# SYSTEM.md — RateRight OpsMan Fleet Architecture

*The whole picture. Read this first.*

---

## What We're Building

Three interconnected systems, one mission: make construction hiring simple and cheap.

1. **RateRight** — Construction marketplace. $50 flat fee per hire. Workers pay nothing.
2. **OpsMan** — Operations management for construction companies. The 8-agent fleet IS the prototype.
3. **Growth Engine** — CRM and sales intelligence. Leads, SMS, calls, AI-powered pipeline.
4. **Phone AI** — Voice receptionist qualifying inbound leads.

**The insight:** The fleet running RateRight demonstrates OpsMan's value. Every agent doing real autonomous work proves the product works.

---

## The Fleet

8 agents, each a separate Clawdbot gateway instance on the same VPS.

| Agent | Port | Model | Domain | Workspace |
|-------|------|-------|--------|-----------|
| **Rivet** 🔧 | 18789 | deepseek-coder | Chief of Staff | `/home/ccuser/rateright-growth/rivet` |
| **Builder** 🔨 | 18790 | deepseek-coder | Development | `/home/ccuser/the-50-dollar-app` |
| **Susan** 💼 | 18792 | moonshot/kimi-k2.5 | Sales & Marketing | `/home/ccuser/susan` |
| **Harper** 📊 | 18796 | openrouter/openai/gpt-5.2 | Finance & Legal | `/home/ccuser/harper` |
| **Sentinel** 🛡️ | 18800 | deepseek/deepseek-chat | DevSecOps | `/home/ccuser/sentinel` |
| **Radar** 🔭 | 18804 | openrouter/x-ai/grok-3 | Intelligence | `/home/ccuser/radar` |
| **Herald** 📡 | 18808 | openrouter/google/gemini-3.1-pro-preview | Communications | `/home/ccuser/herald` |
| **Cog** ⚙️ | 18812 | minimax/MiniMax-M2.5 | Operations Support | `/home/ccuser/cog` |

**Michael (Rocky)** is the founder. Human. Final decisions on everything external, financial, or strategic.

### Layer Structure

```
Layer 0: Michael — Founder, decisions, construction expertise
Layer 1: Rivet — Chief of Staff, fleet coordination, strategy
Layer 2: Builder, Susan, Harper — Execution agents (code, sales, finance)
Layer 3: Sentinel, Radar, Herald, Cog — Support agents (infra, intel, comms, ops)
```

---

## Infrastructure

| System | URL / Location | Stack | Status |
|--------|---------------|-------|--------|
| **VPS** | 134.199.153.159 (DO syd1) | 4 vCPU, 8GB RAM, Ubuntu | Running |
| **RateRight App** | https://rivet.rateright.com.au | Next.js 16 + Supabase | Live |
| **Growth Engine** | https://rateright-growth-production.up.railway.app | Express.js + Railway | Live |
| **Main Site** | https://rateright.com.au | Flask on Fly.io | Live |
| **Phone AI** | VAPI assistant | GPT-4o + Twilio | Active |

### Services (systemd)

Each agent runs as a systemd service: `clawdbot-{agent}` (e.g., `clawdbot-builder`, `clawdbot-susan`).
Rivet's service is `clawdbot-gateway`.

```bash
# Check agent status
systemctl status clawdbot-susan

# Restart an agent
systemctl restart clawdbot-radar

# View logs
journalctl -u clawdbot-harper --since "1 hour ago" --no-pager
```

### Databases
- **RateRight App:** Supabase project `eciepjpcyfurbkfzekok`
- **Growth Engine:** Supabase project `memscjotxrzqnhrvnnkc`
- Both have service role keys for full DB access (in `.env` files, never in session)

---

## Communication

### Agent-to-Agent
- **JSONL inboxes:** Each agent has an inbox file in their workspace. See COMMS-PROTOCOL.md.
- **Shared files:** `/home/ccuser/shared/` for fleet-wide state
- **Agent bridge:** `node /home/ccuser/the-50-dollar-app/scripts/agent-bridge.js <agent> <command>`
- **Gateway-to-gateway bridge:** `node /home/ccuser/rateright-growth/rivet/scripts/builder-bridge.js`

### Fleet State
Single source of truth: `/home/ccuser/shared/fleet-state.json`

Each agent maintains:
- `status.json` — their current state (updated every heartbeat)
- `queue.json` — their task queue

Fleet monitoring scripts (cron):
- `stall-detector.js` — every 5 min, checks agent liveness
- `health-check.js` — every 5 min, HTTP pings
- `buddy-check.js` — every 30 min, cross-agent health verification
- `context-monitor.js` — every 10 min, watches context window usage
- `crash-loop-guard.js` — every 2 min, prevents service crash loops

### Telegram
- **Group:** Rocky & Rivet (-1003505625266)
- **Topics:** General(1), RateRight(2), Sales(4), Research(5), Construction(6), System(7), Personal(8), Ideas(10), Content(11), Legal(388), Financial(391)

---

## Model Strategy

The fleet runs on multi-provider diversity (OpenRouter, MiniMax, DeepSeek, Moonshot). Zero Anthropic dependency.

| Provider | Model | Used By | Purpose |
|----------|-------|---------|---------|
| **OpenRouter** | GPT-5.3-Codex | Rivet, Builder | Strategy, code, judgment |
| **Moonshot** | Kimi K2.5 | Susan | Sales, outreach, CRM |
| **OpenRouter** | GPT-5.2 | Harper | Finance, legal, compliance |
| **DeepSeek** | deepseek-chat | Sentinel | DevSecOps, monitoring |
| **OpenRouter** | Grok-3 | Radar | Intelligence, research |
| **OpenRouter** | Gemini 3.1 Pro | Herald | Communications, content |
| **MiniMax** | M2.5 | Cog, subagents | Operations, grunt work |

**Fallback chain (all agents):** MiniMax M2.5 → Gemini 3.1 Pro Preview

**Provider notes:**
- MiniMax — working, used by Cog as primary (OpenClaw v2026.3.2 fixed mapOptionsForApi)
- Moonshot/Kimi — working, $300 credit available
- Anthropic — blocked Max plan OAuth tokens from third-party tools (Mar 2026). Not used.

**Rule:** External/untrusted data always processed by the strongest available model (prompt injection resistance).

---

## Business Context

- **Revenue model:** $50 flat fee per completed hire
- **Workers pay:** Nothing. Ever.
- **Monthly burn:** ~$700
- **Runway:** ~3 years ($24k in bank)
- **Breakeven:** 2-3 hires/month
- **Gross margin:** 97.2%
- **Leads in pipeline:** 231 (91.8% untouched)
- **Current phase:** Launch prep → soft launch → outreach

### Legal Position
- Sham contracting risk: LOW (construction tradies excluded)
- Labour hire licensing: NOT REQUIRED (we don't pay workers)
- We do MATCHING, not hiring — platform facilitator only

---

## Key Boundaries

1. **Code goes through Builder.** No exceptions. Rivet specs, Builder builds.
2. **External comms get approval.** Draft for Michael, never auto-send.
3. **API keys stay in .env files.** Never read in sessions, never in git.
4. **Each agent owns their domain.** Rivet coordinates, doesn't execute their work.
5. **Fleet is the product.** Every agent proving autonomous value = OpsMan demo.

---

*This is the system. If you're new to the fleet, read AGENTS.md next for coordination protocols, then COMMS-PROTOCOL.md for how to talk to each other.*