# NexusCRM

`NexusCRM` is a metadata-driven CRM platform.

This repository currently hosts the first runnable baseline of
`NexusCRM public-core v1`: a public-safe core that can bootstrap in an
external environment after private PingCAP content is removed.

## Product Direction

`NexusCRM public-core v1` is the first public baseline, not the final product
shape.

The intended open-source product model is:

- `public core`: the reusable platform runtime in `backend/`, `frontend/`, and
  `shared/`
- `tenant/app package`: installable metadata and configuration that define a
  team's business structure without forking platform source
- `business-data onboarding`: a separate import/sync lane for real tenant
  records

This keeps the product boundary aligned with the metadata-driven CRM contract
the current frontend and API surface are targeting:

- adopters boot the platform core
- install package/config payload for their app or tenant shape
- import or sync business data separately
- evolve business process through metadata/config changes rather than platform
  source edits

It is not intended to be adopted through long-term platform forks or
repo-local tenant overlays as the product-default model.

Current codebase evidence for that direction already exists, but the end-state
is not fully closed yet:

- `backend/internal/controlplane/packspec/` and
  `backend/internal/controlplane/tenantoverlay/` show package-like apply seams
- `backend/cmd/setup` and `backend/distributions/cmd/setup` provide the
  platform and product installation tools. Serving uses `backend/cmd/runtime-api`,
  `backend/cmd/runtime-worker`, the Integration processes, and the L1 AppService.
- `frontend/src/` is now shaped around the app-blind host runtime:
  `host-sdk/`, private `host/`, generated contracts, and thin bundled app-pack
  registration glue. CRM product frontend source is owned by the external
  app-packs repository.

What is not yet complete in this repository:

- first-class external package lifecycle and install tooling
- neutral example packages under `examples/`
- dedicated migration translation and validation tooling
- the final external-consumer contract for package upgrade, provenance, and
  cutover

## Current Scope

What this baseline includes:

- backend bootstrap, verify, and server startup
- frontend baseline startup and authenticated first-page flow
- public-safe standard-object smoke coverage
- open-source design pack and execution artifacts under `docs/open-source/`

What this baseline does not include:

- package lifecycle
- full external tenant onboarding
- private continuity packaging
- tenant overlay payload from `backend/internal/controlplane/tenants/**`

## Repository Layout

Top-level baseline directories:

- `backend/` — Go platform runtime plus distribution entrypoints under
  `backend/distributions/`
- `frontend/` — app-blind host runtime, host SDK, generated contracts, and
  app-pack registration glue
- `shared/` — Go packages shared by backend modules
- `docs/` — current design, runbooks, and architecture contracts
- `infra/` — deployment build assets such as Dockerfiles and entrypoints
- `tests/` — cross-module and integration-style test modules
- `data/` — local filesystem runtime data root for source checkouts

Key public documents:

- [Public Core Definition](docs/open-source/product/public-core-v1-definition.md)
- [Public Workspace Boundary Policy](docs/open-source/boundary/public-workspace-layout-and-content-policy.md)
- [Greenfield Bootstrap Contract](docs/open-source/self-hosting/public-greenfield-bootstrap-contract.md)
- [Greenfield Bootstrap Runbook](docs/open-source/self-hosting/greenfield-bootstrap-runbook.md)
- [Backend Greenfield Bootstrap](docs/open-source/self-hosting/backend-greenfield-bootstrap.md)

## Quick Start

Validated local environment:

- Go `1.24+`
- Node `v22.22.2`
- npm `10.9.7`
- Docker
- TiDB `v8.5.0`

Start a local TiDB (ephemeral, no persistent volume):

```bash
docker compose up -d        # uses ./docker-compose.yml
```

Prepare local env:

```bash
cp .env.example .env
export TIDB_PORT=4001
export TIDB_DATABASE=nexuscrm_public_core_v1_tidb85
export NEXUS_ADMIN_PASSWORD='<set-a-local-password>'
export FILE_STORAGE_ROOT="$PWD/data/object-storage"
export FILE_STORAGE_LEGACY_UPLOAD_ROOT="$PWD/data/uploads"
mkdir -p "$FILE_STORAGE_ROOT" "$FILE_STORAGE_LEGACY_UPLOAD_ROOT"
```

