# Virtual Company Architecture — Overview & Board Evaluation

## Overview

ALAI operates a **multi-company virtual organization** where 16 specialized AI agent teams handle different domains. Each company has its own CLAUDE.md instructions, agent configurations, and domain expertise. Companies communicate through tasks (Mission Control) and knowledge entries (HiveMind) — never directly.

**Last evaluated:** 2026-03-31 by architecture board (Petter Graff, Martin Kleppmann, Kelsey Hightower, Chip Huyen + Devil's Advocate).

## Company Registry

<table id="bkmrk-companytypedomainsta"><tr><th>Company</th><th>Type</th><th>Domain</th><th>Status</th></tr><tr><td>**CodeCraft**</td><td>Dev Shop</td><td>Backend, APIs, databases, full-stack, fintech</td><td>🟢 Active</td></tr><tr><td>**Vizu**</td><td>Agency</td><td>Frontend, UI/UX, design, branding, components</td><td>🟢 Active</td></tr><tr><td>**Datavera**</td><td>Product Co</td><td>Data engineering, analytics, ML pipelines, SQL</td><td>🟢 Active</td></tr><tr><td>**Skybound**</td><td>Product Co</td><td>SaaS product development, multi-tenant systems</td><td>🟢 Active</td></tr><tr><td>**Proveo**</td><td>Audit Firm</td><td>QA, testing, code review, validation (READ-ONLY)</td><td>🟢 Active</td></tr><tr><td>**Securion**</td><td>Consultancy</td><td>Security audit, pentest, vulnerability scanning</td><td>🟢 Active</td></tr><tr><td>**FlowForge**</td><td>Consultancy</td><td>DevOps, CI/CD, IaC, monitoring, deployment</td><td>🟢 Active</td></tr><tr><td>**HelixSupport**</td><td>Consultancy</td><td>Production support, SLA, incidents, hotfixes</td><td>🟡 Merge candidate → FlowForge</td></tr><tr><td>**Lexicon**</td><td>Consultancy</td><td>Legal docs, compliance (GDPR/PSD2), ADRs</td><td>🟢 Active</td></tr><tr><td>**Finverge**</td><td>Consultancy</td><td>Fintech, payments, accounting, open banking</td><td>🟢 Active</td></tr><tr><td>**Skillforge**</td><td>Consultancy</td><td>Runbooks, training, knowledge management</td><td>🟡 Merge candidate → Lexicon</td></tr><tr><td>**Proxima**</td><td>Agency</td><td>Marketing, growth, SEO, content</td><td>🟡 Merge candidate → Lexicon</td></tr><tr><td>**AgentForge**</td><td>AI Lab</td><td>AI/ML ops, RAG, embeddings, model ops, HiveMind</td><td>🟢 Active</td></tr><tr><td>**Axiom**</td><td>Consultancy</td><td>Software architecture, system design, blueprints</td><td>🟢 Active</td></tr><tr><td>**Entra**</td><td>Orchestration Hub</td><td>Undefined — needs definition or removal</td><td>🔴 Review</td></tr><tr><td>**Resolver**</td><td>Meta-Ops</td><td>Cross-company diagnostics, systemic fixes</td><td>🟢 Active</td></tr></table>

## Communication Architecture

### Layer 1: Task Routing (Synchronous)

PI Orchestrator classifies tasks by keywords and routes to the appropriate company via `~/system/config/domain-to-company.json`.

```
Task created → PI Orchestrator classifies (Tier 1-5) → keyword match → company assignment → agent execution
```

### Layer 2: Pipeline Chain (Automatic Handoff)

Sequential quality gates managed by `pipeline-engine.js`:

```
BUILD (CodeCraft/Vizu) → REVIEW (Proveo) → SECURITY (Securion) → OPS (FlowForge) → DOCS (Lexicon)
  ↑                          |
  └── BUILD-FIX (max 2 cycles) ←┘  If REVIEW fails
```

### Layer 3: Cross-Company Event Bus (Asynchronous)

Managed by `cross-company-bus.js`. Scans HiveMind entries, applies routing rules from `cross-company-routes.json` (9 rules), creates inter-company tasks.

**Board finding (2026-03-31):** Bus was effectively dead — 1 task/day despite running every 6h. Root causes: agentPatterns didn't match actual HiveMind agent names, keyword matching too narrow. **Fixed same day.**

### Layer 4: Resolver Meta-Daemon

Runs every 6h via `resolver-daemon.js`. Detects systemic patterns (3+ same failure = pattern), creates H-priority fix tasks.

### Layer 5: Decision Log (NEW — 2026-03-31)

Structured, queryable decision log in `mission-control.db`. CLI: `node ~/system/tools/decision.js`. Supports log, query, list, history, supersede. Append-only audit trail with supersession chains.

## Where Communication Lives

<table id="bkmrk-storepurposelocation"><tr><th>Store</th><th>Purpose</th><th>Location</th></tr><tr><td>**Mission Control DB**</td><td>Tasks, pipeline stages, task history, decisions</td><td>`~/system/databases/mission-control.db`</td></tr><tr><td>**HiveMind DB**</td><td>Knowledge entries, intel, memos (23K+ entries)</td><td>`~/system/databases/hivemind.db`</td></tr><tr><td>**Events DB**</td><td>System event log, event bus</td><td>`~/system/databases/events.db`</td></tr><tr><td>**Slack**</td><td>Notifications (ops, exec, alerts channels)</td><td>alai-talk.slack.com</td></tr><tr><td>**Session Logs**</td><td>Per-session summaries</td><td>`~/system/memory/sessions/`</td></tr></table>

## Internal Company Structure

Each company follows a standard layout:

```
~/companies/<Name>/
├── CLAUDE.md       # Mission, expertise, rules, way of working
├── config.json     # Model selection, tier overrides, blueprints
├── agents/         # Agent configurations (lead, builder, reviewer)
├── state/          # Persistent state
└── skills/         # Company-specific skills
```

Every company has 3 standard agents:

1. **Lead** — Orchestrator: reads task specs, decomposes work, assigns phases
2. **Builder** — Implements work per blueprint (model: Sonnet)
3. **Reviewer** — Validates output, READ-ONLY (model: Sonnet or local Ollama)

## Key Orchestration Files

<table id="bkmrk-filepurpose-%7E%2Fsystem"><tr><th>File</th><th>Purpose</th></tr><tr><td>`~/system/kernel/pi-orchestrator.js`</td><td>Main daemon — task intake, classification, routing, execution, quality gates (3,953 lines)</td></tr><tr><td>`~/system/kernel/pipeline-engine.js`</td><td>BUILD→REVIEW→SECURITY automatic chain</td></tr><tr><td>`~/system/kernel/cross-company-bus.js`</td><td>Batch HiveMind scanner + event routing</td></tr><tr><td>`~/system/kernel/resolver-daemon.js`</td><td>Systemic issue detection (6h cron)</td></tr><tr><td>`~/system/config/domain-to-company.json`</td><td>Keyword → company routing map</td></tr><tr><td>`~/system/config/cross-company-routes.json`</td><td>9 inter-company event routing rules</td></tr><tr><td>`~/system/tools/decision.js`</td><td>Decision log CLI (log, query, history, supersede)</td></tr></table>

## Board Evaluation — 2026-03-31

### Panel

Petter Graff (System Architect) · Martin Kleppmann (Distributed Systems) · Kelsey Hightower (Orchestration) · Chip Huyen (AI Quality) · Devil's Advocate

### Verdict

**Structure is sound but underutilized at ~20% capacity.** Fix existing infrastructure before adding new layers.

### Key Findings

1. **Cross-company bus was dead** — agentPatterns didn't match real agent names. Fixed.
2. **getCompanyOverride bug** — returned string instead of object, tier overrides silently failed. Fixed.
3. **Skill-improver never fired** — dead `task.skill` condition. Fixed.
4. **QA-19 skipped ALL checks for automated tasks** — zero quality gating on pipeline. Fixed (retained checks 5, 6, 11, 12).
5. **No decision log** — session decisions evaporated. Fixed (decision.js).
6. **No quality scoring** — only pass/fail, no continuous signal. Planned (Phase 2).
7. **No observability per company** — throughput, first-pass rate, cycle time not tracked. Planned (Phase 3).
8. **82 LaunchAgent plists** — daemon sprawl, should consolidate to ~20. Planned.

### Recommendations (Priority Order)

<table id="bkmrk-%23actioneffortstatus-"><tr><th>\#</th><th>Action</th><th>Effort</th><th>Status</th></tr><tr><td>1</td><td>Fix 5 existing bugs</td><td>1.5h</td><td>✅ Done</td></tr><tr><td>2</td><td>Decision log (decisions table + CLI)</td><td>2h</td><td>✅ Done</td></tr><tr><td>3</td><td>Quality score column + basic scoring</td><td>2h</td><td>⬜ Planned</td></tr><tr><td>4</td><td>Observability DB + agent\_spans</td><td>2h</td><td>⬜ Planned</td></tr><tr><td>5</td><td>MC Dashboard Company Health tab</td><td>2h</td><td>⬜ Planned</td></tr><tr><td>6</td><td>Daemon consolidation (82→~20)</td><td>4h</td><td>⬜ Planned</td></tr><tr><td>7</td><td>Company merge (16→10-12)</td><td>3h</td><td>⬜ CEO decision needed</td></tr></table>

### Design Principles (Confirmed by Board)

- No direct company-to-company calls — all through MC tasks or HiveMind
- No real-time event bus needed — priority-triggered scan sufficient
- SQLite is the right choice for this scale — no Prometheus/Grafana/OTel locally
- INSERT is the telemetry pipeline, SQL is the query language
- Fewer companies, better utilized &gt; more companies with overhead