3.9 KiB

Raw Permalink Blame History

09. Repository Structure Proposal

1. Decision

Choose: Monorepo for LetsBe first-party code, with OpenClaw kept as separate pinned upstream dependency.

This is the best speed/quality tradeoff for a 3-month launch while preserving the non-fork requirement.

2. Why This Over Multi-Repo

2.1 Benefits

Shared TypeScript contracts across Hub, Mobile, Website, and Safety services.
One CI graph with selective test execution and consistent policy checks.
Easier cross-cutting refactors (API shape changes, auth, telemetry schema updates).
Better fit for AI-assisted coding workflows where context continuity matters.

2.2 Risks

Larger repo and CI complexity.
Migration effort from existing repo layout.

2.3 Mitigations

Use path-based CI execution and build caching.
Keep OpenClaw external to avoid massive vendor code in monorepo.
Execute migration in controlled steps with history-preserving imports.

3. Proposed Structure

letsbe-platform/
  apps/
    hub/                    # Next.js admin + customer portal + APIs
    website/                # public onboarding and marketing app
    mobile/                 # React Native + Expo
  services/
    safety-wrapper/         # OpenClaw plugin package
    egress-proxy/           # LLM redaction proxy
    provisioner/            # provisioning controller + scripts/templates
  packages/
    api-contracts/          # OpenAPI specs + TS SDKs
    policy-engine/          # shared classification and gate logic
    tooling-sdk/            # adapter framework + SECRET_REF utilities
    ui-kit/                 # shared design components (web/mobile where possible)
    config/                 # eslint/tsconfig/jest/shared tooling
  infra/
    gitea-workflows/
    docker/
    scripts/
  docs/
    architecture-proposal/
    runbooks/

4. OpenClaw Upstream Strategy (No Fork)

OpenClaw remains outside monorepo as independent upstream source:

Track pinned release tag in services/safety-wrapper/openclaw-version.lock.
CI job pulls pinned OpenClaw version for compatibility tests.
Upgrade workflow:
1. open compatibility PR bumping lock file
2. run hook-contract test suite
3. run staging canary tenants
4. promote if green

If a temporary patch is unavoidable, maintain patch as isolated overlay and upstream contribution plan; do not maintain long-lived fork branch.

5. Migration Plan From Current Repos

5.1 Current Inputs

letsbe-hub
letsbe-ansible-runner
letsbe-orchestrator (reference only, not migrated as active runtime)
letsbe-sysadmin-agent (reference only, patterns ported into Safety)
openclaw (kept external)

5.2 Migration Steps

Create monorepo skeleton and shared package manager workspace.
Import letsbe-hub into apps/hub with history.
Import letsbe-ansible-runner into services/provisioner.
Create new services/safety-wrapper and services/egress-proxy.
Scaffold apps/mobile and apps/website.
Extract shared contracts from hub into packages/api-contracts.
Add compatibility adapters so existing deployments continue during transition.
Archive deprecated repos as read-only references after cutover.

6. Governance Model

CODEOWNERS by area (hub, safety, provisioner, mobile, website).
Required reviewer policy:
- 2 reviewers for safety-wrapper, egress-proxy, provisioner secrets paths.
- 1 reviewer for non-security UI changes.
Architectural Decision Records (ADR) stored under docs/adr.

7. Alternative Considered: Keep Multi-Repo

Rejected for v1 because cross-repo contract drift is already visible in current state (legacy APIs, deprecated stacks, stale references). Under a 12-week launch window, contract drift risk is higher than monorepo migration overhead.

8. Post-Launch Option

After launch, if team scaling or compliance requirements demand stricter isolation, split out mobile and website into separate repos while preserving shared contract package publication.

3.9 KiB Raw Permalink Blame History