# AITBC Repository File Structure

This document describes the current organization and status of files and folders in the repository.

Last updated: 2026-03-25

---

## Whitelist ✅ (Active & Essential)

### Core Applications (`apps/`)

| Path | Status | Notes |
|------|--------|-------|
| `apps/coordinator-api/` | ✅ Active | Main API service, standardized (Mar 2026) |
| `apps/blockchain-explorer/` | ✅ Active | Agent-first blockchain explorer, recently optimized (Mar 2026) |
| `apps/blockchain-node/` | ✅ Active | Blockchain node, standardized (Mar 2026) |
| `apps/trade-exchange/` | ✅ Active | Bitcoin exchange, deployed |
| `apps/marketplace-web/` | ✅ Active | Marketplace frontend, deployed |
| `apps/coordinator-api/src/app/domain/gpu_marketplace.py` | ✅ Active | GPURegistry, GPUBooking, GPUReview SQLModel tables (Feb 2026) |
| `apps/coordinator-api/tests/test_gpu_marketplace.py` | ✅ Active | 22 GPU marketplace tests (Feb 2026) |
| `apps/coordinator-api/tests/test_billing.py` | ✅ Active | 21 billing/usage-tracking tests (Feb 2026) |
| `apps/coordinator-api/tests/conftest.py` | ✅ Active | App namespace isolation for coordinator tests |
| `tests/` | ✅ Active | Test suites (reorganized Mar 2026) |
| `tests/cli/` | ✅ Active | CLI tests (28 files, organized Mar 2026) |
| `tests/integration/` | ✅ Active | Integration tests (28 files, organized Mar 2026) |
| `tests/security/` | ✅ Active | Security tests (5 files, organized Mar 2026) |
| `tests/explorer/` | ✅ Active | Explorer tests (2 files, organized Mar 2026) |
| `tests/websocket/` | ✅ Active | WebSocket tests (2 files, organized Mar 2026) |
| `tests/testing/` | ✅ Active | Performance/testing utilities (25 files, organized Mar 2026) |
| `tests/unit/` | ✅ Active | Unit tests (9 files, organized Mar 2026) |
| `tests/e2e/` | ✅ Active | End-to-end tests (26 files, organized Mar 2026) |
| `tests/docs/` | ✅ Active | Test documentation (5 files, organized Mar 2026) |
| `tests/conftest.py` | ✅ Active | Test configuration (root level) |
| `tests/test_runner.py` | ✅ Active | Test runner (root level) |

### Scripts (`scripts/`)

| Path | Status | Notes |
|------|--------|-------|
| `scripts/aitbc-cli.sh` | ✅ Active | Main CLI tool, heavily used |
| `scripts/dev/gpu/gpu_miner_host.py` | ✅ Active | Production GPU miner, standardized (Mar 2026) |
| `scripts/services/` | ✅ Active | Service files (5 FastAPI services, moved Mar 2026) |
| `scripts/deployment/` | ✅ Active | Deployment scripts (35 files, organized Mar 2026) |
| `scripts/testing/` | ✅ Active | Test scripts (20 files, organized Mar 2026) |
| `scripts/monitoring/` | ✅ Active | Monitoring scripts (3 files, organized Mar 2026) |
| `scripts/development/` | ✅ Active | Development scripts (6 files, organized Mar 2026) |
| `scripts/utils/` | ✅ Active | Utility scripts (40 files, organized Mar 2026) |
| `scripts/manage-services.sh` | ✅ Active | Main service management script (updated Mar 2026) |
| `scripts/README.md` | ✅ Active | Scripts documentation |
| `scripts/deploy/` | ✅ Active | Legacy deployment scripts (27 files) |
| `scripts/gpu/` | ✅ Active | GPU service scripts (9 files, moved to services/) |

### Infrastructure (`infra/`, `systemd/`)

