<a id="getting-started"></a>

# Getting Started

Dads is a TypeScript backend framework and package suite built around three guarantees: every HTTP route declares an access rule before it can compile, relationship permissions run inside your PostgreSQL transactions, and domain boundaries are enforced in CI.

<a id="choose-your-starting-point"></a>

## Choose your starting point

| If you want to... | Start with |
| :-- | :-- |
| **Build a new TypeScript backend** with auth, workspaces, Postgres ReBAC, OpenAPI 3.1, and enforced boundaries wired from day one | Follow the walkthrough below (`npm create dads@latest`) |
| **Add Zanzibar permissions to an existing Postgres app** without running a separate authz database or outbox | [Permissions in Postgres & SpiceDB](https://dadsframework.dev/docs/permissions) |
| **Replace hand-written SpiceDB `.zed` files** with type-checked TypeScript and generated `.zed` output | [Adopt One Package at a Time](https://dadsframework.dev/docs/adopt-standalone) |

<a id="prerequisites"></a>

## Prerequisites

*   **Node.js 24** and **npm**
*   **Docker** (used by `npm start` to boot local PostgreSQL and the API stack)

<a id="1-create-a-project"></a>

## 1\. Create a project

Choose the **minimal** template for a clean backend without demo features, or the **example** template for a full runnable app with notes, attachments, exports, and a permissions UI.

Minimal template (clean start):

```sh
npm create dads@latest my-app -- --template minimal
cd my-app
```

Example template (full runnable workbench):

```sh
npm create dads@latest my-app
cd my-app
```

<a id="2-start-the-local-stack"></a>

## 2\. Start the local stack

Run `npm start` from `my-app`:

```sh
npm start
```

`npm start` boots PostgreSQL in Docker, applies migrations, starts both API entrypoints (`customer` and `staff`), and prints the local URLs.

1.  Open the browser URL printed by `npm start` and select **Create an account**.
2.  In a second terminal, run `npm run dev:mail` to read the local verification link (no SMTP setup required).
3.  Open the verification link, sign in, and create your first workspace.

Useful local commands:

| Command | What it does |
| :-- | :-- |
| `npm run dev:status` | Prints the running URLs and ports |
| `npm run dev:mail` | Shows local verification and invite emails |
| `npm run dev:down` | Stops the local Docker stack |

<a id="3-where-your-code-goes"></a>

## 3\. Where your code goes

Every Dads app splits code into four areas. `npx dad check boundaries` enforces these import rules in CI so features stay isolated as your team (or your coding agents) adds routes.

| Path | What lives here | Can import |
| :-- | :-- | :-- |
| `domains/<name>/` | Your business features: routes, Zod wire contracts, access rules, database tables, and typed clients. Ships with `domains/tenants/` for built-in auth, users, workspaces, and invites. | Framework packages and `libraries/*`. Never another domain. |
| `apps/<api>/app.ts` | Short manifests that pick which domain plugins and background jobs each HTTP server mounts (`customer/app.ts` for your users, `staff/app.ts` for internal tools). | Any `domains/*`, `libraries/*`, and `assembly/*`. |
| `assembly/` | Shared server startup, environment config, PostgreSQL pool, composed access model, migrations, and local dev scripts that boot the entrypoints in `apps/`. | Any `domains/*`, `apps/*`, and `libraries/*`. |
| `libraries/` | Shared runtime types and base entity handles (such as `libraries/app-runtime/index.ts`) that multiple domains need without importing each other. | Framework packages only. |
| `dads.project.json` | The boundary manifest read by `npx dad check boundaries` to verify every import rule. | Config file. |

> **Why is `assembly/` separate from `apps/`?** `apps/customer/app.ts` and `apps/staff/app.ts` are short manifests that choose which routes exist on each server. `assembly/` is the shared host that boots either entrypoint using the same PostgreSQL pool, auth setup, health checks, and migrations.

<a id="4-add-your-first-feature"></a>

## 4\. Add your first feature

Generate a relationship-guarded domain and mount it on the `customer` API:

```sh
npx dad add resource products --api customer
```

Pass `--dry-run` first to preview the generated files before writing them.

This creates `domains/products/` with its own contract, access rule, routes, and database table, registers the plugin in `apps/customer/app.ts`, and leaves `apps/staff/app.ts` untouched.

<a id="5-verify-boundaries-types-and-tests"></a>

## 5\. Verify boundaries, types, and tests

Run the full verification gate from your project root:

```sh
npm run verify
```

`npm run verify` runs four checks in order:

1.  `dad check boundaries` confirms no domain imports another domain's internals.
2.  TypeScript type-checking verifies every route declares an `access` rule and matching request/response schemas.
3.  The web client builds against your updated contracts.
4.  Vitest runs your unit and integration tests (with Docker running).

You can also run `npx dad doctor --gate` to check repo-wide rules such as zero `any`, zero unsafe casts, and denial test coverage.

<a id="next-steps"></a>

## Next steps

*   **Model and enforce permissions:** [Permissions in Postgres & SpiceDB](https://dadsframework.dev/docs/permissions)
*   **Define endpoints, Zod schemas, and clients:** [Routes, Contracts & Clients](https://dadsframework.dev/docs/routes-and-contracts)
*   **Split customer/staff APIs and enforce CI gates:** [Multi-API Composition & CI Gates](https://dadsframework.dev/docs/boundaries-and-apis)
*   **Use packages in an existing codebase:** [Adopt One Package at a Time](https://dadsframework.dev/docs/adopt-standalone)
*   **Why Dads enforces these rules:** [`DAD.md`](https://github.com/brytoncooper/dads-framework/blob/main/DAD.md) and [`Who let Gary back in?`](https://github.com/brytoncooper/dads-framework/blob/main/docs/go-ask-your-other-database.md)

Canonical page: <https://dadsframework.dev/docs/>
