aitbc/docs/6_architecture/8_codebase-structure.md

AITBC Codebase Structure

Monorepo layout for the AI Token Blockchain platform.

Top-Level Overview

aitbc/
├── apps/                    # Core microservices and web applications
├── assets/                  # Shared frontend assets (CSS, JS, fonts)
├── cli/                     # Command-line interface tools
├── contracts/               # Solidity smart contracts (standalone)
├── docs/                    # Markdown documentation (10 numbered sections)
├── extensions/              # Browser extensions (Firefox wallet)
├── infra/                   # Infrastructure configs (nginx, k8s, terraform, helm)
├── packages/                # Shared libraries and SDKs
├── plugins/                 # Plugin integrations (Ollama)
├── scripts/                 # All scripts, organized by purpose
│   ├── blockchain/          # Genesis, proposer, mock chain, testnet
│   ├── ci/                  # CI/CD pipeline scripts
│   ├── deploy/              # Container and service deployment (gitignored)
│   ├── dev/                 # Dev tools, local services, OpenAPI gen
│   ├── examples/            # Usage examples and simulation scripts
│   ├── gpu/                 # GPU miner setup and management (gitignored)
│   ├── ops/                 # Coordinator proxy, remote tunnel
│   ├── service/             # Service management (gitignored)
│   └── test/                # Integration and verification scripts
├── systemd/                 # Systemd service unit files
├── tests/                   # Pytest test suites (unit, integration, e2e, security, load)
├── website/                 # Public-facing website and HTML documentation
├── .gitignore
├── .editorconfig
├── LICENSE                  # MIT License
├── pyproject.toml           # Python project configuration
├── pytest.ini               # Pytest settings and markers
└── README.md

---

apps/ — Core Applications

blockchain-node

Full blockchain node implementation with PoA consensus, gossip relay, mempool, RPC API, WebSocket support, and observability dashboards.

apps/blockchain-node/
├── src/aitbc_chain/
│   ├── app.py               # FastAPI application
│   ├── main.py              # Entry point
│   ├── config.py            # Node configuration
│   ├── database.py          # Chain storage
│   ├── models.py            # Block/Transaction models
│   ├── mempool.py           # Transaction mempool
│   ├── metrics.py           # Prometheus metrics
│   ├── logger.py            # Structured logging
│   ├── consensus/poa.py     # Proof-of-Authority consensus
│   ├── gossip/              # P2P gossip protocol (broker, relay)
│   ├── observability/       # Dashboards and exporters
│   └── rpc/                 # JSON-RPC router and WebSocket
├── scripts/                 # Genesis creation, key generation, benchmarks
├── tests/                   # Unit tests (models, gossip, WebSocket, observability)
└── pyproject.toml

coordinator-api

Central job coordination API with marketplace, payments, ZK proofs, multi-tenancy, and governance.

apps/coordinator-api/
├── src/app/
│   ├── main.py              # FastAPI entry point
│   ├── config.py            # Configuration
│   ├── database.py          # Database setup
│   ├── deps.py              # Dependency injection
│   ├── exceptions.py        # Custom exceptions
│   ├── logging.py           # Logging config
│   ├── metrics.py           # Prometheus metrics
│   ├── domain/              # Domain models (job, miner, payment, user, marketplace, gpu_marketplace)
│   ├── models/              # DB models (registry, confidential, multitenant, services)
│   ├── routers/             # API endpoints (admin, client, miner, marketplace, payments, governance, exchange, explorer, ZK)
│   ├── services/            # Business logic (jobs, miners, payments, receipts, ZK proofs, encryption, HSM, blockchain, bitcoin wallet)
│   ├── storage/             # Database adapters (SQLite, PostgreSQL)
│   ├── middleware/          # Tenant context middleware
│   ├── repositories/        # Data access layer
│   └── schemas/             # Pydantic schemas
├── aitbc/settlement/        # Cross-chain settlement (LayerZero bridge)
├── migrations/              # SQL migrations (schema, indexes, data, payments)
├── scripts/                 # PostgreSQL migration scripts
├── tests/                   # API tests (jobs, marketplace, ZK, receipts, miners)
└── pyproject.toml

blockchain-explorer

Agent-first blockchain explorer built with Python FastAPI and built-in HTML interface.

apps/blockchain-explorer/
├── main.py                   # FastAPI application entry
├── systemd service           # Production service file
└── EXPLORER_MERGE_SUMMARY.md # Architecture documentation

marketplace-web

GPU compute marketplace frontend built with TypeScript and Vite.

apps/marketplace-web/
├── src/
│   ├── main.ts              # Application entry
│   ├── lib/                 # API client and auth
│   └── style.css            # Styles
├── public/                  # Mock data (offers, stats)
├── vite.config.ts
└── tsconfig.json

wallet-daemon

Wallet service with receipt verification and ledger management.