| Path | Status | Notes |
|------|--------|-------|
| `infra/nginx/` | ✅ Active | Production nginx configs |
| `systemd/` | ✅ Active | All 19+ standardized service files (Mar 2026) |
| `systemd/aitbc-gpu-miner.service` | ✅ Active | Standardized GPU miner service |
| `systemd/aitbc-multimodal-gpu.service` | ✅ Active | Renamed GPU multimodal service (Mar 2026) |
| `systemd/aitbc-blockchain-node.service` | ✅ Active | Standardized blockchain node |
| `systemd/aitbc-blockchain-rpc.service` | ✅ Active | Standardized RPC service |
| `systemd/aitbc-coordinator-api.service` | ✅ Active | Standardized coordinator API |
| `systemd/aitbc-wallet.service` | ✅ Active | Fixed and standardized (Mar 2026) |
| `systemd/aitbc-loadbalancer-geo.service` | ✅ Active | Fixed and standardized (Mar 2026) |
| `systemd/aitbc-marketplace-enhanced.service` | ✅ Active | Fixed and standardized (Mar 2026) |

### Website (`website/`)

| Path | Status | Notes |
|------|--------|-------|
| `website/docs/` | ✅ Active | HTML documentation, recently refactored |
| `website/docs/css/docs.css` | ✅ Active | Shared CSS (1232 lines) |
| `website/docs/js/theme.js` | ✅ Active | Theme toggle |
| `website/index.html` | ✅ Active | Main website |
| `website/dashboards/` | ✅ Active | Admin/miner dashboards |

### Documentation (`docs/`)

| Path | Status | Notes |
|------|--------|-------|
| `docs/1_project/` | ✅ Active | Project management docs (updated Mar 2026) |
| `docs/1_project/aitbc.md` | ✅ Active | Secondary server deployment guide (updated Mar 2026) |
| `docs/1_project/aitbc1.md` | ✅ Active | Primary server deployment guide (updated Mar 2026) |
| `docs/1_project/3_infrastructure.md` | ✅ Active | Infrastructure documentation (updated Mar 2026) |
| `docs/infrastructure/` | ✅ Active | Infrastructure documentation (Mar 2026) |
| `docs/infrastructure/codebase-update-summary.md` | ✅ Active | Comprehensive standardization summary (Mar 2026) |
| `docs/DOCS_WORKFLOW_COMPLETION_SUMMARY.md` | ✅ Active | Documentation updates completion (Mar 2026) |
| `docs/0_getting_started/` | ✅ Active | Getting started guides |
| `docs/2_clients/` | ✅ Active | Client documentation |
| `docs/3_miners/` | ✅ Active | Miner documentation |
| `docs/4_blockchain/` | ✅ Active | Blockchain documentation |
| `docs/5_reference/` | ✅ Active | Reference materials |
| `docs/6_architecture/` | ✅ Active | Architecture documentation |
| `docs/7_deployment/` | ✅ Active | Deployment guides |
| `docs/8_development/` | ✅ Active | Development documentation |
| `docs/9_security/` | ✅ Active | Security documentation |
| `docs/10_plan/` | ✅ Active | Planning documentation, updated (Mar 2026) |
| `docs/10_plan/99_currentissue.md` | ✅ Active | Current issues with standardization completion (Mar 2026) |
| `.windsurf/workflows/` | ✅ Active | Development workflows (Mar 2026) |
| `.windsurf/workflows/aitbc-services-monitoring.md` | ✅ Active | Services monitoring workflow (Mar 2026) |

### CLI Tools (`cli/`)

| Path | Status | Notes |
|------|--------|-------|
| `cli/aitbc_cli/commands/client.py` | ✅ Active | Client CLI (submit, batch-submit, templates, history) |
| `cli/aitbc_cli/commands/miner.py` | ✅ Active | Miner CLI (register, earnings, capabilities, concurrent) |
| `cli/aitbc_cli/commands/wallet.py` | ✅ Active | Wallet CLI (balance, staking, multisig, backup/restore) |
| `cli/aitbc_cli/commands/auth.py` | ✅ Active | Auth CLI (login, tokens, API keys) |
| `cli/aitbc_cli/commands/blockchain.py` | ✅ Active | Blockchain queries |
| `cli/aitbc_cli/commands/marketplace.py` | ✅ Active | GPU marketplace operations |
| `cli/aitbc_cli/commands/admin.py` | ✅ Active | System administration, audit logging |
| `cli/aitbc_cli/commands/config.py` | ✅ Active | Configuration, profiles, encrypted secrets |
| `cli/aitbc_cli/commands/monitor.py` | ✅ Active | Dashboard, metrics, alerts, webhooks |
| `cli/aitbc_cli/commands/simulate.py` | ✅ Active | Test simulation framework |
| `cli/aitbc_cli/plugins.py` | ✅ Active | Plugin system for custom commands |
| `cli/aitbc_cli/main.py` | ✅ Active | CLI entry point (12 command groups) |
| `cli/man/aitbc.1` | ✅ Active | Man page |
| `cli/aitbc_shell_completion.sh` | ✅ Active | Shell completion script |
| `cli/test_ollama_gpu_provider.py` | ✅ Active | GPU testing |
| `.github/workflows/cli-tests.yml` | ✅ Active | CI/CD for CLI tests (Python 3.11/3.12/3.13) |

