Skip to content

Documentation

Summary. This is the index of the long-form documentation of ddd-ts-kit. Four entries are normative, two short reference documents first: the architecture reference (the canonical tree, the rule ids, the tactical and clean code conventions, the test levels) and the configuration reference; then the pipeline README (the quality gates) and the README of each package. Everything else explains and teaches: the concepts behind the rules, the tool decisions with their comparisons and limits, and guides for working on such a project as a team and with coding agents. When a page here and the architecture reference disagree, the reference is right.

In French. Every page listed here has a French translation next to it (X.fr.md), reached by the link on its first line; the French index is README.fr.md. Its diagrams have French labels, and its code samples are compiled by the pipeline like the English ones.

On the web. These pages, the README of every package and the documents of the example are also published as a website, with search, in English and in French: https://ddd-ts-kit.github.io/ddd-ts-kit/. The Markdown files here stay its only source.

The normative reference at the top (ARCHITECTURE.md, CONFIG.md, the pipeline README, the package READMEs); under it the concepts that explain it, the tools pages that choose a stack value, the guides that apply it and the proposals that may change it

Page What it holds
Architecture reference the canonical tree, every rule id, the tactical rules, tests, clean code
Configuration every key of ddd-ts-kit.config.json
Versions and stability what a patch and a minor version may hold before 1.0, the ranges a project holds, upgrading, what 1.0 will guarantee
Lines left out of the coverage measure the checks nothing can reach, why, and when each one goes
Cached entries per tenant why cached files an entry under the tenant, throws without the scope, and skips an elevation
The in-memory tuple store refuses production what createTupleStore allows, what an unset NODE_ENV does, and what reverses it
The regulated guard runs no program of the project how the profile is read, why no denyWrite, and the checks the profile gives up
A refusal is an error at once before 1.0 no transition, alias or shim before 1.0; a break ships with a To move line
The regulated guard runs git in its root only the one repository the guard runs git in under the regulated profile, and what it leaves unread
The guard names the readers of VS Code the tools of VS Code that write nothing, and why a list of readers and not of writers
A read model store on OpenSearch each choice of @ddd-ts-kit/opensearch, and what reverses it
init wires OpenSearch init --search opensearch: the tenancy, the provisioning of the declared stores, no generator yet, and what reverses each
Pipeline the quality gates, the git hooks, GitHub and GitLab side by side
Package READMEs under packages/ what each package does, its limits and what was verified

Ordered as a reading path in concepts/README.md.

