LetsBeBiz-Redesign/docs/architecture-proposal/claude/04-IMPLEMENTATION-PLAN.md

27 KiB
Raw Permalink Blame History

LetsBe Biz — Implementation Plan

Date: February 27, 2026 Team: Claude Opus 4.6 Architecture Team Document: 04 of 09 Status: Proposal — Competing with independent team


Table of Contents

  1. Phase Overview
  2. Phase 1 — Foundation (Weeks 1-4)
  3. Phase 2 — Integration (Weeks 5-8)
  4. Phase 3 — Customer Experience (Weeks 9-12)
  5. Phase 4 — Polish & Launch (Weeks 13-16)
  6. Dependency Graph
  7. Parallel Workstreams
  8. Scope Cut Table
  9. Critical Path

1. Phase Overview

Week  1  2  3  4  5  6  7  8  9  10 11 12 13 14 15 16
      ├────────────────┤
      │  PHASE 1:      │
      │  Foundation     │
      │  Safety Wrapper │
      │  Secrets Proxy  │
      │  P0 Tests       │
      │                 ├────────────────┤
      │                 │  PHASE 2:      │
      │                 │  Integration   │
      │                 │  Hub APIs      │
      │                 │  Tool Adapters │
      │                 │  Browser Tool  │
      │                 │                ├────────────────┤
      │                 │                │  PHASE 3:      │
      │                 │                │  Customer UX   │
      │                 │                │  Mobile App    │
      │                 │                │  Provisioner   │
      │                 │                │                ├────────────────┤
      │                 │                │                │  PHASE 4:      │
      │                 │                │                │  Polish        │
      │                 │                │                │  Security Audit│
      │                 │                │                │  Launch        │
Phase Duration Focus Exit Criteria
1 Weeks 1-4 Safety Wrapper + Secrets Proxy core Secrets redaction passes all P0 tests; command classification works; OpenClaw routes through wrapper
2 Weeks 5-8 Hub APIs + tool adapters + billing Hub ↔ Safety Wrapper protocol working; 6 P0 tool adapters operational; token metering flowing to billing
3 Weeks 9-12 Mobile app + customer portal + provisioner End-to-end: payment → provision → AI ready → mobile chat working
4 Weeks 13-16 Security audit + polish + launch Founding member launch: first 10 customers onboarded

2. Phase 1 — Foundation (Weeks 1-4)

Goal: Safety Wrapper and Secrets Proxy functional with comprehensive P0 tests

Week 1: Safety Wrapper Skeleton + Secrets Registry

Task Effort Deliverable Depends On
1.1 Monorepo setup (Turborepo, packages structure) 2d Working monorepo with packages/safety-wrapper, packages/secrets-proxy, packages/shared-types
1.2 Safety Wrapper HTTP server skeleton 2d Express/Fastify server on localhost:8200 with health endpoint 1.1
1.3 SQLite schema + migration system 1d secrets, approvals, audit_log, token_usage, hub_state tables 1.1
1.4 Secrets registry implementation 3d ChaCha20-Poly1305 encrypted SQLite vault; CRUD operations; pattern generation 1.3
1.5 Tool execution endpoint (POST /api/v1/tools/execute) 2d Request parsing, validation, routing to executors 1.2

Week 2: Command Classification + Tool Executors

Task Effort Deliverable Depends On
2.1 Command classification engine 3d Deterministic rule engine for all 5 tiers; shell command classifier with allowlist 1.5
2.2 Shell executor (port from sysadmin agent) 2d execFile-based execution with path validation, timeout, metacharacter blocking 2.1
2.3 Docker executor 1d Docker subcommand classifier + executor 2.2
2.4 File read/write executor 1d Path traversal prevention, size limits, atomic writes 2.2
2.5 Env read/update executor 1d .env parsing, atomic update with temp→rename 2.2
2.6 P0 tests: command classification 2d 100+ test cases covering all tiers, edge cases, shell metacharacters 2.1

Week 3: Secrets Proxy + Redaction Pipeline

