# nexuscrm-controlplane — agent guide
> Lifecycle orchestration: pack install, upgrade, migrate, verify, drift, and schema bootstrap.

**You are in `nexuscrm-controlplane`** (L0 · lifecycle & bootstrap). This repo's own concern definition, public
surface, and dependency rules live in [`README.md`](README.md). The
platform-wide map below tells you where every *other* concern lives, so you land
in the right repo before writing code.

## NexusCRM platform — repository & module map

The platform is split **by release boundary** into seven repositories across
three layers. Rule of thumb: a *repository* is a release boundary, a *Go module*
is an architecture boundary, a *package* is an import boundary. Dependencies
always point **down** — `L2 → L1 → L0` — and inside L0 everything depends on the
neutral contract while nothing depends back up.

- **L0 — platform mechanism** (app-blind: knows metadata / records / policy, not
  Salesforce and not any tenant). Five repos.
- **L1 — product / dialect** (the Salesforce-compatible CRM shape). One repo.
- **L2 — tenant delivery** (one customer's overlays + final pack + deploy). One repo.

### The seven repositories

| Repo | Layer | Module path / pin | Owns |
|---|---|---|---|
| **NexusCRM** (core) | L0 | `github.com/nexuscrm/*` (workspace) | The engine + host + frontend: `metadata`, `records`, `automation`, `analytics`, `permissions`, `persistence`, `storage`, `db`, `auth`, `audit`, `events`, `files`, `outbound`, `kernel`, the `backend` HTTP host, the React `frontend`, and `tools/boundarygate`. The mutually-recursive engine SCC stays here as a modular monolith. |
| **nexuscrm-contract** | L0 | `github.com/pingcap-inc/nexuscrm-contract` `v0.1.0` | Neutral typed contract / extension IR. Dependency root; runtime-pure (no `database/sql`, no `net/http`). Everything imports it; it imports nothing back. |
| **nexuscrm-controlplane** | L0 | `…/nexuscrm-controlplane` `v0.1.4` | Pack install / upgrade / migrate / verify / drift lifecycle + schema bootstrap (`bootstrapimpl`). Backend-free. |
| **nexuscrm-api-host** | L0 | `…/nexuscrm-api-host` `v0.1.0` | Transport host primitives: dialect transport binding, auth / session / permission middleware, websocket, security headers, version routes. |
| **nexuscrm-connectors** | L0 | `…/nexuscrm-connectors` `v0.1.0` | Integration runtime: inbound events / routing, webhooks, outbound callouts, named credentials, connector registry (capabilities / health / throttle / sync state). |
| **nexuscrm-app-packs** | L1 | pack repo + `…/dialects/dialect-*` modules | Official Salesforce-compatible CRM packs, the SF CRM dialect Go modules (`dialect-sf-crm`, `dialect-sf-crm-soql`), app frontend source, and a sealed CI-only non-CRM conformance fixture. Consumed via `official_repo:<pack>` + `NEXUSCRM_OFFICIAL_APP_PACKS_ROOT`. |
| **nexuscrm-pingcap-pack** | L2 | tenant pack repo | PingCAP tenant overlays, final merged pack assembly, bootstrap / deploy orchestration. Nothing depends on it. |

### Where each concern lives (routing table)

| If you need to work on… | Go to |
|---|---|
| Metadata engine / schema interpreter | NexusCRM → `nexuscrm-metadata` |
| Records CRUD / query execution | NexusCRM → `nexuscrm-records` |
| Flow / validation / automation | NexusCRM → `nexuscrm-automation` |
| Reports / dashboards / analytics | NexusCRM → `nexuscrm-analytics` |
| Permissions / FLS / RLS / sharing | NexusCRM → `nexuscrm-permissions` |
| Persistence / storage / DB driver | NexusCRM → `nexuscrm-persistence`, `nexuscrm-storage`, `nexuscrm-db` |
| Auth / session / JWT | NexusCRM → `nexuscrm-auth` (+ `nexuscrm-api-host` middleware) |
| Audit / events / outbox | NexusCRM → `nexuscrm-audit`, `nexuscrm-events`, `nexuscrm-outbound` |
| Files / attachments | NexusCRM → `nexuscrm-files` |
| Backend HTTP host, REST handlers, engine wiring | NexusCRM → `backend` |
| React runtime + host SDK | NexusCRM → `frontend` (`src/host-sdk`, `src/host`) |
| Module-boundary gate / policy | NexusCRM → `tools/boundarygate` |
| Neutral types / contract / IR | **nexuscrm-contract** |
| Pack install / upgrade / verify / drift / bootstrap | **nexuscrm-controlplane** |
| Transport host, dialect binding, middleware, websocket | **nexuscrm-api-host** |
| Connectors / webhooks / callouts / named credentials | **nexuscrm-connectors** |
| Salesforce CRM dialect / SObject·SOQL skin / official packs / app frontend | **nexuscrm-app-packs** (L1) |
| PingCAP tenant config / final pack / deploy | **nexuscrm-pingcap-pack** (L2) |

### Dependency direction (hard rules)

- `nexuscrm-contract` depends on the **Go stdlib only**; every other L0 module imports it.
- `nexuscrm-controlplane`, `nexuscrm-api-host`, `nexuscrm-connectors` depend on the
  contract (+ pinned `github.com/nexuscrm/*` core modules) but **must not import `backend`**.
- `NexusCRM/backend` consumes the published L0 modules as **version pins** (no local
  `replace` on `main`).
- `nexuscrm-app-packs` (L1) builds on the platform's public contract; **L0 must not import L1**.
- `nexuscrm-pingcap-pack` (L2) consumes NexusCRM + app-packs **by ref**; nothing depends on it.
- Inside NexusCRM the engine modules form a mutually-recursive SCC and are kept as
  **one modular monolith** — deliberately *not* split into separate versioned repos.

### Phase status — don't mistake interim state

- **Phase 1 — physical / release split: ✅ merged to `main`.** Seven-repo topology,
  published L0 modules consumed via real version pins, `boundarygate` Forbidden-edge = 0.
- **Phase 2 — L0 / L1 / L2 semantic purity: ⏳ not started.** Rule: *mechanism stays in
  L0; Salesforce / product / tenant shape moves to L1 / L2.* The binding execution
  contract (sequence **L0-A … L0-F**, 12-point DoD) lives in NexusCRM
  `docs/architecture/repo-split.md`. **Do not start Phase 2 behavior migration outside
  that contract.**

## Working in this repo

- **Never import `backend`.** This module is backend-free and independently testable;
  `backend` and `backend/distributions` drive it, not the other way round.
  `boundarygate` fails closed on any `controlplane → backend` edge.
- Lifecycle / bootstrap **mechanism** only — no Salesforce route projection, no tenant
  deploy shape, no product business behavior.
- Build / test: `go build ./... && go test ./...`. Some cross-repo guards skip unless
  `NEXUSCRM_REPO_ROOT` points at a NexusCRM checkout.
- Published as `…/nexuscrm-controlplane`; consumers pin a tag (current `v0.1.4`).
- `CLAUDE.md` and `AGENTS.md` are kept identical — edit both together.