apps/wallet-daemon/
├── src/app/
│   ├── main.py              # FastAPI entry point
│   ├── settings.py          # Configuration
│   ├── ledger_mock/         # Mock ledger with PostgreSQL adapter
│   └── receipts/            # Receipt verification service
├── scripts/                 # PostgreSQL migration
├── tests/                   # Wallet API and receipt tests
└── pyproject.toml

trade-exchange

Bitcoin/AITBC trading exchange with order book, price ticker, and admin panel.

apps/trade-exchange/
├── server.py                # WebSocket price server
├── simple_exchange_api.py   # Exchange REST API (SQLite)
├── simple_exchange_api_pg.py # Exchange REST API (PostgreSQL)
├── exchange_api.py          # Full exchange API
├── bitcoin-wallet.py        # Bitcoin wallet integration
├── database.py              # Database layer
├── build.py                 # Production build script
├── index.html               # Exchange frontend
├── admin.html               # Admin panel
└── scripts/                 # PostgreSQL migration

pool-hub

Mining pool management with job matching, miner scoring, and Redis caching.

apps/pool-hub/
├── src/
│   ├── app/                 # Legacy app structure (routers, registry, scoring)
│   └── poolhub/             # Current app (routers, models, repositories, services, Redis)
├── migrations/              # Alembic migrations
└── tests/                   # API and repository tests

zk-circuits

Zero-knowledge proof circuits for receipt verification.

apps/zk-circuits/
├── circuits/receipt.circom  # Circom circuit definition
├── generate_proof.js        # Proof generation
├── test.js                  # Circuit tests
└── benchmark.js             # Performance benchmarks

---

packages/ — Shared Libraries

packages/
├── py/
│   ├── aitbc-crypto/        # Cryptographic primitives (signing, hashing, key derivation)
│   └── aitbc-sdk/           # Python SDK for coordinator API (receipt fetching/verification)
└── solidity/
    └── aitbc-token/         # ERC-20 AITBC token contract with Hardhat tooling

---

scripts/ — Operations

scripts/
├── aitbc-cli.sh             # Main CLI entry point
├── deploy/                  # Deployment scripts (container, remote, blockchain, explorer, exchange, nginx)
├── gpu/                     # GPU miner management (host miner, registry, exchange integration)
├── service/                 # Service lifecycle (start, stop, diagnose, fix)
├── testing/                 # Test runners and verification scripts
├── test/                    # Individual test scripts (coordinator, GPU, explorer)
├── ci/                      # CI pipeline scripts
├── ops/                     # Operational scripts (systemd install)
└── dev/                     # Development tools (WebSocket load test)

---

infra/ — Infrastructure

infra/
├── nginx/                   # Nginx configs (reverse proxy, local, production)
├── k8s/                     # Kubernetes manifests (backup, cert-manager, network policies, sealed secrets)
├── helm/                    # Helm charts (coordinator deployment, values per environment)
├── terraform/               # Terraform modules (Kubernetes cluster, environments: dev/staging/prod)
└── scripts/                 # Infra scripts (backup, restore, chaos testing)

---

tests/ — Test Suites

tests/
├── cli/                     # CLI tests (141 unit + 24 integration tests)
│   ├── test_cli_integration.py  # CLI → live coordinator integration tests
│   └── test_*.py            # CLI unit tests (admin, auth, blockchain, client, config, etc.)
├── unit/                    # Unit tests (blockchain node, coordinator API, wallet daemon)
├── integration/             # Integration tests (blockchain node, full workflow)
├── e2e/                     # End-to-end tests (user scenarios, wallet daemon)
├── security/                # Security tests (confidential transactions, comprehensive audit)
├── load/                    # Load tests (Locust)
├── conftest.py              # Shared pytest fixtures
└── test_blockchain_nodes.py # Live node connectivity tests

---

website/ — Public Website

website/
├── index.html               # Landing page
├── 404.html                 # Error page
├── docs/                    # HTML documentation (per-component pages, CSS, JS)
├── dashboards/              # Admin and miner dashboards
├── BrowserWallet/           # Browser wallet interface
├── extensions/              # Packaged browser extensions (.zip, .xpi)
└── aitbc-proxy.conf         # Nginx proxy config for website

---

Other Directories

Directory	Purpose
cli/	AITBC CLI package (12 command groups, 90+ subcommands, 141 unit + 24 integration tests, CI/CD, man page, plugins)
plugins/ollama/	Ollama LLM integration (client plugin, miner plugin, service layer)
extensions/	Firefox wallet extension source code
contracts/	Standalone Solidity contracts (ZKReceiptVerifier)
systemd/	Systemd unit files for all AITBC services
docs/	Markdown documentation (10 numbered sections, guides, reference, architecture)
assets/	Shared frontend assets (Tailwind CSS, FontAwesome, Lucide icons, Axios)