Task Effort Deliverable Depends On
3.1 Secrets Proxy HTTP server 1d Transparent proxy on localhost:8100 1.1
3.2 Layer 1: Aho-Corasick registry redaction 2d O(n) multi-pattern matching against all known secrets 1.4, 3.1
3.3 Layer 2: Regex safety net 1d Private keys, JWTs, bcrypt, connection strings, env patterns 3.1
3.4 Layer 3: Shannon entropy filter 1d High-entropy blob detection (≥4.5 bits, ≥32 chars) 3.1
3.5 Layer 4: JSON key scanning 0.5d Sensitive key name detection in JSON payloads 3.1
3.6 P0 tests: secrets redaction 2.5d TDD — test matrix from Technical Architecture §19.2: registry match, patterns, entropy, false positives, performance (<10ms) 3.2-3.5

Week 4: Autonomy Engine + OpenClaw Integration

Task Effort Deliverable Depends On
4.1 Autonomy resolution engine 2d Level 1/2/3 gating matrix; per-agent overrides; external comms gate 2.1
4.2 Approval queue (local) 1d SQLite-backed pending approvals with expiry 4.1
4.3 Credential injection (SECRET_REF resolution) 2d Intercept SECRET_REF placeholders, inject real values from registry 1.4, 2.2
4.4 OpenClaw integration: configure tool routing 2d OpenClaw routes tool calls to Safety Wrapper HTTP API 4.3
4.5 OpenClaw integration: configure LLM proxy 1d OpenClaw routes LLM calls through Secrets Proxy (port 8100) 3.1
4.6 P0 tests: autonomy level mapping 1d All 3 levels × 5 tiers × per-agent override scenarios 4.1
4.7 Integration test: OpenClaw → Safety Wrapper → tool execution 1d End-to-end tool call with classification, gating, execution, audit logging 4.4

Phase 1 Exit Criteria

  • Secrets Proxy redacts all known secret patterns with <10ms latency
  • Command classifier correctly tiers all defined tools + shell commands
  • Autonomy engine correctly gates/executes at all 3 levels
  • OpenClaw successfully routes tool calls through Safety Wrapper
  • OpenClaw successfully routes LLM calls through Secrets Proxy
  • SECRET_REF injection works for tool execution
  • All P0 tests pass (secrets redaction, command classification, autonomy mapping)
  • Audit log records every tool call

3. Phase 2 — Integration (Weeks 5-8)

Goal: Hub ↔ Safety Wrapper protocol, P0 tool adapters, billing pipeline

Week 5: Hub Communication Protocol

Task Effort Deliverable Depends On
5.1 Hub: /api/v1/tenant/register endpoint 1d Registration token validation, API key generation Phase 1
5.2 Hub: /api/v1/tenant/heartbeat endpoint 2d Metrics ingestion, config response, pending commands 5.1
5.3 Hub: /api/v1/tenant/config endpoint 1d Full config delivery (agents, autonomy, classification) 5.1
5.4 Safety Wrapper: Hub client implementation 2d Registration, heartbeat loop, config sync, backoff/jitter 5.1-5.3
5.5 Hub: ServerConnection model update 0.5d Add safetyWrapperUrl, openclawVersion, configVersion fields
5.6 P1 tests: Hub ↔ Safety Wrapper protocol 1.5d Registration, heartbeat, config sync, network failure handling 5.4

Week 6: Token Metering + Billing

