aitbc/ai-memory/architecture/infrastructure.md

Infrastructure

This document describes the physical and logical infrastructure supporting the AITBC development environment.

Host Environment

Development Hosts

• Primary host: aitbc1 machine (this workspace)
• Sibling host: aitbc machine (remote)
• Both run Linux (x64)
• SSH access configured for repository access

Repository (Gitea)

• URL: https://gitea.bubuit.net/oib/aitbc
• Worktree: /root/.openclaw/workspace
• Primary branch: main
• Feature branches: <agent>/<issue>-<slug> or infrastructure-*
• Issue labels: task, bug, feature, refactor, security, good-first-task-for-agent
• Protected branches: main requires PR and CI passing (ideally)

Service Architecture

Coordinator API

• Path: apps/coordinator-api/
• Runtime: Uvicorn/FastAPI
• Port: 8000
• Database: SQLite (data/coordinator.db)
• Startup: python -m app.main within venv
• Responsibilities: job marketplace, provider registry, job lifecycle

Blockchain Node (Brother Chain)

• Path: apps/blockchain-node/
• Runtime: Uvicorn/FastAPI + custom consensus
• Port: 8006 (RPC), 8005 (P2P gossip)
• Database: SQLite (data/chain.db)
• Wallet daemon port: 8015
• Startup: scripts/devnet_up.sh or systemd service
• Responsibilities: ledger, transactions, consensus, wallet management

AI Provider Daemon

• Path: (provided by agents; CLI aitbc ai serve)
• Runtime: FastAPI + Ollama
• Port: 8008 (configurable)
• Model: qwen3:8b (default)
• Responsibilities: serve inference, accept payment, report results

Redis

• Package: redis-server
• Used for: broadcast/pub-sub messaging (dev only)
• Configuration: default local instance
• Not production hardened (no auth/TLS by default)

Build & Package Infrastructure

Monorepo Layout

/root/.openclaw/workspace/
├── packages/py/        # Python packages (aitbc-core, aitbc-crypto, etc.)
├── apps/               # Service applications
│   ├── coordinator-api/
│   └── blockchain-node/
├── cli/                # Main CLI tool
├── scripts/            # Automation scripts (claim-task, monitor-prs)
├── memory/             # Legacy per-agent hourly logs (migrating to ai-memory/)
├── ai-memory/          # Structured memory (canonical)
└── MEMORY.md           # Curated long-term notes (to be migrated)

Build Tools

• Poetry: for package dependency management (pyproject.toml)
• pip (editable): pip install -e ./package
• pytest: test runner
• Gitea Actions: CI pipeline (runs tests on PRs)

Python Dependencies (Key)

• FastAPI, Uvicorn (services)
• SQLAlchemy/SQLModel (ORM)
• aiosqlite (async SQLite)
• aiohttp, websockets, pydantic
• Redis client (development)
• See pyproject.toml files for exact versions

Automation & Coordination Scripts

scripts/claim-task.py

• Polls unassigned issues with eligible labels
• Uses atomic Git branch creation as distributed lock
• Creates work branch <agent>/<issue>-<slug>
• Runs every 5 minutes (cron)

scripts/monitor-prs.py

• Monitors open PRs
• Auto-requests review from sibling on own PRs
• For sibling's PRs: validates syntax, auto-approves if valid per Ring rules
• Monitors CI status; reports failures
• Cleans up claim branches on merge/close
• Runs every 10 minutes (cron)

Cron Configuration

*/5 * * * * cd /root/.openclaw/workspace && /usr/bin/python scripts/claim-task.py
*/10 * * * * cd /root/.openclaw/workspace && /usr/bin/python scripts/monitor-prs.py

Configuration Management

Port Allocations (Standard)

• Coordinator API: 8000
• Blockchain RPC: 8006
• Blockchain P2P: 8005
• Wallet Daemon: 8015
• AI Provider: 8008

Environment Variables

Services may use:

• DATABASE_URL (default: sqlite+aiosqlite:///data/app.db)
• REDIS_URL (default: redis://localhost)
• LOG_LEVEL (default: INFO)
• HOST, PORT (per-service)

Secrets

• Gitea tokens stored in environment (not in repo)
• Wallet keys stored in encrypted wallet files (user-managed)
• No hardcoded credentials in code

CI/CD Pipeline

1. PR opened → Gitea Actions trigger
2. Install dependencies (cached)
3. Run linters (if configured)
4. Run test suites for affected packages
5. Report status to PR
6. Block merge if CI failing

Monitoring & Diagnostics

• Health endpoints: GET /health on each service
• Coordinator jobs: GET /v1/jobs for active jobs
• Blockchain status: GET /status for chain info
• Logs: stdout/stderr captured by systemd or Docker

Network Considerations

• Development: all services on localhost or local network
• Future production: need TLS for Redis, firewall rules, authentication
• P2P gossip over internet requires hole-packing or relay servers
• Port mapping must be configured on routers for external access

Backup & Resilience

• SQLite databases stored under data/; should be backed up periodically
• Git repository serves as code backup; push to remote Gitea
• Wallet keys: user responsibility to back up mnemonic/private keys

Known Issues

• Docker Compose detection: some systems only have docker compose (v2) not docker-compose (v1)
• Absolute paths in test scripts (need correction to project-relative)
• Starlette Broadcast removed in 0.38 → must pin <0.38
• Redis pub/sub not suitable for internet without auth/TLS (dev-only solution)