6.4 KiB
Architectural Decisions
This log records significant architectural decisions made during the AITBC project to prevent re-debating past choices.
Format
- Decision: What was decided
- Date: YYYY-MM-DD
- Context: Why the decision was needed
- Alternatives Considered: Other options
- Reason: Why this option was chosen
- Impact: Consequences (positive and negative)
Decision 1: Stability Rings for PR Review Automation
Date: 2026-03-15
Context: Need to automate PR reviews while maintaining quality. Different parts of the codebase have different risk profiles; a blanket policy would either be too strict or too lax.
Alternatives Considered:
- Manual review for all PRs (high overhead, slow)
- Path-based auto-approve with no ring classification (fragile)
- Single threshold based on file count (too coarse)
Reason: Rings provide clear, scalable zones of trust. Core packages (Ring 0) require human review; lower rings can be automated. This balances safety and velocity.
Impact:
- Reduces review burden for non-critical changes
- Maintains rigor where it matters (packages, blockchain)
- Requires maintainers to understand and respect ring boundaries
- Automated scripts can enforce ring policies consistently
Status: Implemented and documented in architecture/agent-roles.md and architecture/system-overview.md
Decision 2: Hierarchical Memory System (ai-memory/)
Date: 2026-03-15
Context: Existing memory was unstructured (memory/ with hourly files per agent, MEMORY.md notes). This caused information retrieval to be slow, knowledge to be scattered, and made coordination difficult.
Alternatives Considered:
- Single large daily file for all agents (edit conflicts, hard to parse)
- Wiki system (external dependency, complexity)
- Tag-based file system (ad-hoc, hard to enforce)
Reason: A structured hierarchy with explicit layers (daily, architecture, decisions, failures, knowledge, agents) aligns with how agents need to consume information. Clear protocols for read/write operations improve consistency.
Impact:
- Agents have a predictable memory layout
- Faster recall through organized documents
- Reduces hallucinations by providing reliable sources
- Encourages documentation discipline (record decisions, failures)
Status: Implemented; this file is part of it.
Decision 3: Distributed Task Claiming via Atomic Git Branches
Date: 2026-03-15
Context: Multiple autonomous agents need to claim issues without stepping on each other. There is no central task queue service; we rely on Git as the coordination point.
Alternatives Considered:
- Gitea issue assignment API (requires locking, may race)
- Shared JSON lock file in repo (prone to merge conflicts)
- Cron-based claiming with sleep-and-retry (simple but effective)
Reason: Atomic Git branch creation is a distributed mutex provided by Git itself. It's race-safe without extra infrastructure. Combining with a claiming script and issue labels yields a simple, robust system.
Impact:
- Eliminates duplicate work
- Allows agents to operate independently
- Easy to audit: branch names reveal claims
- Claim branches are cleaned up after PR merge/close
Status: Implemented in scripts/claim-task.py
Decision 4: P2P Gossip via Redis Broadcast (Dev Only)
Date: 2026-03-15
Context: Agents need to broadcast messages to peers on the network. The initial implementation needed something quick and reliable for local development.
Alternatives Considered:
- Direct peer-to-peer sockets (complex NAT traversal)
- Central message broker with auth (more setup)
- Multicast (limited to local network)
Reason: Redis pub/sub is simple to set up, reliable, and works well on a local network. It's explicitly marked as dev-only; production will require a secure direct P2P mechanism.
Impact:
- Fast development iteration
- No security for internet deployment (known limitation)
- Forces future redesign for production (good constraint)
Status: Dev environment uses Redis; production path deferred.
Decision 5: Starlette Version Pinning (<0.38)
Date: 2026-03-15
Context: Starlette removed the Broadcast module in version 0.38, breaking the gossip backend that depends on it.
Alternatives Considered:
- Migrate to a different broadcast library (effort, risk)
- Reimplement broadcast on top of Redis only (eventual)
- Pin Starlette version until production P2P is ready
Reason: Pinning is the quickest way to restore dev environment functionality with minimal changes. The broadcast module is already dev-only; replacing it can be scheduled for production hardening.
Impact:
- Dev environment stable again
- Must remember to bump/remove pin before production
- Prevents accidental upgrades that break things
Status: pyproject.toml pins starlette>=0.37.2,<0.38
Decision 6: Use Poetry for Package Management
Date: Prior to 2026-03-15
Context: Need a consistent way to define dependencies, build packages, and manage virtualenvs across multiple packages in the monorepo.
Alternatives Considered:
- pip + requirements.txt (flat, no build isolation)
- Hatch (similar, but Poetry chosen)
- Custom Makefile (reinventing wheel)
Reason: Poetry provides a modern, all-in-one solution: dependency resolution, virtualenv management, building, publishing. It works well with monorepos via workspace-style handling (or multiple pyproject files).
Impact:
- Standardized packaging
- Faster onboarding (poetry install)
- Some learning curve; additional tool
Status: Adopted across packages; ongoing.
Decision 7: Blockchain Node Separate from Coordinator
Date: Prior to 2026-03-15
Context: The system needs a ledger for payments and consensus, but also a marketplace for job matching. Should they be one service or two?
Alternatives Considered:
- Monolithic service (simpler deployment but tighter coupling)
- Separate services with well-defined API (more flexible, scalable)
- On-chain marketplace (too slow, costly)
Reason: Separation of concerns: blockchain handles consensus and accounts; coordinator handles marketplace logic. This allows each to evolve independently and be scaled separately.
Impact:
- Clear service boundaries
- Requires cross-service communication (HTTP)
- More processes to run in dev
Status: Two services in production (devnet).
Add subsequent decisions below as they arise.