### Home Scripts (`home/`)

| Path | Status | Notes |
|------|--------|-------|
| `home/client/` | ✅ Active | Client test scripts |
| `home/miner/` | ✅ Active | Miner test scripts |
| `home/quick_job.py` | ✅ Active | Quick job submission |
| `home/simple_job_flow.py` | ✅ Active | Job flow testing |

### Plugins (`plugins/`)

| Path | Status | Notes |
|------|--------|-------|
| `plugins/ollama/` | ✅ Active | Ollama integration |

### Development Utilities (`dev/`)

| Path | Status | Notes |
|------|--------|-------|
| `dev/` | ✅ Active | Development environment (reorganized, Mar 2026) |
| `dev/cli/` | ✅ Active | CLI development environment (moved from cli-dev, Mar 2026) |
| `dev/scripts/` | ✅ Active | Development scripts (79 Python files) |
| `dev/cache/` | ✅ Active | Development cache files |
| `dev/env/` | ✅ Active | Environment configurations |
| `dev/multi-chain/` | ✅ Active | Multi-chain development files |
| `dev/tests/` | ✅ Active | Development test files |

### Development Utilities (`dev-utils/`)

| Path | Status | Notes |
|------|--------|-------|
| `dev-utils/` | ✅ Active | Development utilities (legacy) |
| `dev-utils/aitbc-pythonpath.pth` | ✅ Active | Python path configuration |

### Data Directory (`data/`)

| Path | Status | Notes |
|------|--------|-------|
| `data/` | ✅ Active | Runtime data directory (gitignored) |
| `data/coordinator.db` | ⚠️ Runtime | SQLite database, moved from root |

### Root Files

| Path | Status | Notes |
|------|--------|-------|
| `README.md` | ✅ Active | Project readme, updated with standardization badges (Mar 2026) |
| `LICENSE` | ✅ Active | License file |
| `.gitignore` | ✅ Active | Recently updated (145 lines) |
| `pyproject.toml` | ✅ Active | Python project config |
| `.editorconfig` | ✅ Active | Editor config |
| `pytest.ini` | ✅ Active | Pytest configuration with custom markers |
| `CLEANUP_SUMMARY.md` | ✅ Active | Documentation of directory cleanup |
| `test_block_import.py` | ✅ Resolved | Moved to `tests/verification/test_block_import.py` |

### Backup Directory (`backup/`)

| Path | Status | Notes |
|------|--------|-------|
| `backup/` | ✅ Active | Backup archive storage (organized, Mar 2026) |
| `backup/explorer_backup_20260306_162316.tar.gz` | ✅ Active | Explorer TypeScript source backup (15.2 MB) |
| `backup/BACKUP_INDEX.md` | ✅ Active | Backup inventory and restoration instructions |

---

### Blockchain Node (`apps/blockchain-node/`)

