106 lines
3.9 KiB
Markdown
106 lines
3.9 KiB
Markdown
|
# 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.
|