Documentation
The Damat Guide
A step-by-step walkthrough — from zero to a running, modular backend, then deeper into every building block. New here? Start with Introduction and Concepts.
Start here
1IntroductionUnderstand Damat's core idea: modular, TypeScript-first backends built from reusable domain blades.2Concepts and architectureBuild the mental model for modules, durable work, PostgreSQL truth, Redis acceleration, and runtime role separation.3Module boundaries and portabilitySeparate module-owned behavior from host-owned composition and lifecycle policy.4Execution primitivesChoose among route, workflow, job, event, and pipeline based on durability and restart needs.5Composition and durability runtimeSplit durable truth from acceleration, and understand runtime modes and migrations.6Getting startedCreate your first app quickly, provision PostgreSQL, understand generated structure, and run your first endpoint.7Prerequisites and local runProvision local PostgreSQL, optional Redis, and run the initial CLI and app startup flow.8Project structure walkthroughUnderstand how app contracts, module folders, and durable artifacts are organized.9Configuration & environmentLearn which knobs control modules, environment loading, worker selection, and policy settings in `damat.config.ts`.10Configuration sectionsMap `projectConfig`, `services`, `modules`, and `providers` to ownership and responsibilities.11Environment loading and variablesUnderstand env precedence, required variables, and module env declarations.12Choosing a runtime roleChoose server, worker, or combined runtime, and understand worker role behavior under restart.13Startup behavior and safetyLearn `runtime.mode`, worker roles, Redis fallback, and startup migration checks.
Build
14Defining models (the ORM DSL)Compose typed PostgreSQL schemas with fluent columns, relations, indexes, constraints, and migrations-ready model metadata.15Model columns and typesUse column builders and modifiers to define stable types and defaults without ad-hoc SQL.16Relations, indexes, and constraintsUse module-local relations and constraints, then isolate cross-module links in app-owned link modules.17MigrationsPlan schema changes safely across modules with generated snapshot diffs and shared durability/system migrations.18App migration workflowRun host-owned migration setup, checks, and status commands for safe startup and deploy flow.19Standalone module migration workflowUse module migration commands in local module context and keep ownership boundaries intact.20Modules & servicesTurn model definitions into typed domain services, typed credentials, and module entrypoints.21Querying & the CRUD serviceUse generated find/write APIs, where-operators, transactions, and optional read-cache/event/logging features.22Querying options and filtersMaster paging, filtering, sorting, and projection for generated service queries.23Transactions and consistencyUnderstand transaction scopes, validation, caching, events, and query logging.24Building HTTP APIsDesign file-based route trees with Hono, typed handlers, validation, and predictable response conventions.25HTTP validation and compositionSplit request validation and route middleware into predictable handler files.26AuthenticationAttach an auth provider, shape request principals, and secure routes with session/API-key based access.27Authentication implementationImplement the auth role using provider contracts and explicit route-level enforcement.28Integration providersAdopt provider role contracts (auth/payment/subscription) and expose clean integration seams from modules.29Provider implementation and integrationImplement payment and subscription-like providers with typed role methods and explicit module binding.30Workflows (the saga engine)Orchestrate local, compensable business steps with retries and timeouts while one process remains alive.31Implement a workflowBuild typed steps, compensation payloads, and a composed in-process saga.32Workflow reliability and errorsTune retries, timeouts, lock scope, and failure interpretation.33Redis acceleration and utilitiesAdd optional acceleration for cache, liveness, pub/sub, locks, sessions, and rate limiting without changing durability semantics.34Cache and rate limitsUse typed cache helpers, tag-based invalidation, and Redis-based per-identity request limits.35Locks, queues, and sessionsProtect critical sections and ephemeral queue patterns while keeping jobs/events durable in PostgreSQL.36Events and background jobsBuild retryable async work and per-consumer event delivery with PostgreSQL-first persistence and observability.37Define jobs and durable eventsDefine durable jobs/events, enable capabilities, and wire request-level transaction context.38Publish durable work atomicallyQueue jobs and publish durable events with transaction alignment and idempotency metadata.39Inspect and recover durable workInspect failed work, retry safely, and understand operational semantics under Redis fallback.40Durable pipelinesPersisted orchestration for restart-safe process flows with waits, branches, signals, and durable stage state.41Define a pipelineDesign node graphs with typed payload wiring, branches, loops, child pipelines, and resilient start/signal flows.42Start and signal a pipeline runStart pipeline runs and send durable signals with actor, reason, and idempotency context.43Configure and operate pipelinesConfigure workers, signals, migration readiness, retention, and production-safe fallback behavior.44LoggingTune structured logs and outputs for local debugging, production diagnostics, and operational diagnostics.45The default backend, end to endFollow the reference app end-to-end to map every subsystem to a real project structure.
Modules & sharing
46Authoring a moduleDesign a single-purpose module with models, config, migrations, tests, and install-ready contracts.47Module service and layeringKeep service boundaries strict from route to generated accessor, and stay portable.48Test and prepare a moduleValidate module behavior, publish safely, and keep install notes accurate.49Installing existing modulesLearn module installation workflows across registry refs, local paths, and git sources.50Plan and integrate an installPlan install targets, run module plan/add flows, and wire host-owned capabilities manually.51Source, package, and lifecycleUse package mode safely, review trust metadata, and update/remove modules cleanly.52Publish modules to a registryPublish modules safely with verification, release metadata, and optional self-hosted registries.53Installing modules with AI (MCP)Use the MCP server to discover, inspect, and install modules with reduced command context.54Module capabilitiesUnderstand the full capability surface: schema generation, migrations, workflows, orchestration, tests, and packaging.55Durable module capabilitiesMap module capability families and choose stable boundaries for jobs, events, and pipelines.56Installation and runtime ownershipAlign installer intent, transaction context, and runtime policy with host-owned behavior.57Composing & linking modulesCompose a backend from independent modules using links, `getModule`, registration, and explicit wiring.58Design an app-owned linkDefine app-owned cross-module relations with explicit link endpoints and ownership.59Activate and query linksRun migrations, query linked graph fields, and manage dormant shipped links safely.
Operate & reference
60CLI referenceFind exact commands for backend workflows: create, migrate, dev loops, install, build, and inspect.61DeploymentDeploy confidently with explicit migration jobs, stable runtime roles, and process-mode guardrails.62Containers, health, and rollbackSplit deployment into release, container, and rollback safety paths.63Package referenceJump straight to package APIs and internal docs from the same navigation tree as the guide.64TroubleshootingResolve startup, runtime, migration, and durability issues quickly with symptom-first checklists.65Runtime and durability faultsDiagnose pipeline, jobs, events, Redis, and startup signal issues.66Tooling and build faultsResolve module, MCP, and toolchain issues with command-first diagnostics.
Ready to build?
Scaffold an app and follow along.