letsbe
/
LetsBeBiz-Redesign
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
LetsBeBiz-Redesign/docs/architecture-proposal/claude/00-OVERVIEW.md

262 lines
17 KiB
Markdown
Raw Permalink 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:
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
```
Reference in New Issue View Git Blame Copy Permalink