aitbc/ai-memory/architecture/system-overview.md

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