# nexuscrm-app-packs — agent guide
> Official Salesforce-compatible CRM L1 product shape and connector definitions; the issue-tracker fixture is sealed and CI-only.

**You are in `nexuscrm-app-packs`** (L1 · product / Salesforce CRM dialect).
Use [`README.md`](README.md) for runnable commands and the current physical
layout. This guide is authoritative for layer/dependency rules and for the
issue-tracker classification; older multi-app wording does not confer product
status. 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 / pin owner | 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`; production pin owned by NexusCRM consumer manifests | Neutral typed contract / extension IR plus separately versioned generated Runtime wire module. The semantic root is runtime-pure (no `database/sql`, `net/http`, protobuf, or gRPC). |
| **nexuscrm-controlplane** | L0 | `…/nexuscrm-controlplane`; production pin owned by NexusCRM consumer manifests | Pack install / upgrade / migrate / verify / drift lifecycle + schema bootstrap (`bootstrapimpl`). Backend-free. |
| **nexuscrm-api-host** | L0 | `…/nexuscrm-api-host`; production pin owned by NexusCRM consumer manifests | Transport host primitives: dialect binding, middleware, websocket, security/version routes, process probes, and app-blind Runtime gRPC handler policy. |
| **nexuscrm-connectors** | L0 | `…/nexuscrm-connectors`; production pin owned by NexusCRM consumer manifests | Generic integration mechanisms: inbound execution, webhooks, outbound callouts, named credentials, connector registry, health, throttle, and sync state. It does not author provider definitions. |
| **nexuscrm-app-packs** | L1 | pack repo + product codec/dialect modules | Official Salesforce-compatible CRM packs/dialects/frontend, the independently publishable `sfcrm/querycodec` and `sfcrm/wire` modules, official connector definition packs such as `hubspot-crm-connector`, and one sealed CI-only non-CRM issue-tracker conformance fixture. No issue-tracker pack, dialect, frontend, distribution, or release surface exists. 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. |

Do not copy exact cross-repository versions into this guide. Resolve the
production-composition pins from the target NexusCRM revision's live
`backend/go.mod` and `backend/distributions/go.mod`; each app-packs `go.mod`
remains authoritative for its own module. An independently deployed L1
AppService composes released, app-blind L0 host/identity/Runtime client
primitives from `nexuscrm-api-host` and `nexuscrm-contract`; the AppService
module's `go.mod` selects the client libraries needed to compile it. Those Go
module versions are not an L1 dependency on an L0 service release and must not
be promoted into a deploy-time or runtime compatibility gate. That downward
`L1 -> L0` API dependency does not transfer CRM route, request, or response
semantics into L0.

### L1 -> L0 API and release boundary

- L1 depends on the **versioned neutral L0 API surface**: published contract,
  wire protocol, client/host primitives, and declared Runtime capabilities. It
  must not depend on a NexusCRM Core source commit, Runtime/Worker
  implementation revision, internal Go module, database schema, or process
  composition.
- L1 AppRelease metadata may declare an explicit protocol-version requirement.
  Absence of that version adds no extra constraint: use the neutral API's
  baseline compatibility contract and never infer a Core, Runtime, repository,
  module, or unified L0 release version. Capability declarations are not
  optional: every neutral Runtime capability consumed by a handler must be
  declared and enforced by Catalog/Controlplane installation. Do not replace
  those capability checks with a same-source-SHA requirement.
- A release/BOM may pin independently published L0 and L1 image digests into
  one deployable tuple. That is release selection evidence, not a source,
  compile, or runtime dependency from L1 to the chosen L0 implementation.
- Installing sfcrm uses the generic L0 Controlplane pack/AppRelease and Catalog
  publication surfaces. The L1 serving process calls the one private L0 gRPC
  endpoint and holds no Runtime database credentials. If installation requires
  checking out or compiling a matching NexusCRM Core revision, treat that as a
  Controlplane/deployment-boundary defect; do not preserve it in L1 tooling as
  a compatibility workaround.
- Do not make an L1 deployer infer compatibility from image labels or source
  SHAs. Build/release publishes immutable artifacts, the release tuple selects
  their digests, and the versioned L0 contract plus Catalog receipts own
  behavioral compatibility.

### 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** |
| Generic connector runtime / webhook execution / callouts / named credentials | **nexuscrm-connectors** (L0) |
| Salesforce CRM dialect / SObject·SOQL skin / CRM packs / app frontend | **nexuscrm-app-packs** (L1) |
| Official connector definitions / profiles / handler configs / route declarations | **nexuscrm-app-packs** (L1) |
| PingCAP tenant config / final pack / deploy | **nexuscrm-pingcap-pack** (L2) |

### Dependency direction (hard rules)

- The semantic root of `nexuscrm-contract` depends on the **Go stdlib only**;
  protobuf/gRPC dependencies stay in its separate `wire-go` module.
- `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 published public L0 modules; **L0 must not
  import L1**. An L1 AppService may assemble app-blind `nexuscrm-api-host`
  primitives, but must not copy or override their generic transport, identity,
  security, lifecycle, or Runtime-client policy and must not import NexusCRM
  `backend`, core internals, persistence, or database packages.
- `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: finite roadmap closed as scoped;
  broader cleanup remains incremental.** The named **L0-A … L0-F** sequence ran
  and reached explicit landed, non-carve, retained-compatibility, or deferred
  dispositions. It is neither "not started" nor proof that every future
  semantic-purity migration is done. Current status and residual owners live in
  NexusCRM `docs/architecture/repo-split.md`; new migrations require a
  current-tree consumer/owner audit and their own scoped contract.

## Working in this repo

- This is **L1 product/configuration shape**, not platform mechanism. It owns
  the Salesforce-compatible CRM packs, `dialect-sf-crm`,
  the stdlib-only `sfcrm/querycodec` and `sfcrm/wire` modules, the transitional
  `dialect-sf-crm-soql` compatibility module, CRM app frontend source, and official connector pack
  definitions such as `hubspot-crm-connector`. Generic connector and Runtime
  behavior belongs **upstream** in L0; tenant mappings, Flow bodies, and
  overlays belong **downstream** in `nexuscrm-pingcap-pack` (L2).
- Build / validate packs with the `crm` build tag and the app-packs guardrails — see
  [`README.md`](README.md) for the exact `cmd/setup` and `check:frontend-app-package-build`
  commands. Dialect modules: check this repo out under `NexusCRM/nexuscrm-app-packs` and
  run `GOWORK=off go test ./...`.
- Do **not** copy generated platform artifacts (`generated-api.ts`, `generated-schema.ts`,
  `generated-error-codes.ts`) here; app frontend imports platform code only through the
  public host SDK.
- `CLAUDE.md` and `AGENTS.md` are kept identical — edit both together.

### Sealed issue-tracker conformance boundary

- `tests/conformance/issue-tracker/` is a **CI-only, test-owned non-CRM
  conformance fixture**. It proves App-neutral contract behavior only. It is
  not a product App, AppService, production route, deployment/service/image,
  frontend requirement, AppInstallation, or proof of multi-App production
  operation.
- Release-shaped issue-tracker pack, dialect, frontend, distribution, install,
  deploy, and publication paths are forbidden. CI guards the absent paths and
  the fixture's public-neutral dependency closure, including test dependencies
  and future subpackages.
- The reviewed fixture payload and golden matrix are mirrored and checksummed
  by NexusCRM CI, which runs them through the real Runtime records adapter.
- Promoting issue-tracker into a real second App requires a separate product
  decision and production design; this fixture must never be promoted.