<a id="multi-api-composition-ci-gates"></a>

# Multi-API Composition & CI Gates

Dads separates **which routes exist on an HTTP process** from **where domain code lives**, then checks import boundaries and code rules mechanically in CI.

![Multi-API composition across customer and staff entrypoints](https://dadsframework.dev/docs/source/website/site/assets/diagrams/multi-api-composition.svg)

<a id="1-compose-separate-api-entrypoints"></a>

## 1\. Compose separate API entrypoints

Each file under `apps/<api>/app.ts` is a short manifest calling `composeApi` from [`@dads-framework/plugin`](https://dadsframework.dev/docs/package-plugin). It selects the domain plugins and background jobs that entrypoint exposes (`apps/customer/app.ts`):

```ts
export function customerApp(provider: ServiceProvider) {
  return composeApi("customer", {
    services: [provider, starterAccess],
    routes: [
      tenantsPlugin,
      tenantPermissionsPlugin,
      notesPlugin,
      // dad:add domains
    ],
    jobs: [notesAttachmentWorker],
  });
}
```

`apps/staff/app.ts` mounts internal routes (such as audit exports) and omits `notesPlugin` completely:

```ts
export function staffApp(provider: ServiceProvider) {
  return composeApi("staff", {
    services: [provider, starterAccess],
    routes: [
      tenantsPlugin,
      tenantAuditExportPlugin,
      // dad:add domains
    ],
    jobs: [],
  });
}
```

Customer routes are not hidden behind a feature flag on the staff server; they are never registered on that Fastify instance.

<a id="2-enforce-domain-boundaries-with-dadsprojectjson"></a>

## 2\. Enforce domain boundaries with `dads.project.json`

`dads.project.json` declares your packages and the three boundary tiers:

```json
{
  "domainBoundaries": {
    "domains": ["src/domains/*", "domains/*"],
    "libraries": ["libraries/*"],
    "composition": ["src/composition", "apps/*", "assembly"]
  }
}
```

The import rules enforced by `npx dad check boundaries`:

*   **`domains/*`** can import framework packages and `libraries/*`. A domain can never import another domain's tables, routes, or internals.
*   **`libraries/*`** hold shared runtime tokens and base entity handles (such as `libraries/app-runtime/index.ts`) and import framework packages only.
*   **`apps/*` and `assembly/`** sit in the composition tier and wire domains together with real infrastructure (PostgreSQL, auth, mail, object storage).

When one domain needs data from another domain, define a narrow TypeScript port and wire the implementation in `assembly/services.ts` instead of importing across domains.

```sh
npx dad check boundaries
```

<a id="3-run-doctor-and-changed-file-verification-in-ci"></a>

## 3\. Run Doctor and changed-file verification in CI

Every starter includes `npm run verify` and the `@dads-framework/toolbox` CLI for local and CI gates:

| Command | What it checks |
| :-- | :-- |
| `npm run verify` | Runs boundary checks, TypeScript type-checking, web build, and tests |
| `npx dad check boundaries` | Fails if any file crosses a domain boundary or undeclared dependency |
| `npx dad doctor --gate` | Checks repo-wide rules: zero `any`, zero unsafe casts, routes with `access`, denial test coverage, and source budgets |
| `npx dad verify --changed --json` | Runs focused checks for files touched in the current branch |

> **Coding agents and CI:** Because boundaries, `access` declarations, and denial tests are verified by `dad check boundaries` and `dad doctor --gate`, broken imports or unguarded endpoints fail before code review.

<a id="4-deploy-outside-development"></a>

## 4\. Deploy outside development

Every generated starter ships with a `DEPLOY.md` and production scripts in `package.json`:

1.  Install dependencies from the committed lockfile with `npm ci` and run `npm run verify`.
2.  Set `DATABASE_URL`, `DADS_IDENTITY_SECRET`, and `DADS_BASE_URL` in your runtime secret store.
3.  Run database migrations once before booting new API instances:

```sh
npm run migrate
```

4.  Start each API process by selecting `DADS_API=customer` or `DADS_API=staff`:

```sh
NODE_ENV=production DADS_API=customer HOST=127.0.0.1 PORT=3000 npm run start:api
```

5.  Check liveness against `/api/health`:

```sh
curl -fsS http://127.0.0.1:3000/api/health
```

A healthy process responds with HTTP `200` and `{ "data": { "status": "ok" } }`.

<a id="related-references"></a>

## Related references

*   [`@dads-framework/toolbox`](https://dadsframework.dev/docs/package-toolbox) for all CLI commands and JSON output schemas
*   [`@dads-framework/plugin`](https://dadsframework.dev/docs/package-plugin) for `composeApi`, `defineService`, and `providePlugin`
*   [Architecture decisions](https://github.com/brytoncooper/dads-framework/blob/main/docs/decisions/README.md)

Canonical page: <https://dadsframework.dev/docs/boundaries-and-apis>
