LetsBeBiz-Redesign/docs/architecture-proposal/claude/00-OVERVIEW.md

# LetsBe Biz — Architecture Proposal Overview

**Date:** February 27, 2026
**Team:** Claude Opus 4.6 Architecture Team
**Document:** 00 of 09 (Master Overview)
**Status:** Proposal — Competing with independent team

---

## Executive Summary

This document is the master overview for the LetsBe Biz architecture proposal. It summarizes the key architectural decisions, links to all 9 deliverable documents, and provides a quick-reference for evaluating the proposal against the Architecture Brief criteria.

### What We're Proposing

A 16-week implementation plan to build the LetsBe Biz platform — a privacy-first AI workforce for SMBs — with the following core architecture:

1. **Safety Wrapper as a separate process** (localhost:8200) — not an in-process OpenClaw extension. This is our most significant divergence from the Technical Architecture v1.2, justified by the discovery that OpenClaw's `before_tool_call`/`after_tool_call` hooks are not bridged to external plugins (GitHub Discussion #20575).

2. **Secrets Proxy as a separate process** (localhost:8100) — a thin HTTP proxy that runs the 4-layer redaction pipeline on all LLM-bound traffic. This process has one job: ensure secrets never leave the server.

3. **Turborepo monorepo** containing all LetsBe-specific code: Safety Wrapper, Secrets Proxy, Hub, Website, Mobile App, and shared packages. OpenClaw remains an upstream Docker image dependency.

4. **4-phase implementation**: Foundation (wk 1-4) → Integration (wk 5-8) → Customer Experience (wk 9-12) → Polish & Launch (wk 13-16). Critical path: 42 working days with 7.5 weeks of buffer.

5. **Minimum 3 engineers, recommended 4-5**, working across 5 parallel streams.

---

## Document Index

| # | Document | What It Covers | Key Decisions |
|---|----------|---------------|---------------|
| **01** | [System Architecture](./01-SYSTEM-ARCHITECTURE.md) | Two-domain architecture, 4-layer security model, data flows, network topology | Safety Wrapper as separate process; secrets-never-leave-server guarantee; 3-tier autonomy with independent external comms gate |
| **02** | [Component Breakdown](./02-COMPONENT-BREAKDOWN.md) | Full API contracts, TypeScript interfaces, database schemas for every component | 49 new Hub API endpoints; 11 new/updated Prisma models; complete Safety Wrapper HTTP API; 4-layer redaction pipeline specification |
| **03** | [Deployment Strategy](./03-DEPLOYMENT-STRATEGY.md) | Central platform, tenant server, containers, resource budgets, provider strategy | ~640MB LetsBe overhead per tenant; Netcup RS G12 primary + Hetzner overflow; canary rollout (staging → 5% → 25% → 100%) |
| **04** | [Implementation Plan](./04-IMPLEMENTATION-PLAN.md) | Week-by-week task breakdown, dependency graph, parallel workstreams, scope cuts | 80 tasks across 16 weeks; 5 parallel streams; 11 deferrable items identified; critical path = 42 days |
| **05** | [Timeline & Milestones](./05-TIMELINE.md) | Week-by-week Gantt, 4 milestones with exit criteria, buffer analysis, post-launch roadmap | 38-day buffer (7.5 weeks); 4 go/no-go decision points; founding member launch June 19, 2026 |
| **06** | [Risk Assessment](./06-RISK-ASSESSMENT.md) | 22 identified risks (6 HIGH, 9 MEDIUM, 7 LOW), known unknowns, security attack surface | Hook gap already mitigated; provisioner zero-tests is biggest operational risk; secrets bypass is biggest security risk |
| **07** | [Testing Strategy](./07-TESTING-STRATEGY.md) | P0-P3 priority tiers, adversarial test matrix, quality gates, provisioner testing | TDD for secrets redaction (~60 tests) and classification (~100+ tests); 3 quality gates (pre-merge, pre-deploy, pre-launch) |
| **08** | [CI/CD Strategy](./08-CICD-STRATEGY.md) | Gitea Actions pipelines (full YAML), branch strategy, rollback procedures | Path-based triggers; matrix builds; emergency rollback checklist; secret rotation policy |
| **09** | [Repository Structure](./09-REPO-STRATEGY.md) | Turborepo monorepo, full directory tree, package architecture, migration plan | 7 packages (safety-wrapper, secrets-proxy, hub, website, mobile, shared-types, provisioner); fresh git history recommended |