Filesystem storage paths may be absolute. When they are relative, source
checkout runs resolve them against the repo root; packaged deployments should
either set absolute paths or set `NEXUSCRM_RUNTIME_ROOT` to the intended base.

Check out the official app-packs repository under this checkout before running
CRM distribution commands or the default CRM-compatible frontend entrypoint.
Graduated L0 repositories (`github.com/pingcap-inc/nexuscrm-contract`,
`github.com/pingcap-inc/nexuscrm-api-host`,
`github.com/pingcap-inc/nexuscrm-connectors`, and
`github.com/pingcap-inc/nexuscrm-controlplane`) are consumed through pinned
module versions. The remaining root `nexuscrm-*` modules are still part of this
repo's modular monolith. The CRM dialect modules are L1 source owned by the
app-packs repository and compiled through `backend/distributions/go.mod`
replacements. The app-blind L0 host build
(`npm --prefix frontend run build:host`) does not provision or read app-packs
source. A downstream distribution build must pass both
`NEXUSCRM_FRONTEND_APP_PACKS_ROOT` and the exact
`NEXUSCRM_FRONTEND_APP_PACKS_REF` selected by its release BOM; this repository
does not select or pin an L1 frontend revision.

```bash
git clone git@github.com:pingcap-inc/nexuscrm-app-packs.git nexuscrm-app-packs
export NEXUSCRM_OFFICIAL_APP_PACKS_ROOT="$PWD/nexuscrm-app-packs"
export NEXUSCRM_FRONTEND_APP_PACKS_ROOT="$NEXUSCRM_OFFICIAL_APP_PACKS_ROOT"
export NEXUSCRM_FRONTEND_APP_PACKS_REF="$(git -C "$NEXUSCRM_FRONTEND_APP_PACKS_ROOT" rev-parse HEAD)"
```

Apply the L0 platform bootstrap:

```bash
bash -lc 'set -a; source ./.env; set +a; export TIDB_PORT=4001; export TIDB_DATABASE=nexuscrm_public_core_v1_tidb85; export NEXUS_ADMIN_PASSWORD="<set-a-local-password>"; cd backend && go run ./cmd/setup apply'
```

Install the Salesforce-compatible CRM L1 app pack before running CRM object
smokes. The CRM pack uses CRM distribution host primitives, so run the setup
entry point with the same `crm` build tag used by the CRM server:

```bash
bash -lc 'set -a; source ./.env; set +a; export NEXUSCRM_OFFICIAL_APP_PACKS_ROOT="$PWD/nexuscrm-app-packs"; export TIDB_PORT=4001; export TIDB_DATABASE=nexuscrm_public_core_v1_tidb85; cd backend/distributions && GOWORK=off go run -tags crm ./cmd/setup install-pack --source official_repo:salesforce-crm-standard'
bash -lc 'set -a; source ./.env; set +a; export NEXUSCRM_OFFICIAL_APP_PACKS_ROOT="$PWD/nexuscrm-app-packs"; export TIDB_PORT=4001; export TIDB_DATABASE=nexuscrm_public_core_v1_tidb85; cd backend/distributions && GOWORK=off go run -tags crm ./cmd/setup verify-pack salesforce-crm-standard'
```

Verify the bootstrap result:

```bash
bash -lc 'set -a; source ./.env; set +a; export TIDB_PORT=4001; export TIDB_DATABASE=nexuscrm_public_core_v1_tidb85; cd backend/distributions && GOWORK=off go run -tags crm ./cmd/setup verify'
```

The source-backed install invalidates the earlier `ApplyAll` marker. Before
direct server startup, enter the same lock-held authority used by container
`auto` mode. This run performs full `ApplyAll`, re-verifies the installed
composition, and restores the marker:

```bash
bash -lc 'set -a; source ./.env; set +a; export NEXUSCRM_OFFICIAL_APP_PACKS_ROOT="$PWD/nexuscrm-app-packs"; export TIDB_PORT=4001; export TIDB_DATABASE=nexuscrm_public_core_v1_tidb85; cd backend/distributions && GOWORK=off go run -tags crm ./cmd/setup apply-if-needed'
```

