# 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)