# Chassis

> A lightweight, decorator-driven Express + TypeScript backend starter.
> Controllers are classes with `@route`-decorated methods; exported
> controllers auto-mount; responses go through `req.resHandler`; errors
> are thrown as `AppError`; config is one validated zod schema.
> Modules are opt-in via environment variables and chosen at scaffold time:
> a database + ORM (Mongo/Mongoose, Postgres/Drizzle, or SQLite/Drizzle),
> auth (Auth0, local JWT, or Clerk), an optional Next.js front end, Sentry,
> an MCP server, and x402 payments (`@paidRoute`). With the front end the
> project is an npm-workspaces monorepo (`apps/api` + `apps/web`).
> `npm run verify` (typecheck + lint + test) is the quality gate.

## Conventions for code generation

- Add an endpoint: `npm run gen <Name>`, then edit the controller methods.
- Endpoints: methods on a class extending `Routable`, decorated with
  `@route('get'|'post'|..., '/path', [middlewares])`. Export the class
  from `src/controllers/index.ts` to register it.
- Responses: `req.resHandler.ok(data)`, `.created(data)`, `.noContent()`,
  `.notFound(msg)`, `.conflict(msg)`, `.validation(issues)`. Never call
  `res.status().json()`.
- Errors: `throw new AppError(ERROR_CODES.NOT_FOUND, 'message')`. No
  try/catch in controllers — Express 5 + a central handler catch throws.
- Validation: `validate({ body: zodSchema })` in the route middleware
  array. Parsed body replaces `req.body`.
- Config: only `src/config/index.ts` reads `process.env`; it's a zod
  schema and the app exits on invalid config.
- Never edit `src/core/**` for feature work.
- Local JWT ships `/auth/register` and `/auth/login`; users live in the
  configured database (`src/db/users.ts`), or in memory when there is none.
- Front end (only when `web/` or `apps/web/` exists): pages are server
  components, API calls go through `apiFetch` in `lib/api.ts`, and auth is
  imported from `auth/active.ts` — never from a provider directly.

## Docs

- [Agent guide](https://dvd90.github.io/chassis/#agents): conventions, do/don't, definition of done
- [Getting started](https://dvd90.github.io/chassis/#getting-started): scaffold to running API
- [Building an API](https://dvd90.github.io/chassis/#guides-building-an-api): a full CRUD resource
- [Database](https://dvd90.github.io/chassis/#guides-database): Mongo/Postgres/SQLite, ORM, DB-aware gen
- [Authentication](https://dvd90.github.io/chassis/#guides-authentication): Auth0, JWT, Clerk, custom providers
- [MCP](https://dvd90.github.io/chassis/#guides-mcp) and [Payments (x402)](https://dvd90.github.io/chassis/#guides-payments-x402)
- [Core API reference](https://dvd90.github.io/chassis/#reference-core-api): decorators, resHandler, AppError, validate
- [Configuration](https://dvd90.github.io/chassis/#reference-configuration): every env var
- [Architecture](https://dvd90.github.io/chassis/#architecture): request lifecycle, decorator flow
- [Modules](https://dvd90.github.io/chassis/#modules): the opt-in integration contract

## Full text

- [Every page, one file](https://dvd90.github.io/chassis/llms-full.txt)
- [Agent guide](https://dvd90.github.io/chassis/AGENTS.md): conventions and definition of done
- [Source](https://github.com/dvd90/chassis)