Getting Started

This section walks you through setting up tx-agent-kit for local development, from prerequisites to running your first domain scaffold.

Opinionated stack

tx-agent-kit is deliberately opinionated. It picks one tool per concern and enforces that choice mechanically through linters, structural checks, and shell invariants. This means the prerequisites are non-negotiable: you need the exact toolchain below, not alternatives.

Concern	Choice	Why
Runtime	Node.js 22+	Native ESM, `--watch`, stable `fetch`
Package manager	pnpm 10+	Workspace protocol, strict hoisting, lockfile
Containers	Docker Desktop	Postgres, Redis, OTEL Collector, Prometheus, Jaeger, Grafana run as local infra
Workflows	Temporal CLI	Local dev server for durable workflows (`temporal server start-dev`)
Backend framework	Effect	Typed errors, dependency injection, HttpApi
ORM	Drizzle	SQL-first migrations, typed schema, Studio UI
Validation	effect/Schema	Shared contracts across API, web, and mobile (zod is banned)
Frontend	Next.js 16	Client-only SPA, no SSR, no API routes
Mobile	Expo	React Native with shared contracts
Secrets (deploy)	1Password CLI	`op://` references in deploy templates; not required for local dev

Prerequisites

Required for local development

Tool	Version	Install	Purpose
Node.js	22+	nodejs.org	JavaScript runtime
pnpm	10+	`corepack enable && corepack prepare pnpm@latest --activate`	Monorepo package manager
Docker Desktop	24+	docker.com	Local infra (Postgres, Redis, monitoring stack)
Temporal CLI	Latest	`brew install temporal` or docs.temporal.io/cli	Local workflow dev server

Optional (for staging/production deploys)

Tool	Version	Install	Purpose
1Password CLI (`op`)	2.x	1password.com/downloads/command-line	Resolve `op://` secrets for deploy templates
Vercel CLI	Latest	`npm i -g vercel`	Deploy docs site and previews

Verify your setup

node --version      # v22.x.x or higher
pnpm --version      # 10.x.x or higher
docker --version    # Docker Engine 24+ recommended
temporal version    # Temporal CLI (any recent version)

Quick overview

tx-agent-kit is a pnpm monorepo with four applications and several shared packages:

tx-agent-kit/
  apps/
    api/        # Effect HttpApi server (port 4000)
    web/        # Next.js client-only SPA (port 3000)
    worker/     # Temporal worker + workflows
    mobile/     # Expo React Native app
    docs/       # Fumadocs documentation site (port 3002)
  packages/
    core/       # DDD domain slices
    db/         # Drizzle schema, migrations, repositories
    contracts/  # Shared API schemas (effect/Schema)
    auth/       # Password + JWT primitives
    logging/    # Structured JSON logger
    observability/ # OpenTelemetry bootstrap
    testkit/    # Test utilities
    tooling/    # ESLint configs, scaffold CLI

Local infrastructure runs in Docker via docker-compose.yml, while Temporal runs as a standalone CLI process:

Service	Port	Role
PostgreSQL	5432	Primary database
Temporal CLI	7233 (gRPC), 8233 (UI)	Workflow orchestration
Redis	6379	Caching and session store
OTEL Collector	4317 (gRPC), 4318 (HTTP)	Traces and metrics pipeline
Prometheus	9090	Metrics storage and queries
Jaeger	16686	Distributed tracing UI
Grafana	3001	Dashboards and log exploration

Next steps

Local Setup to clone, install, configure, and run the full stack.
First Domain to create a new domain using the scaffold CLI.