---

## Key Architectural Decisions

### Where We Agree with the Technical Architecture v1.2

| Decision | Our Position |
|----------|-------------|
| OpenClaw as upstream dependency, not a fork | **Agree.** Pinned to release tag, monthly review. |
| One customer = one VPS | **Agree.** Permanent for v1. |
| 4-layer security model (Sandbox → Tool Policy → Command Gating → Secrets Redaction) | **Agree.** All 4 layers designed and specified. |
| 3-tier autonomy (Training Wheels / Trusted Assistant / Full Autonomy) | **Agree.** Per-agent overrides, external comms gate independent. |
| 5-tier command classification (Green/Yellow/Yellow+External/Red/Critical Red) | **Agree.** Full rule set defined with 100+ test cases. |
| SQLite for on-server state | **Agree.** ChaCha20-Poly1305 via sqleet for secrets vault. |
| Tool registry + master skill + cheat sheets (not individual adapters) | **Agree.** Token-efficient architecture (~3,200 tokens base). |
| Hub relay for mobile app communication | **Agree.** App → Hub → SW → OpenClaw. |
| Native browser tool (deprecate MCP Browser) | **Agree.** OpenClaw's Playwright/CDP is sufficient. |

### Where We Diverge from the Technical Architecture v1.2

| Topic | v1.2 Proposes | We Propose | Rationale |
|-------|--------------|-----------|-----------|
| **Safety Wrapper architecture** | In-process OpenClaw extension using `before_tool_call` / `after_tool_call` hooks | Separate process (localhost:8200) receiving tool calls via HTTP | `before_tool_call`/`after_tool_call` hooks are NOT bridged to external plugins (GitHub Discussion #20575). The in-process model doesn't work as documented. |
| **Secrets Proxy** | "Thin secrets proxy" as separate process (partially aligned) | Full 4-layer redaction pipeline as separate process (localhost:8100) with dedicated responsibility | Aligns with v1.2's intent but with clearer scope: this process does ONLY redaction, nothing else. |
| **Interactive demo** | "Bella's Bakery" shared sandbox | Per-session ephemeral containers with 15-minute TTL | Shared sandbox is a security/isolation nightmare. Per-session containers are isolated, use fake data, and auto-cleanup. Cost: ~€0.02/demo. |
| **Website** | Not explicitly addressed (Part of Hub?) | Separate Next.js app in monorepo | The website has a fundamentally different audience (prospects) vs. Hub (staff/customers). Separate app keeps concerns clean. |
| **Mobile framework** | React Native (suggested) | Expo Bare Workflow SDK 52+ | Expo provides EAS Build (cloud builds), EAS Update (OTA), and managed push notifications — reduces DevOps burden significantly. Still React Native under the hood. |

### Innovations Beyond the v1.2 Spec

| Innovation | Benefit |
|-----------|---------|
| **Canary deployment for tenant updates** (staging → 5% → 25% → 100%) | Catch issues before they affect all customers |
| **Pre-provisioned server pool** with warm spares | Instant customer onboarding instead of waiting for VPS procurement |
| **Shannon entropy filter** (Layer 3 of redaction) | Catches unknown/unregistered secrets that aren't in the registry or regex patterns |
| **Per-session ephemeral demo** vs. shared sandbox | Better isolation, no state leakage between prospects, self-cleaning |
| **Scope cut table** with 11 deferrable items | Clear plan for what to cut if timeline pressure hits, with impact assessment |
| **Adversarial testing matrix** | 30+ explicit bypass attempt tests for secrets redaction and command classification |

---

## Architecture at a Glance

### Tenant Server (Per-Customer VPS)

```
┌─────────────────────────────────────────────────────────┐
│ Customer VPS (Netcup RS G12 / Hetzner Cloud)            │
│                                                         │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐  │
│  │  OpenClaw    │──│Safety Wrapper│──│ Secrets Proxy │  │
│  │ (AI Runtime) │  │ (:8200)      │  │ (:8100)       │  │
│  │ ~384MB       │  │ ~128MB       │  │ ~64MB         │  │
│  └──────────────┘  └──────────────┘  └───────┬───────┘  │
│         │                │                    │          │
│         │     ┌──────────┘                    │          │
│         │     │                               │          │
│         ▼     ▼                               ▼          │
│  ┌─────────────────┐                  External LLMs     │
│  │ 25+ Tool        │                  (OpenRouter)      │
│  │ Containers      │                  (secrets never    │
│  │ (Nextcloud,     │                   reach here)      │
│  │  Chatwoot, etc) │                                    │
│  └─────────────────┘                                    │
│                                                         │
│  nginx (:80/:443) ─── reverse proxy to all services     │
└─────────────────────────────────────────────────────────┘
```

### Central Platform

```
┌───────────────────────────────────────┐
│ Hub Server                             │
│                                        │
│  ┌─────────────┐  ┌─────────────────┐  │
│  │ Hub (Next.js)│  │ PostgreSQL 16   │  │
│  │ :3847        │  │ :5432           │  │
│  └──────┬───────┘  └─────────────────┘  │
│         │                                │
│  ┌──────▼──────────────────────────┐     │
│  │ Tenant Communication            │     │
│  │ • Registration + API keys       │     │
│  │ • Heartbeat (60s interval)      │     │
│  │ • Config sync (delta delivery)  │     │
│  │ • Token usage ingestion         │     │
│  │ • Approval routing              │     │
│  │ • Chat relay (App ↔ AI)         │     │
│  └─────────────────────────────────┘     │
└───────────────────────────────────────┘

┌───────────────────────────────────────┐
│ Website (letsbe.biz)                   │
│ Separate Next.js app                   │
│ AI-powered onboarding + Stripe         │
└───────────────────────────────────────┘
```

---

## Evaluation Criteria Cross-Reference

The Architecture Brief §11 defines 7 evaluation criteria. Here's where each is addressed:

### 1. Architectural Clarity

- **System decomposition:** 01-SYSTEM-ARCHITECTURE — two-domain model (central + tenant), clear component boundaries
- **Clean interfaces:** 02-COMPONENT-BREAKDOWN — full API contracts with TypeScript interfaces for every integration point
- **Independent evolution:** 09-REPO-STRATEGY — packages can be deployed independently; no circular dependencies

### 2. Security Rigor

- **Secrets guarantee:** 01-SYSTEM-ARCHITECTURE §4 — 4-layer model; 02-COMPONENT-BREAKDOWN §2 — full redaction pipeline spec
- **Edge cases:** 07-TESTING-STRATEGY §10 — adversarial testing matrix with 30+ bypass attempts
- **Attack surface:** 06-RISK-ASSESSMENT §6 — 10 attack vectors analyzed with mitigations

### 3. Pragmatic Trade-offs

- **Scope cuts identified:** 04-IMPLEMENTATION-PLAN §8 — 11 deferrable items with impact assessment
- **Speed vs. quality:** 05-TIMELINE §7 — 4 go/no-go decision points with explicit fallback plans
- **Non-negotiables preserved:** 06-RISK-ASSESSMENT §6 — security invariants that must hold under all conditions

### 4. Build Order Intelligence

- **Critical path:** 04-IMPLEMENTATION-PLAN §9 — 42 working days, mapped task-by-task
- **Parallel development:** 04-IMPLEMENTATION-PLAN §7 — 5 streams with team sizing options
- **Dependencies mapped:** 04-IMPLEMENTATION-PLAN §6 — full ASCII dependency graph

### 5. Testing Strategy

- **Security-critical TDD:** 07-TESTING-STRATEGY §3-4 — tests written BEFORE implementation for P0 components
- **Meaningful tests:** 07-TESTING-STRATEGY §1 — "tests validate behavior, not coverage" philosophy
- **Provisioner testing:** 07-TESTING-STRATEGY §13 — bats-core tests for the zero-test Bash codebase

### 6. Innovation

- **Hook gap discovery:** The Technical Architecture v1.2's in-process extension model doesn't work. We discovered this and designed around it.
- **Per-session ephemeral demo:** Better isolation and security than shared "Bella's Bakery" sandbox
- **Shannon entropy filter:** Catches unknown secrets that bypass registry lookup and regex patterns
- **Canary deployment:** Progressive rollout prevents bad updates from affecting all customers

### 7. Honesty About Risks

- **22 risks identified:** 06-RISK-ASSESSMENT — 6 HIGH, 9 MEDIUM, 7 LOW
- **6 known unknowns:** 06-RISK-ASSESSMENT §5 — areas requiring investigation with timelines
- **Buffer analysis:** 05-TIMELINE §6 — even worst-case scenario (all risks materialize) leaves 18 days buffer

---

## Non-Negotiables Verified

| Non-Negotiable (Brief §3) | Status | Reference |
|---------------------------|--------|-----------|
| Privacy Architecture (4-Layer Security Model) | **Designed** | 01-SYSTEM-ARCHITECTURE §4-6; 02-COMPONENT-BREAKDOWN §1-2 |
| AI Autonomy Levels (3-Tier System) | **Designed** | 01-SYSTEM-ARCHITECTURE §6; 02-COMPONENT-BREAKDOWN §1.4 |
| Command Classification (5 Tiers) | **Designed** | 02-COMPONENT-BREAKDOWN §1.2; 07-TESTING-STRATEGY §4 |
| OpenClaw as Upstream Dependency (not fork) | **Verified** | 01-SYSTEM-ARCHITECTURE §1; separate-process architecture avoids any OpenClaw modification |
| One Customer = One VPS | **Designed** | 03-DEPLOYMENT-STRATEGY §1-3 |

---

## Scope Coverage

| Brief §4 Item | Status | Primary Document |
|---------------|--------|-----------------|
| 4.1 Safety Wrapper | **Full design** | 02-COMPONENT-BREAKDOWN §1 |
| 4.2 Tool Registry + Adapters | **Full design** | 02-COMPONENT-BREAKDOWN §7 |
| 4.3 Hub Updates | **Full design** | 02-COMPONENT-BREAKDOWN §3 |
| 4.4 Provisioner Updates | **Full design** | 02-COMPONENT-BREAKDOWN §4 |
| 4.5 Mobile App | **Full design** | 02-COMPONENT-BREAKDOWN §5 |
| 4.6 Website + Onboarding | **Full design** | 02-COMPONENT-BREAKDOWN §6 |
| 4.7 Secrets Registry | **Full design** | 02-COMPONENT-BREAKDOWN §1.1 |
| 4.8 Autonomy Level System | **Full design** | 02-COMPONENT-BREAKDOWN §1.4 |
| 4.9 Prompt Caching | **Covered** | 01-SYSTEM-ARCHITECTURE; 04-IMPLEMENTATION-PLAN task 14.1 |
| 4.10 First-Hour Templates | **Covered** | 04-IMPLEMENTATION-PLAN tasks 15.3-15.4 |
| 4.11 Interactive Demo | **Full design** | 02-COMPONENT-BREAKDOWN §9 |

---

## Quick Stats

| Metric | Value |
|--------|-------|
| Total documents | 10 (00-09) |
| New Hub API endpoints | ~49 |
| New/updated Prisma models | 11 |
| P0 test cases (redaction + classification) | ~160+ |
| Identified risks | 22 (6 HIGH, 9 MEDIUM, 7 LOW) |
| Known unknowns | 6 |
| Deferrable scope items | 11 |
| Critical path | 42 working days |
| Total buffer | 38 working days (7.5 weeks) |
| Minimum team size | 3 engineers |
| Recommended team size | 4-5 engineers |
| Estimated launch date | June 19, 2026 (assuming March 3 start) |
| LetsBe overhead per tenant | ~640MB RAM |

---

*End of Document — 00 Overview*

---

## Document Listing

```
docs/architecture-proposal/claude/
├── 00-OVERVIEW.md              ← You are here (master overview)
├── 01-SYSTEM-ARCHITECTURE.md   ← System diagrams, data flows, security model
├── 02-COMPONENT-BREAKDOWN.md   ← API contracts, interfaces, schemas
├── 03-DEPLOYMENT-STRATEGY.md   ← Deployment, containers, resource budgets
├── 04-IMPLEMENTATION-PLAN.md   ← Task breakdown, dependency graph, scope cuts
├── 05-TIMELINE.md              ← Gantt chart, milestones, buffer analysis
├── 06-RISK-ASSESSMENT.md       ← Risk register, known unknowns, attack surface
├── 07-TESTING-STRATEGY.md      ← Test tiers, adversarial matrix, quality gates
├── 08-CICD-STRATEGY.md         ← Gitea pipelines, branch strategy, rollback
└── 09-REPO-STRATEGY.md         ← Monorepo structure, directory tree, migration
```