# 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

```text
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

1. Create monorepo skeleton and shared package manager workspace.
2. Import `letsbe-hub` into `apps/hub` with history.
3. Import `letsbe-ansible-runner` into `services/provisioner`.
4. Create new `services/safety-wrapper` and `services/egress-proxy`.
5. Scaffold `apps/mobile` and `apps/website`.
6. Extract shared contracts from hub into `packages/api-contracts`.
7. Add compatibility adapters so existing deployments continue during transition.
8. 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.