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