17 KiB

Raw Blame History

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:

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).
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.
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-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.
Minimum 3 engineers, recommended 4-5, working across 5 parallel streams.

Document Index

#	Document	What It Covers	Key Decisions
01	System Architecture	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	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	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	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	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	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	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	Gitea Actions pipelines (full YAML), branch strategy, rollback procedures	Path-based triggers; matrix builds; emergency rollback checklist; secret rotation policy
09	Repository Structure	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

17 KiB Raw Blame History