Setup command boundaries:

- `setup apply` runs the full L0 control-plane bootstrap path: substrate schema,
  managed metadata, repair, runtime packs, optional dev sample, derived-state
  rebuild, indexes, and final verification. L1 app packs install explicitly
  with `setup install-pack --source ...`; that source-backed mutator invalidates
  the completed marker, so `setup apply-if-needed` must restore it before direct
  server startup.
- `setup apply-metadata` only prepares the platform foundation. It creates or
  updates the system schema and reconciles core managed metadata so later pack
  commands have a valid database substrate. It does not install CRM or other app
  packs, does not run repair, does not rebuild derived state, and does not
  replace `setup apply` for rollout verification.
- `setup apply-packs` applies runtime platform packs and the optional dev
  sample on top of an already prepared metadata substrate.

Start the serviceified deployment through the target L2 delivery repository's
checked-in runbook. It supplies the Runtime API, Runtime Worker, Integration,
and L1 AppService configuration and the frozen release inputs. The monolithic
server commands and image have been retired; installing metadata alone does
not launch the serving topology.

Start the frontend:

```bash
cd frontend
npm ci
npm run dev -- --host 127.0.0.1 --port 5174 --strictPort
```

Open the app:

- frontend: `http://127.0.0.1:5174`
- backend health: `http://127.0.0.1:3001/health`

## Local Bootstrap Credentials

During local bootstrap, set `NEXUS_ADMIN_PASSWORD` to a password of your own
choice. That value becomes the bootstrap admin password for your local proof
environment.

The exact bootstrap admin email and seeded login identity are runtime/bootstrap
details for the current baseline, not part of the long-term public product
contract.

Authenticated smoke scripts also require explicit local credentials:

- `NEXUS_SMOKE_EMAIL`
- `NEXUS_SMOKE_PASSWORD`

## Verified Baseline

The current baseline has been validated for:

- greenfield backend bootstrap on local TiDB `v8.5.0`
- `setup apply`
- explicit distribution CRM-tagged
  `cd backend/distributions && GOWORK=off go run -tags crm ./cmd/setup install-pack --source official_repo:salesforce-crm-standard`
- `cd backend/distributions && GOWORK=off go run -tags crm ./cmd/setup verify-pack salesforce-crm-standard`
- distribution CRM-tagged `cd backend/distributions && GOWORK=off go run -tags crm ./cmd/setup verify`
- distribution CRM-tagged `cd backend/distributions && GOWORK=off go run -tags crm ./cmd/setup apply-if-needed`
- backend startup on `127.0.0.1:3001`
- backend restart safety
- frontend first-page load on `127.0.0.1:5174`
- authenticated dashboard-shell smoke
- authenticated CRM/v63 `/object/Account` list conformance smoke
- authenticated CRM/v63 `Account` create/edit/delete conformance smoke
- authenticated CRM/v63 `Contact` create/detail conformance smoke

Frontend CRM/v63 conformance smoke commands:

```bash
cd frontend
npm run conformance:crm-v63:auth-object
npm run conformance:crm-v63:record-create
npm run conformance:crm-v63:record-crud
npm run conformance:crm-v63:second-object
```

The legacy `smoke:auth-*` package scripts remain as compatibility aliases for
these CRM/v63 conformance commands. L0 host SDK boundary coverage is separate:
`cd frontend && npm run check:l0-sdk-boundary`.

## Boundary Notes

This public baseline intentionally excludes:

- `backend/internal/controlplane/tenants/**`
- private tenant payloads and overlays
- PingCAP-specific deploy continuity

The extraction strategy for this repo is allowlist-based. It is not a
"copy the whole private repo and delete things later" flow.

## Status

Current status:

- first allowlist import completed into an originally empty public repo
- bootstrap closure completed for backend and frontend baseline
- greenfield public bootstrap proof completed for the current scope

This means the repository is at a usable `public-core v1` first baseline, not
the final end-state of the entire open-source migration.