| Path | Status | Notes |
|------|--------|-------|
| `apps/blockchain-node/` | ✅ Active | Blockchain node with PoA, mempool, sync (Stage 20/21/22 complete) |
| `apps/blockchain-node/src/aitbc_chain/mempool.py` | ✅ Active | Dual-backend mempool (memory + SQLite) |
| `apps/blockchain-node/src/aitbc_chain/sync.py` | ✅ Active | Chain sync with conflict resolution |
| `apps/blockchain-node/src/aitbc_chain/consensus/poa.py` | ✅ Active | PoA proposer with circuit breaker |
| `apps/blockchain-node/src/aitbc_chain/app.py` | ✅ Active | FastAPI app with rate limiting middleware |
| `apps/blockchain-node/tests/test_mempool.py` | ✅ Active | 27 mempool tests |
| `apps/blockchain-node/tests/test_sync.py` | ✅ Active | 23 sync tests |

### Smart Contracts (`contracts/`) 📜 **EXPANDED**

| Path | Status | Notes |
|------|--------|-------|
| `contracts/contracts/AIPowerRental.sol` | ✅ Active | Handles decentralized GPU/AI compute rentals |
| `contracts/contracts/AITBCPaymentProcessor.sol` | ✅ Active | AITBC token flow and automated settlements |
| `contracts/contracts/DisputeResolution.sol` | ✅ Active | Arbitration for OpenClaw marketplace disputes |
| `contracts/contracts/EscrowService.sol` | ✅ Active | Multi-signature execution escrow locks |
| `contracts/contracts/DynamicPricing.sol` | ✅ Active | Supply/Demand algorithmic pricing |
| `contracts/contracts/PerformanceVerifier.sol` | ✅ Active | On-chain ZK verification of AI inference quality |
| `contracts/contracts/AgentStaking.sol` | ✅ Active | Agent ecosystem reputation staking |
| `contracts/contracts/AgentBounty.sol` | ✅ Active | Crowdsourced task resolution logic |
| `contracts/contracts/ZKReceiptVerifier.sol` | ✅ Active | ZK receipt verifier contract |
| `contracts/contracts/BountyIntegration.sol` | ✅ Active | Cross-contract event handling |
| `contracts/AgentWallet.sol` | ✅ Active | Isolated agent-specific wallets |
| `contracts/AgentMemory.sol` | ✅ Active | IPFS CID anchoring for agent memory |
| `contracts/KnowledgeGraphMarket.sol` | ✅ Active | Shared knowledge graph marketplace |
| `contracts/MemoryVerifier.sol` | ✅ Active | ZK-proof verification for data retrieval |
| `contracts/CrossChainReputation.sol` | ✅ Active | Portable reputation scores |
| `contracts/AgentCommunication.sol` | ✅ Active | Secure agent messaging |
| `contracts/scripts/` | ✅ Active | Hardhat deployment & verification scripts |

---

## Future Placeholders 📋 (Keep - Will Be Populated)

These empty folders are intentional scaffolding for planned future work per the roadmap.

| Path | Status | Roadmap Stage |
|------|--------|---------------|
| `docs/user/guides/` | ✅ Complete | Stage 19 - Documentation (Q1 2026) |
| `docs/developer/tutorials/` | ✅ Complete | Stage 19 - Documentation (Q1 2026) |
| `docs/reference/specs/` | ✅ Complete | Stage 19 - Documentation (Q1 2026) |
| `infra/terraform/environments/staging/` | ✅ Complete | Stage 19 - Infrastructure (Q1 2026) |
| `infra/terraform/environments/prod/` | ✅ Complete | Stage 19 - Infrastructure (Q1 2026) |
| `infra/helm/values/dev/` | ✅ Complete | Stage 19 - Infrastructure (Q1 2026) |
| `infra/helm/values/staging/` | ✅ Complete | Stage 19 - Infrastructure (Q1 2026) |
| `infra/helm/values/prod/` | ✅ Complete | Stage 19 - Infrastructure (Q1 2026) |
| `apps/coordinator-api/migrations/` | ✅ Complete | Stage 19 - Application Components (Q1 2026) |
| `apps/pool-hub/src/app/routers/` | ✅ Complete | Stage 19 - Application Components (Q1 2026) |
| `apps/pool-hub/src/app/registry/` | ✅ Complete | Stage 19 - Application Components (Q1 2026) |
| `apps/pool-hub/src/app/scoring/` | ✅ Complete | Stage 19 - Application Components (Q1 2026) |

---

## Summary Statistics

