# tx-agent-kit

> You tell the agent what to build. The agent builds it. The repo makes sure the agent builds it right.

tx-agent-kit is a production TypeScript monorepo where AI agents do the implementing and mechanical checks keep them honest. Effect HTTP, Temporal, Next.js, Drizzle, Expo. Every architectural rule is a lint check, not a prayer.

## Start here

[Welcome](/docs): What this project is and how to orient yourself
[Local Setup](/docs/getting-started/local-setup): Clone, install, and run everything in under 5 minutes
[Your First Domain](/docs/getting-started/first-domain): Scaffold a real feature end-to-end with one command

## Understand the philosophy

[Why tx-agent-kit exists](/docs/philosophy): The agent-first engineering thesis
[Why this is different](/docs/philosophy/why-different): Tribal knowledge dies. Lint rules don't.
[The operating model](/docs/philosophy/operating-model): You steer intent. Agents implement. The repo enforces.
[Mechanical enforcement](/docs/philosophy/mechanical-enforcement): If it matters, it's a check. 50+ invariants and counting.

## Learn the architecture

[Architecture overview](/docs/architecture): The big picture: 4 apps, 8 packages, strict boundaries
[Monorepo structure](/docs/architecture/monorepo-structure): What lives where and why
[DDD pattern](/docs/architecture/ddd-pattern): domain/ → ports/ → application/ → adapters/
[Dependency flow](/docs/architecture/dependency-flow): Dependencies point inward. ESLint enforces it.
[Data flow](/docs/architecture/data-flow): Web → API → Core → DB → Worker, traced end to end

## Master the core concepts

[Effect services](/docs/core-concepts/effect-services): DI, layers, typed errors. The backbone of the API.
[Domain modeling](/docs/core-concepts/domain-modeling): Pure functions. No Date.now. No Math.random. Testable in isolation.
[Ports and adapters](/docs/core-concepts/ports-and-adapters): Interfaces in ports/. Implementations in packages/db.
[Schema contracts](/docs/core-concepts/schema-contracts): effect/Schema everywhere. Zod is banned.

## Know the apps

[API server](/docs/apps/api): Effect HttpApi. Auth, workspaces, tasks, invitations. Generates its own OpenAPI spec.
[Web](/docs/apps/web): Client-only Next.js. No server code. No Effect. No Drizzle. Just typed API calls.
[Worker](/docs/apps/worker): Temporal. Deterministic workflows. Activities handle the messy parts.
[Mobile](/docs/apps/mobile): Expo React Native. Same API, same contracts.

## Know the packages

[Core](/docs/packages/core): DDD domain slices. The business logic lives here.
[DB](/docs/packages/db): Drizzle schema, repositories, migrations, pgTAP tests. Only package that touches the ORM.
[Contracts](/docs/packages/contracts): Shared API shapes. Single source of truth for validation.
[Auth](/docs/packages/auth): Password hashing and JWT. Thin and boring on purpose.
[Logging](/docs/packages/logging): Structured JSON. console.log is dead to us.
[Observability](/docs/packages/observability): OTEL bootstrap. Traces, metrics, logs.
[Testkit](/docs/packages/testkit): Harnesses, lock guards, DB reset helpers.
[Tooling](/docs/packages/tooling): ESLint configs and the scaffold CLI.

## Build something

[Add a domain](/docs/guides/adding-a-domain): The golden path. Scaffold, wire, validate, ship.
[Add routes](/docs/guides/adding-routes): crud or custom. Kind markers keep you honest.
[Add workflows](/docs/guides/adding-workflows): Temporal. No timers in workflows. Activities do the I/O.
[Add DB triggers](/docs/guides/adding-db-triggers): One command scaffolds migration + pgTAP test.
[Test it](/docs/guides/testing-strategy): Unit → integration → pgTAP → smoke. Quiet runners for agents.
[Generate the API client](/docs/guides/generating-api-client): OpenAPI in, typed hooks out.

## Understand enforcement

[How enforcement works](/docs/enforcement): Three layers. ESLint, structural scripts, shell checks.
[ESLint rules](/docs/enforcement/eslint-rules): What's banned and why
[Structural checks](/docs/enforcement/structural-checks): Cross-file invariants that ESLint can't catch
[Shell invariants](/docs/enforcement/shell-invariants): Env governance and integration baselines
[The full list](/docs/enforcement/closed-invariants): Every enforced rule in one place

## Run the infrastructure

[Docker stack](/docs/infrastructure/docker-stack): Postgres, Redis, OTEL, Jaeger, Prometheus, Grafana
[Local dev workflow](/docs/infrastructure/local-development): env:configure → infra:ensure → db:migrate → dev
[Worktrees](/docs/infrastructure/worktrees): Parallel branches with collision-free ports
[Secrets](/docs/infrastructure/secrets-management): 1Password CLI. op:// refs in committed templates.

## See everything

[Logging](/docs/observability/logging): Structured JSON over OTLP
[Tracing](/docs/observability/tracing): Distributed traces. Jaeger locally, Cloud Trace in prod.
[Metrics](/docs/observability/metrics): Counters, histograms. Prometheus locally, Cloud Monitoring in prod.
[Monitoring stack](/docs/observability/monitoring-stack): The full local + production observability picture

## Ship it

[Build images](/docs/deployment/build-images): Immutable, digest-pinned containers
[Run migrations](/docs/deployment/migrations): Drizzle migrations against staging/prod via 1Password
[Deploy](/docs/deployment/deploy-compose): op inject → docker compose up → smoke test
[Smoke tests](/docs/deployment/smoke-tests): Health, auth, workspaces, tasks, invitations. Automated.

## Reference

[API Reference](/docs/api-reference): Auto-generated from the OpenAPI spec
[Commands](/docs/commands): Every pnpm script, organized by what you're trying to do