# AITBC Repository File Structure

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

Last updated: 2026-02-22

---

## Whitelist ✅ (Active & Essential)

### Core Applications (`apps/`)

| Path | Status | Notes |
|------|--------|-------|
| `apps/coordinator-api/` | ✅ Active | Main API service, recently updated (Feb 2026) |
| `apps/explorer-web/` | ✅ Active | Blockchain explorer, recently updated |
| `apps/wallet-daemon/` | ✅ Active | Wallet service, deployed in production |
| `apps/trade-exchange/` | ✅ Active | Bitcoin exchange, deployed |
| `apps/zk-circuits/` | ✅ Active | ZK proof circuits, 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/cli/test_cli_integration.py` | ✅ Active | 24 CLI → live coordinator integration tests (Feb 2026) |

### Scripts (`scripts/`)

| Path | Status | Notes |
|------|--------|-------|
| `scripts/aitbc-cli.sh` | ✅ Active | Main CLI tool, heavily used |
| `scripts/gpu/gpu_miner_host.py` | ✅ Active | Production GPU miner |
| `scripts/gpu/gpu_miner_host_wrapper.sh` | ✅ Active | Systemd wrapper |
| `scripts/deploy/` | ✅ Active | Deployment scripts |
| `scripts/service/` | ✅ Active | Service management |
| `scripts/dev_services.sh` | ✅ Active | Local development |
| `scripts/testing/` | ✅ Active | Test scripts (moved from root, 13 files) |

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

| Path | Status | Notes |
|------|--------|-------|
| `infra/nginx/` | ✅ Active | Production nginx configs |
| `systemd/aitbc-host-gpu-miner.service` | ✅ Active | Production service |
| `systemd/coordinator-api.service` | ✅ Active | Production service |

### 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 (restructured) |
| `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 |

### 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-utils/`)

| Path | Status | Notes |
|------|--------|-------|
| `dev-utils/` | ✅ Active | Development utilities (newly created) |
| `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, streamlined for idea/overview |
| `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` |

---

### 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 ✅** | ~60 items | Active and maintained |
| **Placeholders 📋** | 12 folders | All complete (Stage 19) |
| **Debug prints** | 17 statements | Replace with logger |

---

## Folder Structure Recommendation

```
aitbc/
├── apps/                    # Core applications
│   ├── coordinator-api/     # ✅ Keep
│   ├── explorer-web/        # ✅ Keep
│   ├── marketplace-web/     # ✅ Keep
│   ├── trade-exchange/      # ✅ Keep
│   ├── wallet-daemon/       # ✅ Keep
│   ├── blockchain-node/     # ✅ Keep
│   └── zk-circuits/         # ✅ Keep
├── cli/                     # ✅ CLI tools
├── contracts/               # ✅ Smart contracts
├── docs/                    # ✅ Numbered documentation structure
│   ├── 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
├── 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/                 # ✅ Keep - organized by purpose
├── systemd/                 # ✅ Systemd service units
├── tests/                   # ✅ Test suites
├── website/                 # ✅ Public website and HTML docs
├── dev-utils/               # ✅ Development utilities
├── data/                    # ✅ Runtime data (gitignored)
└── .windsurf/               # ✅ Keep
```

This structure represents the current clean state of the AITBC repository with all essential components organized for optimal development and deployment workflows.

**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/`.