825f157749
- Bump minimum Python version from 3.11 to 3.13 across all apps - Add Python 3.11-3.13 test matrix to CLI workflow - Document Python 3.11+ requirement in .env.example - Fix Starlette Broadcast removal with in-process fallback implementation - Add _InProcessBroadcast class for tests when Starlette Broadcast is unavailable - Refactor API key validators to read live settings instead of cached values - Update database models with explicit
237 lines
11 KiB
Markdown
237 lines
11 KiB
Markdown
# 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/`)
|
|
|
|
| Path | Status | Notes |
|
|
|------|--------|-------|
|
|
| `contracts/ZKReceiptVerifier.sol` | ✅ Active | ZK receipt verifier contract |
|
|
| `contracts/Groth16Verifier.sol` | ✅ Active | Groth16 verifier stub (snarkjs-replaceable) |
|
|
| `contracts/scripts/security-analysis.sh` | ✅ Active | Slither + Mythril analysis script |
|
|
| `contracts/scripts/deploy-testnet.sh` | ✅ Active | Testnet deployment script |
|
|
|
|
---
|
|
|
|
## 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/`.
|