Page In one line
Domain and subdomains core, supporting, generic: how to classify and what it changes
Bounded context what a boundary is, and the language, autonomy and consistency tests
Modules of the model a context too large to read, divided into parts of one model (Evans), not into sub-contexts: the gains, the limits, how to adopt them
Ubiquitous language the glossary-first rule and how a glossary is written
Context map the relationship patterns, when each fits and what it costs
Context map: a worked example the scheduling application, from a statement of needs to its map
Entities and value objects identity versus value, and primitive obsession
Aggregates consistency boundary, one transaction, reference by id, sizing
Domain building blocks domain event, domain service, repository, factory
State machines the lifecycle of an aggregate: states, transitions, guards, refusals, its diagram
Invariants, permissions, validation three different things in three places
Anemic model how to recognise one, and when a thin model is fine
Layers and the dependency rule hexagonal, onion, clean: what they share, where they differ
Ports and composition ports as abstract classes, the composition root, declared or explicit wiring
The presentation layer one controller class per route, route groups, guards at the edge and permissions on the use case, mapper and serializer
Representations, field access and forms one schema in JSON, XML or CSV by content negotiation, fields reserved to a permission, forms described by the server for each caller
CQRS command and query buses, and event sourcing as a separate choice: what it buys and what it does not
Modular monolith one deployable, contexts kept extractable
Domain and integration events the two kinds of events and the translation between them
Transactional outbox the dual write problem, the outbox, relay strategies
Delivery and idempotency at-least-once, idempotent consumers, ordering
Eventual consistency explained to a product person
Sagas and process managers long-running processes: what the kit provides and what it does not
Event versioning evolving a published event
Event sourcing, per aggregate when to keep an aggregate as its events, what it costs, upcasters, crypto-shredding, projections fed by the store, migrating to it and back
Personal data in a generated project what init --privacy on and generate repository --personal write, the erasure and the export of a person end to end, the two modes of erasure, the retention purged every night, the register generated by docs, the privacy/* rules, what stays out of reach and what the tool does not decide
Authentication and authorization RBAC, ABAC, ReBAC compared, with a decision table
Authorization in practice @Requires, the bus middleware, the Authorizer port and policies, followed through one command
Actor and execution scope the explicit actor, and what every unit of work carries
Multitenancy the tenant from the edge to the storage: isolation strategies, propagation, elevation of platform staff, the proof
Audit trail tamper-evident history recorded around the use cases
Observability tracing, logs, metrics, error reporting, the correlation id
Resilience retry, timeout, circuit breaker, bulkhead, cache and their failure modes
HTTP caching what to cache at which layer, cache policies, never a decision of authorization across actors
File storage files in a storage, never in the database: staged before the transaction, moved to their key with the commit, served by short signed links
Scheduled jobs jobs that trigger use cases, several instances, idempotence
Background jobs work enqueued in the transaction of a command, run by a worker at least once, leases, checkpoints
File import and export a design, not built: a large file read or written by a background job, batch by batch, between the queue and the file storage
Clean code naming, small functions, stepdown, comments, with before and after
Testing strategy fakes versus mocks, builders, contract tests, the four levels

Each page has a comparison table, selection criteria, what the kit supports and verified, the limits, and a recommendation by situation.

Page The decision
HTTP frameworks Express, Fastify, Hono or NestJS, and what framework-agnostic routes cost with Nest
Validation zod, class-validator, TypeBox or a Standard Schema library; shared schemas
Contract pairs which framework with which validation library, by team: the four pairs proven end to end, measured; oRPC and tRPC as a second door, not a pair
Representations and forms XML and CSV without a library, and why; JSON Forms renderers for React, Angular and Vue, and the alternatives
Dependency injection the kit's declarations on tsyringe, InversifyJS or Awilix, NestJS, or manual wiring, compared and measured
Persistence Drizzle, Knex, Prisma or TypeORM; PostgreSQL versus others; a read model on OpenSearch
Search read models a read model on OpenSearch: what fits and what does not, init --search opensearch, the store of a context, its tests, its tenants, in production
Message brokers in-process, RabbitMQ, Kafka, NATS JetStream or Redis Streams
Cache and coordination Redis, Dragonfly or Valkey; what the lock does and does not guarantee
HTTP caches Varnish, Souin, nginx, Fastly, Cloudflare or Bunny in front of the API: how each purges by tag, what the kit verified
File storage connectors memory, local directory or S3 compatible (AWS, MinIO, OVHcloud, Scaleway, R2); how to write one for Google Cloud Storage or Azure
Identity Keycloak or plain OIDC and JWT
Authorization engines in-process models versus OpenFGA, SpiceDB, Cedar, OPA
Observability OpenTelemetry with Jaeger or Tempo; loggers; Sentry or GlitchTip
Static analysis and pipeline the checker, the ESLint plugin, dependency-cruiser, knip, TypeScript 6 and 7; GitHub or GitLab
Quality baseline what every project gets and what each tool answers: type check, lint, format, dead code, import graph, architecture check, tests
Test runners Vitest or Jest
Client SDK openapi-typescript with openapi-fetch, hey-api or orval, measured on the example contract, against the client ddd-ts-kit sdk writes: typed error codes, no dependency; how it is checked and published
Import aliases @/, declared once under tsconfig paths and rewritten into relative paths by the build; imports without an extension by default, and why the build writes the .js Node needs; why not a Node subpath import; what each tool reads
Page For
Methodology the end-to-end path from a statement of needs to running code, step by step: the supported path
Which command, when the command or skill for each moment of a project, a first feature from zero, and the reference of every command and flag
One slice, end to end the request POST /orders through the four layers of a generated slice, and its domain and application code once filled
The plugin for coding agents installing the plugin in Claude Code, Codex and Copilot, its twenty-six skills, six agents and hook, and what each host runs
Composing the kit with other tools the kit inside an Nx workspace and beside Superpowers, from real sessions: one Nx project for the kit project, what to work around, which tool reports which import, two sets of agent instructions; which plugin conducts a feature, a plan, a test and a bug, and the section of AGENTS.md that decides it; Spec Kit and BMAD from a whole flow each, and the documents each writes beside those of the kit
Team workflow ownership per context, the glossary, contracts first, review, decisions, onboarding
Parallel work several people or agents at once: what is safe, what is sequenced, a concrete plan
Story workflow one session per user story, one story per terminal: questions first, design review and acceptance tests before the code, a report of every provisional decision
Closing the loop from a metric out of its band to the next story: the queries on the metrics the kit emits, a bands.yaml with three tiers, what a stateless run needs, the incident record a fix story starts from, what arrives from a chat channel
Commit discipline commit and pull request size, generated files, what hooks and CI enforce
A handler with many dependencies constructor over-injection read as a smell: an order of diagnosis, each remedy with its place in the tree, no limit
A cycle between two contexts three questions before merging: one language or two, an event for one direction, a missing concept
When to extract microservices the signals, the costs, a readiness checklist, the steps, when to merge back
Bootstrap with well-designed contexts a generic context written whole with --preset identity: what it writes, what it asks of the stack, how it composes with each access model and with tenants
Choosing access control five questions that pick roles, attributes or relationships (Zanzibar), worked presets for each, the combined model of the example, scopes and refusals at the edge
Token economy spending fewer tokens with coding agents, and complementary tools
Sandboxing coding agents what loads a machine and what the kit does about it; capping an agent, the sandbox of the agent, NVIDIA OpenShell for the security of a session
Deploy and rollback what a project ships beyond its image, the order of a release, what a rollback of each piece means, three tiers of autonomy for an agent by environment, deploy, status and rollback as one script each, the rehearsal in staging
The French documentation contributors: how every page keeps its French translation current, the glossary, the style of the diagrams, the code samples the pipeline compiles
Page Status
Which contexts deserve a preset the criteria, then notification next, personal data requests as a guide; files (a capability of the platform), audit, billing and settings no
Modules inside a bounded context built: sub-contexts are not a concept of the references, modules of the model are (Evans); the judgement of its gains and limits, and the spike that measured the cost on the example
The read side criteria, representations, forms, read models and projections; the page says, part by part, what is built in the runtime packages, what the CLI does not generate yet and what is not built
Velocity of the build, the checks and the tests studied, not built: where the time and the memory of this repository go, on a workstation and in the pipeline; the levers of Vitest, ESLint, Oxlint, the native compiler and the package managers measured on this tree; what other teams published about orchestrators, test selection and GitHub Actions; a plan in order of gain per cost, and why no orchestrator; the tools of the oxc-project (Oxlint, Oxfmt, tsdown, oxc-transform, the Oxc transform of Vitest) measured on 2026-10-26, with a verdict for each and the plan of their adoption
The families that generate projects studied, one line built, then the levers the maintainer decided on 2026-10-26: what the pipeline jobs that generate projects cost per run and per day on a pull request, the trunk and at night (70 percent of a pull request run), what they repeat, nine levers with their gain and what a pull request would no longer prove, and a plan of pull requests in order of gain per effort
Privacy by design, beyond event sourcing built, every part: why the kit, which erased the personal values of stored events alone, now declares the personal fields once and reads them in ports with an adapter per ORM (erasure, export, retention), generators, a register and privacy/* rules; the pull requests in merge order, the example adopting the ports; what a tool can never guarantee and the words to use
A second example, spend management on the most popular stack specified, not built: NestJS, Prisma, Jest, Kafka, S3, ABAC on a business of money and workflows; first the four capabilities that stack switches off today (queue and processes on Nest, tenancy and audit on Prisma, the identity preset), then the example as the proof; MySQL left out, with what it would take
Where to take the kit next, from what neighbouring tools do proposed, not built: sixteen neighbouring tools read on 2026-10-25 (agent methods, DDD plugins, import boundary tools, CQRS and event sourcing runtimes), nine proposals rated by value, cost and relevance, in tiers (now, next, later), and what the comparison suggests that the kit should not do, with the reason
Your question Where the answer is
Where does this file go, and what may it import? the architecture reference, 2. Canonical tree and 3. Dependency rules
Why was this reported, and how do I fix it? npx ddd-ts-kit explain <rule-id>, then When something is refused
Which command, or which skill, now? Which command, when
Does this rule belong in the aggregate, the handler or the schema? Invariants, permissions, validation
Why does the generator refuse my name? Ubiquitous language: a name comes from the glossary of its context
How does one context react to another? Domain and integration events, then Transactional outbox
How do I test a handler without a mock? Testing strategy
Which value for a stack key? the tools page of the decision, then Configuration
A rule does not fit this project Deviations: a recorded decision, never a silent off
What changes after an upgrade of the kit? Versions and stability, Migrate after a kit upgrade and a key left out of stack

Part of the reference also answers in the terminal of a project, from the installed version of the kit, so it never disagrees with the code you run:

Terminal window
npx ddd-ts-kit rules # every rule id, its severity and what it holds
npx ddd-ts-kit explain imports/alias-only # why a rule exists, a bad and a good example, how to suppress it
npx ddd-ts-kit generate --help # every kind of file the generator writes, and its flags
npx ddd-ts-kit describe billing # one context as facts: use cases, routes, events, ports

New to DDD. Follow the reading path of concepts/README.md in order, at least sections 1 and 2, then:

  1. Layers and the dependency rule
  2. Domain and integration events and Eventual consistency
  3. Testing strategy
  4. Methodology, to see the ideas as steps
  5. the architecture reference, which will now read as a summary

Tech lead adopting the kit.

  1. the root README and the architecture reference
  2. Methodology
  3. the tools pages for the decisions you have to take, starting with Persistence, Message brokers and Static analysis and pipeline
  4. Modular monolith and When to extract microservices
  5. Team workflow, Parallel work, Commit discipline
  6. Token economy, if the team works with coding agents
  7. Configuration
  8. Personal data, before production: what is declared, erased, exported and purged, and what stays the decision of the controller

Contributor to the kit.

  1. CONTRIBUTING.md at the root, then the architecture reference: a change of rule starts there
  2. Ports and composition and Layers and the dependency rule
  3. the README of the package you change, and of the CLI and the ESLint plugin, which hold the rules
  4. Static analysis and pipeline and Testing strategy
  5. the tools page of the area you touch: it states what was verified and what was not, which is where a contribution is most useful
  6. The French documentation, before changing a page: its French translation changes in the same pull request