aitbc/ai-memory/architecture.md

Architecture Overview

This document records the high-level structure of the AITBC codebase, important conventions, and module responsibilities.

---

Repository Layout

/opt/aitbc/
├── apps/
│   ├── blockchain-node/          # AITBC blockchain node implementation
│   │   └── src/aitbc_chain/
│   │       ├── app.py           # FastAPI app with RPC and WebSocket
│   │       ├── consensus/       # PoA consensus implementation
│   │       ├── database.py      # SQLite DB for chain state
│   │       ├── gossip/          # P2P gossip layer
│   │       ├── mempool.py       # Transaction pool
│   │       ├── models.py        # Chain data models
│   │       └── rpc/             # RPC endpoints
│   │
│   ├── coordinator-api/          # Coordinator service (orchestration)
│   │   └── src/app/
│   │       ├── main.py
│   │       ├── routers/
│   │       │   ├── blockchain.py
│   │       │   ├── marketplace_gpu.py
│   │       │   └── ...
│   │       └── services/
│   │           ├── trading_surveillance.py
│   │           ├── ai_trading_engine.py
│   │           ├── advanced_analytics.py
│   │           ├── ai_surveillance.py
│   │           └── regulatory_reporting.py
│   │
│   └── wallet-daemon/            # Wallet management daemon
│       └── src/...
│
├── cli/
│   └── aitbc_cli/
│       ├── main.py              # Click entrypoint
│       ├── commands/            # CLI command groups
│       │   ├── surveillance.py
│       │   ├── ai_trading.py
│       │   ├── advanced_analytics.py
│       │   ├── regulatory.py
│       │   ├── compliance.py
│       │   ├── ai_surveillance.py
│       │   └── ai.py            # AI provider commands
│       └── core/                # CLI core logic
│           └── chain_manager.py
│
├── packages/py/
│   ├── aitbc-core/              # Core utilities (logging, crypto helpers)
│   │   └── src/aitbc/logging/
│   ├── aitbc-sdk/               # Blockchain SDK
│   └── aitbc-agent-sdk/         # Agent-specific SDK (README added 2026-03-15)
│
├── genesis_*.yaml                # Genesis configurations for different chains
├── pyproject.toml                # Root project (CLI packages)
└── README.md                     # Top-level project readme

---

Important Conventions

Import Structure

• Service modules live under apps/coordinator-api/src/app/services/. They should not rely on relative imports within the app package; instead, use absolute imports from the Python path when the package is installed. CLI commands add the service directory to sys.path at runtime.

• CLI commands are organized as Click command groups. Avoid naming command functions the same as imported service functions to prevent shadowing. Use aliasing if needed (generate_sar as generate_sar_svc).

• Package dependencies: The root pyproject.toml builds the aitbc-cli package. Service-specific dependencies should be listed there if used by CLI, or in separate service package configs.

Stability Rings

We classify code by stability to guide review thresholds:

Ring	Contents	Threshold	Approvals
0 (Core)	aitbc-core, aitbc-sdk	>0.90	2
1 (Platform)	apps/ (coordinator-api, blockchain-node, wallet-daemon)	>0.80	1
2 (Application)	cli/, analytics, tools	>0.70	1
3 (Experimental)	experiments/, test-only PRs	>0.50	1

Ring detection is based on changed file paths; test-only PRs automatically downgrade to Ring 3.

Branch Naming

• Work branches: <agent-name>/<issue-number>-<short-description> (e.g., aitbc/7-add-tests)
• Claim branches: claim/<issue-number> (used as distributed locks)
• Do not push directly to main.

Pull Request Workflow

1. Branch created from main
2. Implement changes; ensure tests pass
3. Push branch; create PR via API or web
4. Auto-request review from the other agent (using create_pr.py)
5. Sibling agent reviews using auto_review.py or manually
6. Merge after approval and CI green
7. Delete claim branch

---

Key Modules

Blockchain Node (aitbc_chain)

• Uses FastAPI for RPC
• PoA consensus; proposer identity from .env
• Database: SQLite files stored in node data directory
• Health endpoint: GET /health
• RPC methods: /rpc/*

Coordinator API

• Manages AI agents, compute providers, marketplace GPU scheduling
• Services implement business logic (trading, surveillance, analytics, regulatory)
• Exposes REST endpoints for interaction

CLI

• Unified command-line interface for all operations
• Command groups: surveillance, ai-trading, advanced-analytics, regulatory, compliance, ai-surveillance, wallet, chain, etc.
• Uses shared service modules from coordinator-api via path injection

---

End of architecture notes.