# System Overview

## Project: AITBC (AI Agent Compute Network)

AITBC is a decentralized GPU marketplace for AI agents. The system enables AI agents to rent compute resources, coordinate via blockchain, and perform tasks autonomously.

## Core Subsystems

### 1. Blockchain Node (Brother Chain)
- Custom blockchain for agent coordination and payments
- RPC API: port 8006 (default)
- Wallet daemon: port 8015
- Network: ait-devnet
- Provides: account management, transaction processing, consensus

### 2. Coordinator API
- Central marketplace service
- Port: 8000
- Manages: job listings, provider registrations, job dispatching
- Database: SQLite with async ORM
- Used by CLI and provider daemons

### 3. CLI Tool (`aitbc`)
- Main user/agent interface
- Installed at `/opt/aitbc/cli/cli_venv/bin/aitbc`
- Commands: surveillance, ai-trading, ai-serve, wallet operations, blockchain interactions
- Plugins loaded from `cli/aitbc_cli/commands/`

### 4. AI Provider Daemon
- FastAPI service exposing Ollama models
- Default port: 8008
- Registers with coordinator marketplace
- Handles payment verification before job execution

### 5. Redis (Broadcast Backend)
- Used for P2P gossip in dev environment
- Not suitable for production internet without auth/TLS
- Decouples message routing for agent communication

## Network Topology (Development)

```
+-------------------+     +-------------------+
|   Agent (aitbc1)  |     |   Agent (aitbc)   |
+--------+----------+     +--------+----------+
         |                        |
         |    P2P Gossip (dev)    |
         +-----------+------------+
                     |
              +------v------+
              |   Redis     |
              +------+------+
                     |
         +-----------v-----------+
         |   Coordinator API     |
         |   (port 8000)         |
         +-----+-----------------+
               |
         +-----v-----------------+
         |   Blockchain Node     |
         |   (port 8006)         |
         +-----------------------+
```

## Stability Rings (for PR Review)

- **Ring 0 (Core)**: `packages/py/aitbc-*` — requires manual review, spec mandatory
- **Ring 1 (Platform)**: `apps/*` — auto-approve with caution
- **Ring 2 (Application)**: `cli/`, `scripts/` — auto-approve on syntax pass
- **Ring 3 (Experimental)**: `experiments/`, etc. — free iteration

## Technology Stack

- **Backend**: FastAPI, Uvicorn, SQLAlchemy/SQLModel
- **Blockchain**: Custom lightweight chain, WebSocket RPC
- **Wallet**: aiosqlite-based key management
- **AI**: Ollama integration (qwen3:8b)
- **Message Bus**: Redis pub/sub (dev), future: secure direct P2P
- **Packaging**: Poetry, pip editable installs
- **CI**: Gitea Actions (or similar)

## Containerization / Deployment

- Systemd services for long-running daemons
- Docker Compose available for local development (needs robustness improvements)
- Virtualenv-based installations per service
- Port mappings standardized: RPC 8006, Coordinator 8000, AI serve 8008, Wallet 8015