API Server (apps/api)

The API server is the backbone of tx-agent-kit. It is built on Effect HttpApi and exposes a fully typed, schema-validated REST API. The server runs on port 4000 by default.

Architecture

The API server follows a layered architecture where routes delegate to domain services, which in turn interact with repositories through Effect's dependency injection system.

Request -> Route Handler -> Domain Service -> Repository Port -> DB Repository

Each route handler extracts the authenticated principal from the Authorization header, invokes the appropriate domain service, and maps the result to an API response shape.

Route Groups

OpenAPI tags map directly to generated API reference pages. The full route surface lives in apps/api/src/routes/:

For full request/response shapes, use the generated pages in docs/api-reference/* or runtime /openapi.json.

Billing and Roles

Billing authorization is role-gated:

• owner and admin can manage billing (PATCH /v1/organizations/{organizationId}/billing, POST /v1/billing/checkout, POST /v1/billing/portal).
• member cannot manage billing and receives 401 on management endpoints.
• Subscription state is synced from Stripe webhooks (/v1/webhooks/stripe) into organization billing fields (isSubscribed, subscriptionStatus, subscriptionPlan).

Rate Limiting

Sensitive auth paths are protected by an in-memory rate limiter that enforces two independent limits per sliding window: one keyed by client IP address and one keyed by the authentication identifier (email address). Both must pass for a request to proceed.

The set of rate-limited paths is defined centrally in @tx-agent-kit/contracts (authRateLimitedPaths).

Proxy trust

When the API runs behind a load balancer or reverse proxy, client IPs arrive in the X-Forwarded-For header rather than the socket address. Set TRUST_PROXY=true (or 1) to extract the leftmost IP from that header. The default is false, which uses the direct socket address.

429 response shape

When a client exceeds either limit the API returns HTTP 429 with a Retry-After header (seconds) and the following body:

{
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "Too many authentication attempts. Please try again later."
  }
}

Domain Events

The API writes domain events transactionally using *WithEvent port methods. Each mutation that produces a domain event inserts the event row inside the same database transaction as the business write, guaranteeing at-least-once delivery semantics via the outbox pattern.

The API never imports @temporalio/* directly. Events reach the worker exclusively through the outbox table, which the worker polls and processes. This keeps the API deployment free of Temporal SDK dependencies and ensures that event publication cannot fail independently of the business write.

Kind Markers

Every route file declares an explicit kind marker that must match the corresponding repository port kind:

// apps/api/src/routes/organizations.ts
export const OrganizationsRouteKind = 'crud' as const

// apps/api/src/routes/auth.ts
export const AuthRouteKind = 'custom' as const

The enforcement layer validates that crud routes expose the full list/get/create/update/remove surface, and that custom routes do not accidentally implement the full CRUD pattern.

OpenAPI Generation

The API spec is generated from the Effect HttpApi definitions:

pnpm openapi:generate

This produces apps/api/openapi.json, which is then consumed by Orval to generate typed client hooks for the web and mobile apps.

When the API server is running (default http://localhost:4000), runtime docs are available at:

• /docs for Swagger UI
• /openapi.json for the raw OpenAPI document

Both runtime endpoints come from the same Effect HttpApi definitions. The generated apps/api/openapi.json remains the repo artifact used by downstream generation workflows (including pnpm docs:api:generate).

Security Headers

Every API response carries a fixed set of security headers applied by securityHeadersMiddleware in apps/api/src/middleware/security-headers.ts:

No configuration is required; headers are always applied on all responses including error paths.

Config and Environment

Runtime environment variables are read exclusively through apps/api/src/config/env.ts. Direct process.env access is forbidden in route and service modules. The module caches parsed config on first call; resetApiEnvCache() is exported for use in tests.

Required variables

Optional variables and group invariants

Group invariants enforced at startup:

• RESEND_API_KEY, RESEND_FROM_EMAIL, and WEB_BASE_URL must all be set together. In production, all three are required.
• All four GOOGLE_OIDC_* variables must be configured together. In production they are required.
• Stripe plan checkout requires the selected plan's recurring Stripe Price ID.
• STRIPE_WEBHOOK_SECRET is required in production/staging when Stripe is configured.

Integration Testing

The API integration suite lives at apps/api/src/api.integration.test.ts and uses the standardized harness:

import { createDbAuthContext } from '@tx-agent-kit/testkit'

const ctx = createDbAuthContext({
  apiCwd: resolve(dirname(fileURLToPath(import.meta.url)), '..')
})

The harness provides authenticated HTTP helpers and handles DB reset between test cases. Manual process spawning and direct createSqlTestContext wiring are forbidden in the API integration suite.