| Category | Count | Status |
|----------|-------|--------|
| **Whitelist ✅** | ~85 items | Active and maintained (Mar 2026) |
| **Placeholders 📋** | 12 folders | All complete (Stage 19) |
| **Standardized Services** | 19+ services | 100% standardized (Mar 2026) |
| **Development Scripts** | 79 files | Organized in dev/scripts/ (Mar 2026) |
| **Deployment Scripts** | 35 files | Organized in scripts/deploy/ (Mar 2026) |
| **Documentation Files** | 200+ files | Updated and current (Mar 2026) |
| **Backup Archives** | 1+ files | Organized in backup/ (Mar 2026) |
| **Debug prints** | 17 statements | Replace with logger |

## Recent Major Updates (March 2026)

### ✅ Complete Infrastructure Standardization
- **19+ services** standardized to use `aitbc` user and `/opt/aitbc` paths
- **Duplicate services** removed and cleaned up
- **Service naming** conventions improved (e.g., GPU multimodal renamed)
- **All services** operational with 100% health score
- **Automated verification** tools implemented

### ✅ Enhanced Documentation
- **Infrastructure documentation** created and updated
- **Service monitoring workflow** implemented
- **Codebase verification script** developed
- **Project files documentation** updated to reflect current state

### ✅ Improved Organization
- **Development environment** reorganized into `dev/` structure
- **Scripts organized** by purpose (deploy, dev, testing)
- **Workflows documented** for repeatable processes
- **File organization prevention** system implemented

### ✅ Complete Scripts and Tests Organization (March 25, 2026)
- **Scripts organized** by purpose into 6 categories (services, deployment, testing, monitoring, development, utils)
- **Test files organized** by function into 9 categories (cli, integration, security, explorer, websocket, testing, unit, e2e, docs)
- **Service scripts** moved to dedicated `scripts/services/` folder
- **Documentation updated** to reflect new file locations
- **No codebase rewrites** needed - all paths already properly configured