Task Effort Deliverable Depends On
6.1 Safety Wrapper: token metering capture 2d Capture from OpenRouter response headers; hourly bucket aggregation Phase 1
6.2 Hub: TokenUsageBucket + BillingPeriod models 1d Prisma migration, model definitions
6.3 Hub: /api/v1/tenant/usage endpoint 1d Ingest usage buckets, update billing period 6.2
6.4 Hub: /api/v1/admin/billing/* endpoints 2d Customer billing summary, history, overage trigger 6.2
6.5 Stripe Billing Meters integration 2d Overage metering + premium model metering via Stripe 6.4
6.6 Hub: FoundingMember model + multiplier logic 1d Token multiplier applied to billing period creation 6.2
6.7 Hub: usage alerts (80/90/100%) 1d Trigger push notifications at pool thresholds 6.3

Week 7: Tool Adapters (P0)

Task Effort Deliverable Depends On
7.1 Tool registry template + generator 1d tool-registry.json generation from provisioner env files Phase 1
7.2 Master skill (SKILL.md) 0.5d Teach AI three access patterns (API, CLI, browser) 7.1
7.3 Cheat sheet: Portainer 0.5d REST v2 API endpoints for container management
7.4 Cheat sheet: Nextcloud 1d WebDAV + OCS REST endpoints
7.5 Cheat sheet: Chatwoot 1d REST v1/v2 endpoints for conversation management
7.6 Cheat sheet: Ghost 0.5d Content + Admin REST endpoints
7.7 Cheat sheet: Cal.com 0.5d REST v2 endpoints
7.8 Cheat sheet: Stalwart Mail 0.5d REST endpoints for account/domain management
7.9 Integration tests: agent → tool via Safety Wrapper 2d 6 tools: API call with SECRET_REF, classification, execution, response 7.3-7.8

Week 8: Approval Queue + Config Sync

Task Effort Deliverable Depends On
8.1 Hub: CommandApproval model + endpoints 2d CRUD for approvals; customer + admin approval endpoints 6.2
8.2 Hub: /api/v1/tenant/approval-request endpoint 1d Safety Wrapper pushes approval requests to Hub 8.1
8.3 Hub: /api/v1/tenant/approval-response/{id} endpoint 1d Safety Wrapper polls for approval decisions 8.1
8.4 Hub: AgentConfig model + admin endpoints 2d CRUD for agent configs; sync to Safety Wrapper
8.5 Config sync: Hub → Safety Wrapper 1d Config versioning; delta delivery via heartbeat 5.2, 8.4
8.6 Push notification service skeleton 1d Expo Push token registration; notification sending
8.7 Integration test: approval round-trip 1d Red command → gate → push to Hub → approve → execute 8.3

Phase 2 Exit Criteria

  • Safety Wrapper registers with Hub and maintains heartbeat
  • Token usage flows from Safety Wrapper → Hub → BillingPeriod
  • Stripe overage billing triggers when pool exhausted
  • 6 P0 tool cheat sheets operational (agent can use Portainer, Nextcloud, Chatwoot, Ghost, Cal.com, Stalwart)
  • Approval round-trip works: gate → Hub → approve → execute
  • Config sync: Hub agent config changes propagate to Safety Wrapper
  • Founding member multiplier applies to billing periods

4. Phase 3 — Customer Experience (Weeks 9-12)

Goal: End-to-end customer journey from payment to mobile chat

Week 9: Mobile App Foundation

Task Effort Deliverable Depends On
9.1 Expo project setup (Bare Workflow, SDK 52) 1d Project scaffolding, EAS configuration
9.2 Auth flow (login, JWT storage) 2d Login screen, secure token storage, auto-refresh
9.3 Chat view with SSE streaming 3d Real-time agent response rendering via Hub relay Phase 2
9.4 Agent selector (team chat vs. direct) 1d Agent roster, tap to open direct chat 9.3
9.5 Push notification setup (Expo Push) 1d Token registration, notification categories, background handlers
9.6 Approval cards with one-tap approve/deny 1d In-app queue + push notification action buttons 9.5, Phase 2

Week 10: Customer Portal + Chat Relay

Task Effort Deliverable Depends On
10.1 Hub: customer portal API (/api/v1/customer/*) 3d Dashboard, agents, usage, approvals, tools, billing endpoints Phase 2
10.2 Hub: chat relay service 2d App → Hub → Safety Wrapper → OpenClaw → response stream Phase 2
10.3 Hub: WebSocket endpoint for real-time chat 2d Persistent connection for chat + notification delivery 10.2
10.4 Mobile: dashboard screen 1d Server status, morning briefing, quick actions 10.1
10.5 Mobile: usage dashboard 1d Per-agent, per-model token usage with trends 10.1

Week 11: Provisioner Update + Website

Task Effort Deliverable Depends On
11.1 Provisioner: update step 10 for OpenClaw + Safety Wrapper 3d Deploy LetsBe AI stack, generate configs, seed secrets Phase 1
11.2 Provisioner: n8n cleanup 1d Remove all n8n references (7 files)
11.3 Provisioner: config.json cleanup (CRITICAL fix) 0.5d Remove plaintext passwords post-provisioning
11.4 Website: landing page + onboarding flow pages 1-5 2d Business description → AI classification → tool selection → tier selection → domain
11.5 Website: AI business classifier 1d Gemini Flash integration for business type classification
11.6 Website: resource calculator 0.5d Live RAM/disk calculation based on selected tools

Week 12: End-to-End Integration

Task Effort Deliverable Depends On
12.1 Website: payment flow (Stripe Checkout) 1d Stripe integration, order creation 11.4
12.2 Website: provisioning status page (SSE) 1d Real-time progress display 11.1, 12.1
12.3 End-to-end test: payment → provision → AI ready → mobile chat 3d Full journey on staging VPS All above
12.4 Provisioner: Playwright scenario migration (7 scenarios, minus n8n) 2d Cal.com, Chatwoot, Keycloak, Nextcloud, Stalwart, Umami, Uptime Kuma via OpenClaw browser 11.1
12.5 Mobile: settings screens (agent config, autonomy, external comms) 1d Agent management, model selection, external comms gate 10.1
12.6 Mobile: secrets side-channel (provide/reveal) 1d Secure modal for credential input, tap-to-reveal card Phase 2

Phase 3 Exit Criteria

  • Full customer journey works: website signup → payment → provisioning → AI ready
  • Mobile app: login, chat with agents, approve commands, view usage
  • Provisioner deploys OpenClaw + Safety Wrapper (not orchestrator/sysadmin)
  • n8n references fully removed
  • config.json no longer contains plaintext passwords
  • Chat relay works: App → Hub → Safety Wrapper → OpenClaw → response
  • Push notifications delivered for approval requests

5. Phase 4 — Polish & Launch (Weeks 13-16)

Goal: Security audit, performance optimization, founding member launch

Week 13: Security Audit + P1 Adapters

Task Effort Deliverable Depends On
13.1 Security audit: secrets redaction (adversarial testing) 2d Test with crafted payloads: encoded, nested, multi-format Phase 3
13.2 Security audit: command gating (boundary testing) 1d Attempt to bypass classification via edge cases Phase 3
13.3 Security audit: path traversal, injection, SSRF 1d Penetration testing of all Safety Wrapper endpoints Phase 3
13.4 Run openclaw security audit --deep on staging 0.5d Fix any findings Phase 3
13.5 Cheat sheets: Odoo, Listmonk, NocoDB, Umami, Keycloak, Activepieces 3d P1 tool adapters operational
13.6 Channel configuration: WhatsApp + Telegram 1.5d OpenClaw channel config; pairing mode; DM security

Week 14: Performance + Polish

Task Effort Deliverable Depends On
14.1 Prompt caching optimization 1d Verify cacheRetention: "long" working; measure cache hit rate Phase 3
14.2 Token efficiency audit 1d Measure per-agent token usage; optimize verbose SOUL.md files 14.1
14.3 Secrets redaction performance benchmark 0.5d Confirm <10ms latency with 50+ secrets in registry Phase 3
14.4 Mobile app: UI polish, error handling, offline state 2d Production-ready mobile experience Phase 3
14.5 Website: remaining pages (agent config, payment, provisioning status) 1.5d Complete onboarding flow Phase 3
14.6 Provisioner: integration tests (Docker Compose based) 2d Test provisioning in container; verify all steps succeed Phase 3

Week 15: Staging Launch + First-Hour Templates

Task Effort Deliverable Depends On
15.1 Deploy full stack to staging 1d Hub + Website + Provisioner + staging tenant VPS All above
15.2 Internal dogfooding: team uses staging for 1 week 5d (ongoing) Bug reports, UX feedback, performance data 15.1
15.3 First-hour templates: Freelancer workflow 1d Email setup, calendar connect, basic automation 15.1
15.4 First-hour templates: Agency workflow 1d Client comms, project tracking, team setup 15.1
15.5 Backup monitoring via OpenClaw cron 0.5d Daily backup-status.json check + Hub reporting 15.1
15.6 Interactive demo: ephemeral container system 2d Per-session demo with 15-min TTL 15.1

Week 16: Launch

Task Effort Deliverable Depends On
16.1 Fix staging issues from dogfooding 3d All critical/high issues resolved 15.2
16.2 Production deployment 1d Hub production, pre-provisioned server pool, DNS 16.1
16.3 Founding member onboarding: first 10 customers ongoing Hands-on onboarding, 2× token allotment 16.2
16.4 Monitoring dashboard setup 0.5d Hub health, tenant health, billing dashboards 16.2
16.5 Runbook documentation 0.5d Incident response, common issues, escalation paths 16.2

Phase 4 Exit Criteria

  • Security audit passes with no critical findings
  • Performance targets met (redaction <10ms, heartbeat reliable, tool calls <5s p95)
  • 10 founding members onboarded and actively using the platform
  • WhatsApp and Telegram channels operational
  • Interactive demo working on letsbe.biz/demo
  • Backup monitoring reporting to Hub
  • First-hour templates proving cross-tool workflows work

6. Dependency Graph

                    ┌─────────────┐
                    │ 1.1 Monorepo│
                    │   Setup     │
                    └──────┬──────┘
                    ┌──────┴──────┐
              ┌─────┤             ├─────┐
              │     │             │     │
       ┌──────▼──┐ ┌▼────────┐ ┌─▼──────────┐
       │1.2 SW   │ │1.3 SQLite│ │3.1 Secrets │
       │Skeleton │ │Schema   │ │Proxy Server│
       └────┬────┘ └────┬────┘ └─────┬──────┘
            │           │            │
       ┌────▼────┐ ┌────▼────┐  ┌───▼────────┐
       │1.5 Tool │ │1.4 Secrets│ │3.2-3.5    │
       │Execute  │ │Registry  │ │4-Layer     │
       │Endpoint │ └────┬─────┘ │Redaction   │
       └────┬────┘      │      └───┬────────┘
            │           │          │
       ┌────▼────┐      │     ┌───▼────────┐
       │2.1 Cmd  │      │     │3.6 P0 Tests│
       │Classify │      │     │Redaction   │
       └────┬────┘      │     └────────────┘
            │           │
  ┌─────────┼─────┐     │
  │    ┌────┤     │     │
  │    │    │     │     │
┌─▼──┐┌▼──┐┌▼──┐ │     │
│2.2 ││2.3││2.4│ │     │
│Shell│Dock│File│ │     │
│Exec││er ││Exec│ │     │
└────┘└───┘└───┘ │     │
                 │     │
            ┌────▼─────▼──┐
            │4.1 Autonomy │
            │Engine       │
            └──────┬──────┘
                   │
            ┌──────▼──────┐
            │4.4 OpenClaw │
            │Integration  │
            └──────┬──────┘
                   │
         ┌─────────┼──────────┐
         │         │          │
    ┌────▼───┐ ┌───▼────┐ ┌──▼─────────┐
    │5.1-5.4 │ │6.1-6.7 │ │7.1-7.9     │
    │Hub     │ │Token   │ │Tool        │
    │Protocol│ │Billing │ │Adapters    │
    └────┬───┘ └───┬────┘ └──┬─────────┘
         │         │         │
    ┌────▼─────────▼─────────▼──┐
    │8.1-8.7 Approvals + Config │
    └────────────┬──────────────┘
                 │
    ┌────────────┼────────────┐
    │            │            │
┌───▼────┐ ┌────▼───┐ ┌──────▼──────┐
│9.1-9.6 │ │10.1-10.5│ │11.1-11.6   │
│Mobile  │ │Customer│ │Provisioner  │
│App     │ │Portal  │ │+ Website    │
└───┬────┘ └───┬────┘ └──────┬──────┘
    │          │             │
    └──────────┼─────────────┘
               │
    ┌──────────▼──────────┐
    │12.3 E2E Integration │
    └──────────┬──────────┘
               │
    ┌──────────▼──────────┐
    │Phase 4: Polish      │
    │Security + Launch    │
    └─────────────────────┘

7. Parallel Workstreams

Tasks that can be developed simultaneously by different engineers:

Stream A: Safety Wrapper Core (1 senior engineer)

Week 1-2: SW skeleton, classification, executors
Week 3:   Autonomy engine, SECRET_REF injection
Week 4:   OpenClaw integration, integration tests
Week 5-6: Hub client, heartbeat, config sync
Week 7-8: Token metering, approval round-trip

Stream B: Secrets Proxy (1 engineer)

Week 1-2: Proxy skeleton, 4-layer pipeline
Week 3:   P0 tests (TDD), performance benchmarks
Week 4:   Integration with OpenClaw LLM routing
Week 5+:  Secrets API (provide/reveal/generate/rotate)

Stream C: Hub Backend (1 engineer)

Week 1-4: Prisma models, tenant API endpoints
Week 5-6: Billing pipeline, Stripe meters
Week 7-8: Approval queue, agent config CRUD
Week 9-10: Customer portal API, chat relay

Stream D: Mobile + Frontend (1 engineer)

Week 1-4: (Can start UI mockups, design system)
Week 5-8: (Website landing page, onboarding flow)
Week 9-10: Mobile app core (auth, chat, approvals)
Week 11-12: Polish, settings, usage dashboard

Stream E: Provisioner + DevOps (1 engineer, part-time)

Week 1-4: Docker image builds, CI/CD pipeline
Week 5-8: Tool cheat sheets (P0 + P1)
Week 9-11: Provisioner update, n8n cleanup
Week 12: Integration testing, config.json fix

Minimum team size: 3 engineers (streams A+B combined, C, D+E combined) Recommended team size: 4-5 engineers (each stream dedicated)


8. Scope Cut Table

If timeline pressure hits, these items can be deferred to post-launch:

Item Phase Impact of Deferral Difficulty to Add Later
Interactive demo 4 No demo on website — use video instead Low
WhatsApp/Telegram channels 4 App-only access — channels are config, not code Low
P2+P3 tool cheat sheets 4 6 tools instead of 24 at launch Low
DNS automation 3 Manual DNS record creation (existing flow) Low
First-hour workflow templates 4 No guided first hour — users explore freely Low
Customer portal web UI 3 Mobile app only — no web dashboard for customers Medium
Overage billing 2 Pause AI at pool limit (no overage option) Medium
Custom agent creation 3 5 default agents only, no custom Medium
Founding member program 2 Standard pricing only — add multiplier later Low
Dynamic tool installation Post-launch Fixed tool set per provisioning — no add/remove Medium
Premium model tier 2 Included models only — add premium later Medium

Non-Negotiable (Cannot Cut)

  • Secrets redaction (the privacy guarantee)
  • Command classification + gating
  • Hub ↔ Safety Wrapper communication
  • Token metering (needed for billing even without overage)
  • Mobile app (primary customer interface)
  • Provisioner update (must deploy new stack)
  • 6 P0 tool cheat sheets

9. Critical Path

The longest chain of dependent tasks that determines the minimum project duration:

Monorepo setup (2d)
  → Safety Wrapper skeleton (2d)
    → Command classification (3d)
      → Executors (2d)
        → Autonomy engine (2d)
          → OpenClaw integration (2d)
            → Hub protocol (5d)
              → Token metering + billing (5d)
                → Approval queue (4d)
                  → Customer portal API (3d)
                    → Chat relay (2d)
                      → Mobile app chat (3d)
                        → Provisioner update (3d)
                          → E2E integration test (3d)
                            → Security audit (3d)
                              → Launch (1d)

Total critical path: ~42 working days ≈ 8.5 weeks

With parallelization (5 engineers), the 16-week timeline has ~7.5 weeks of buffer distributed across phases. This buffer absorbs:

  • Unexpected OpenClaw integration issues
  • Secrets redaction edge cases requiring additional work
  • Mobile app platform-specific bugs (iOS/Android)
  • Provisioner testing on real VPS hardware

End of Document — 04 Implementation Plan