# Architecture Overview

This document describes the high-level structure of the AITBC project for agents implementing changes.

## Rings of Stability

The codebase is divided into layers with different change rules:

- **Ring 0 (Core)**: `packages/py/aitbc-core/`, `packages/py/aitbc-sdk/`
  - Spec required, high confidence threshold (>0.9), two approvals
- **Ring 1 (Platform)**: `apps/coordinator-api/`, `apps/blockchain-node/`
  - Spec recommended, confidence >0.8
- **Ring 2 (Application)**: `cli/`, `apps/analytics/`
  - Normal PR, confidence >0.7
- **Ring 3 (Experimental)**: `experiments/`, `playground/`
  - Fast iteration allowed, confidence >0.5

## Key Subsystems

### Coordinator API (`apps/coordinator-api/`)
- Central orchestrator for AI agents and compute marketplace
- Exposes REST API and manages provider registry, job dispatch
- Services live in `src/app/services/` and are imported via `app.services.*`
- Import pattern: add `apps/coordinator-api/src` to `sys.path`, then `from app.services import X`

### CLI (`cli/aitbc_cli/`)
- User-facing command interface built with Click
- Bridges to coordinator-api services using proper package imports (no hardcoded paths)
- Located under `commands/` as separate modules: surveillance, ai_trading, ai_surveillance, advanced_analytics, regulatory, enterprise_integration

### Blockchain Node (Brother Chain) (`apps/blockchain-node/`)
- Minimal asset-backed blockchain for compute receipts
- PoA consensus, transaction processing, RPC API
- Devnet: RPC on 8026, health on `/health`, gossip backend memory
- Configuration in `.env`; genesis generated by `scripts/make_genesis.py`

### Packages
- `aitbc-core`: logging utilities, base classes (Ring 0)
- `aitbc-sdk`: Python SDK for interacting with Coordinator API (Ring 0)
- `aitbc-agent-sdk`: agent framework; `Agent.create()`, `ComputeProvider`, `ComputeConsumer` (Ring 0)
- `aitbc-crypto`: cryptographic primitives (Ring 0)

## Conventions

- Branches: `<agent-name>/<issue-number>-<short-description>`
- Claim locks: `claim/<issue>` (short-lived)
- PR titles: imperative mood, reference issue with `Closes #<issue>`
- Tests: use pytest; aim for >80% coverage in modified modules
- CI: runs on Python 3.11, 3.12; goal is to support 3.13