### ✅ Server Architecture Updates (March 25, 2026)
- **aitbc1** established as primary server (https://aitbc1.bubuit.net) with reverse proxy role
- **aitbc** established as secondary server (https://aitbc.bubuit.net) with application services
- **SSH access** simplified to `ssh aitbc` and `ssh aitbc1` (root login, no sudo needed)
- **Deployment guides** updated to reflect new primary/secondary architecture
- **Infrastructure documentation** updated for two-server setup

### ✅ Documentation Standardization (March 25, 2026)
- **All sudo references** removed from systemctl commands (root access)
- **SSH references** updated to use new server names
- **Service paths** updated in documentation to reflect new organization
- **12 documentation files** updated across the codebase
- **Consistent command patterns** applied throughout

### ✅ Explorer Architecture Simplification (March 6, 2026)
- **TypeScript explorer** merged into Python blockchain-explorer
- **Agent-first architecture** strengthened with single service
- **Source code deleted** with proper backup (15.2 MB archive)
- **Documentation updated** across all reference files

---

## Folder Structure Recommendation

```
aitbc/
├── apps/                    # Core applications
│   ├── coordinator-api/     # ✅ Keep - Standardized (Mar 2026)
│   ├── explorer-web/        # ✅ Keep
│   ├── marketplace-web/     # ✅ Keep
│   ├── trade-exchange/      # ✅ Keep
│   ├── blockchain-node/     # ✅ Keep - Standardized (Mar 2026)
│   ├── blockchain-explorer/ # ✅ Keep - Standardized (Mar 2026)
│   └── zk-circuits/         # ✅ Keep
├── cli/                     # ✅ CLI tools
├── contracts/               # ✅ Smart contracts
├── dev/                     # ✅ Development environment (Mar 2026)
│   ├── cli/                 # ✅ CLI development environment (moved Mar 2026)
│   ├── scripts/             # Development scripts (79 files)
│   ├── cache/               # Development cache
│   ├── env/                 # Environment configs
│   ├── multi-chain/         # Multi-chain files
│   └── tests/               # Development tests
├── backup/                  # ✅ Backup archive storage (Mar 2026)
│   ├── explorer_backup_*.tar.gz  # Application backups
│   └── BACKUP_INDEX.md      # Backup inventory
├── docs/                    # ✅ Numbered documentation structure
│   ├── infrastructure/      # ✅ Infrastructure docs (Mar 2026)
│   ├── 0_getting_started/   # Getting started guides
│   ├── 1_project/           # Project management
│   ├── 2_clients/           # Client documentation
│   ├── 3_miners/            # Miner documentation
│   ├── 4_blockchain/        # Blockchain documentation
│   ├── 5_reference/         # Reference materials
│   ├── 6_architecture/      # Architecture documentation
│   ├── 7_deployment/        # Deployment guides
│   ├── 8_development/       # Development documentation
│   ├── 9_security/          # Security documentation
│   └── 10_plan/             # Planning documentation
├── extensions/              # ✅ Browser extensions (Firefox wallet)
├── infra/                   # ✅ Infrastructure configs
│   ├── k8s/                 # Kubernetes manifests
│   └── nginx/               # Nginx configurations
├── packages/                # ✅ Shared libraries
│   ├── py/aitbc-crypto/     # Cryptographic primitives
│   ├── py/aitbc-sdk/        # Python SDK
│   └── solidity/aitbc-token/# ERC-20 token contract
├── plugins/                 # ✅ Keep (ollama)
├── scripts/                 # ✅ Scripts organized by purpose (Mar 2026)
│   ├── services/            # ✅ Service files (5 FastAPI services)
│   ├── deployment/          # ✅ Deployment scripts (35 files)
│   ├── testing/             # ✅ Test scripts (20 files)
│   ├── monitoring/          # ✅ Monitoring scripts (3 files)
│   ├── development/         # ✅ Development scripts (6 files)
│   ├── utils/               # ✅ Utility scripts (40 files)
│   ├── deploy/              # ✅ Legacy deployment scripts (27 files)
│   ├── gpu/                 # ✅ GPU service scripts (9 files)
│   ├── manage-services.sh   # ✅ Main service management script
│   └── README.md            # ✅ Scripts documentation
├── systemd/                 # ✅ Systemd service units (19+ files)
├── tests/                   # ✅ Test suites organized by function (Mar 2026)
│   ├── cli/                 # ✅ CLI tests (28 files)
│   ├── integration/          # ✅ Integration tests (28 files)
│   ├── security/            # ✅ Security tests (5 files)
│   ├── explorer/            # ✅ Explorer tests (2 files)
│   ├── websocket/           # ✅ WebSocket tests (2 files)
│   ├── testing/             # ✅ Performance/testing utilities (25 files)
│   ├── unit/                # ✅ Unit tests (9 files)
│   ├── e2e/                 # ✅ End-to-end tests (26 files)
│   ├── docs/                # ✅ Test documentation (5 files)
│   ├── conftest.py          # ✅ Test configuration
│   └── test_runner.py       # ✅ Test runner
├── website/                 # ✅ Public website and HTML docs
├── dev-utils/               # ✅ Development utilities (legacy)
├── data/                    # ✅ Runtime data (gitignored)
├── .windsurf/               # ✅ Keep - Workflows (Mar 2026)
└── config/                  # ✅ Configuration files
```

This structure represents the current clean state of the AITBC repository with all essential components organized for optimal development and deployment workflows. The March 2026 standardization effort has resulted in:

- **100% service standardization** across all systemd services
- **Complete scripts and tests organization** by purpose and function
- **Updated server architecture** with primary/secondary server setup
- **Enhanced documentation** with comprehensive infrastructure guides
- **Automated verification tools** for maintaining standards
- **Production-ready infrastructure** with all services operational
- **Optimized CLI development** with centralized dev/cli environment
- **Agent-first architecture** with simplified explorer service
- **Comprehensive backup system** with proper git exclusion
- **Standardized SSH access** with root privileges and no sudo requirements

**Note**: Redundant `apps/logs/` directory removed - central `logs/` directory at root level is used for all logging. Redundant `assets/` directory removed - Firefox extension assets are properly organized in `extensions/aitbc-wallet-firefox/`. CLI development environment moved from `cli-dev` to `dev/cli` for better organization. Explorer TypeScript source merged into Python service and backed up.