Container Build Strategy for API, Worker, and Side Services

Overview

This section documents how Dwilar/lita-api turns the monorepo API and worker into production container images, and how the standalone side services are packaged beside them. The main API image is built from the workspace root with pnpm, shared packages, and a TypeScript build step; the worker uses the same workspace build pattern but runs as a background poller instead of an HTTP server.

The deployment split is visible directly in the Dockerfiles: apps/api and apps/worker are monorepo-aware Node 20 images, while services/consent-service and services/scoring-orchestrator are self-contained Node 18 images, and services/token-service plus services/us-data-gateway are multi-stage Go binaries. docker-compose.api.yml is the composition layer that assembles these images into a single runtime stack.

Architecture Overview

flowchart TB
    subgraph WorkspaceBuild [Monorepo Workspace Build]
        RootManifests[Root package json pnpm workspace yaml turbo json tsconfig base json]
        SharedPackages[packages directory]
        ApiDockerfile[apps api Dockerfile]
        WorkerDockerfile[apps worker Dockerfile]
        ApiBuild[apps api build]
        WorkerBuild[apps worker build]
        ApiRuntime[apps api runtime image]
        WorkerRuntime[apps worker runtime image]
        RootManifests --> ApiDockerfile
        RootManifests --> WorkerDockerfile
        SharedPackages --> ApiDockerfile
        SharedPackages --> WorkerDockerfile
        ApiDockerfile --> ApiBuild
        WorkerDockerfile --> WorkerBuild
        ApiBuild --> ApiRuntime
        WorkerBuild --> WorkerRuntime
    end

    subgraph StandaloneServices [Standalone Side Services]
        ConsentDockerfile[services consent service Dockerfile]
        ScoreDockerfile[services scoring orchestrator Dockerfile]
        TokenDockerfile[services token service Dockerfile]
        GatewayDockerfile[services us data gateway Dockerfile]
        ConsentRuntime[consent service image]
        ScoreRuntime[scoring orchestrator image]
        TokenRuntime[token service image]
        GatewayRuntime[us data gateway image]
        ConsentDockerfile --> ConsentRuntime
        ScoreDockerfile --> ScoreRuntime
        TokenDockerfile --> TokenRuntime
        GatewayDockerfile --> GatewayRuntime
    end

    ComposeFile[docker compose api yml]
    ComposeFile --> ApiRuntime
    ComposeFile --> WorkerRuntime
    ComposeFile --> ConsentRuntime
    ComposeFile --> ScoreRuntime
    ComposeFile --> TokenRuntime
    ComposeFile --> GatewayRuntime

Container Image Matrix

Image Build family Base image Build tool Runtime artifact Port
apps/api Monorepo Node node:20-alpine pnpm + tsc dist/index.js 3000
apps/worker Monorepo Node node:20-alpine pnpm + tsc dist/index.js none
services/consent-service Standalone Node node:18-alpine npm ci src/index.js 8081
services/scoring-orchestrator Standalone Node node:18-alpine npm ci src/index.js 8082
services/token-service Standalone Go golang:1.20-alpine then alpine:3.19 go build /bin/token-service 8083
services/us-data-gateway Standalone Go golang:1.20-alpine then alpine:3.19 go build /bin/us-data-gateway 8084

Workspace-Built Node Images

API Image Build

apps/api/Dockerfile, apps/api/package.json, apps/api/tsconfig.json, apps/api/src/index.ts, apps/api/src/server.ts

The API image is built as a two-stage image. The build stage copies the workspace manifests, the app manifest, the app TypeScript config, and the shared packages tree before running pnpm install --frozen-lockfile; this is what makes the image workspace-aware instead of app-only. After the source tree is copied in, pnpm -C apps/api build compiles the server into dist.

The runtime stage copies only dist and package.json, sets NODE_ENV=production, exposes 3000, and starts node dist/index.js.

Build inputs

File Role in the image
package.json Root workspace manifest copied before dependency install
pnpm-workspace.yaml Defines the workspace layout for pnpm install
turbo.json Workspace build configuration copied into the build context
tsconfig.base.json Shared TypeScript base config copied into the build context
apps/api/package.json Declares @lita/api, its build script, and runtime dependencies
apps/api/tsconfig.json Compiles src into dist
packages/ Shared workspace packages used by the API build

Runtime contract

Setting Value
Runtime base node:20-alpine
Output copied into image /app/apps/api/dist
Runtime entrypoint node dist/index.js
Container port 3000
Runtime mode NODE_ENV=production

API bootstrap flow

apps/api/src/index.ts starts the compiled server by calling buildServer(), resolving PORT from the environment with a default of 3000, fixing the host to 0.0.0.0, and then calling server.listen({ port, host }). The process logs the chosen port after the listener is up.

apps/api/src/server.ts builds the Fastify instance, initializes OpenTelemetry with initOtel(), installs the logger from buildLogger(), and then wires cors, helmet, rateLimit, authPlugin, tenantPlugin, idempotencyPlugin, and auditPlugin before registering the versioned routes.

Function Responsibility
buildServer Creates the Fastify app, initializes telemetry, registers plugins, and mounts routes and probes
server.listen Binds the API container to the configured host and port

Worker Image Build

apps/worker/Dockerfile, apps/worker/package.json, apps/worker/tsconfig.json, apps/worker/src/index.ts

The worker uses the same workspace build pattern as the API. The build stage copies the root workspace manifests, the worker package manifest, the worker TypeScript config, and the shared packages tree, then runs pnpm install --frozen-lockfile. After the worker source is copied in, pnpm -C apps/worker build emits dist.

The runtime image again copies only dist and package.json, sets NODE_ENV=production, and runs node dist/index.js. Unlike the API, the worker exposes no port because it is a background process.

Build inputs

File Role in the image
package.json Root workspace manifest copied before dependency install
pnpm-workspace.yaml Defines the workspace layout for pnpm install
turbo.json Workspace build configuration copied into the build context
tsconfig.base.json Shared TypeScript base config copied into the build context
apps/worker/package.json Declares @lita/worker, its build script, and runtime dependencies
apps/worker/tsconfig.json Compiles src into dist
packages/ Shared workspace packages used by the worker build

Runtime contract

Setting Value
Runtime base node:20-alpine
Output copied into image /app/apps/worker/dist
Runtime entrypoint node dist/index.js
Container port none
Runtime mode NODE_ENV=production

Worker execution flow

apps/worker/src/index.ts runs a perpetual polling loop. pollDeliveries() queries prisma.webhookDelivery.findMany() for deliveries whose status is pending or retrying and whose nextRetryAt is null or due, then processes up to 10 records at a time. processDelivery() loads the delivery and its endpoint, signs the payload with signWebhook(), POSTs the payload to the endpoint, and updates delivery state in Prisma based on success or failure.

Function Responsibility
processDelivery Signs and sends a webhook delivery, then updates delivery state and audit trail
pollDeliveries Fetches due deliveries from Prisma and dispatches them one by one
run Repeats polling every 5000 ms and logs poll failures
sequenceDiagram
    participant Worker as run
    participant Poll as pollDeliveries
    participant DB as prisma
    participant Process as processDelivery
    participant Sign as signWebhook
    participant Endpoint as Delivery endpoint
    participant Audit as recordAuditEvent

    Worker->>Poll: poll every 5000 ms
    Poll->>DB: findMany due deliveries
    DB-->>Poll: delivery list
    loop each delivery
        Poll->>Process: deliveryId
        Process->>DB: findUnique delivery with endpoint
        Process->>Sign: sign payload
        Process->>Endpoint: POST payload with headers
        alt success
            Process->>DB: update delivered
        else failure
            Process->>DB: update retrying or failed
            Process->>Audit: webhook.delivery.failed
        end
    end

Standalone Side Service Images

services/consent-service/Dockerfile

services/consent-service/Dockerfile is a single-stage Node image. It installs dependencies with npm ci --omit=dev, copies src, sets NODE_ENV=production, exposes 8081, and starts node src/index.js.

Setting Value
Runtime base node:18-alpine
Dependency install npm ci --omit=dev
Runtime entrypoint node src/index.js
Container port 8081
Build style Single-stage runtime image

Scoring Orchestrator Image Build

services/scoring-orchestrator/Dockerfile

services/scoring-orchestrator/Dockerfile uses the same single-stage Node pattern as the consent service. It installs production dependencies with npm ci --omit=dev, copies src, exposes 8082, and launches node src/index.js.

Setting Value
Runtime base node:18-alpine
Dependency install npm ci --omit=dev
Runtime entrypoint node src/index.js
Container port 8082
Build style Single-stage runtime image

Token Service Image Build

services/token-service/Dockerfile

services/token-service/Dockerfile is a multi-stage Go build. The build stage downloads modules after setting GOPROXY=direct, copies the full source tree, and builds /bin/token-service from ./cmd/token-service. The runtime stage is a slim alpine:3.19 image that creates a non-root app user, sets PORT=8083, exposes 8083, copies in the binary, and uses it as the entrypoint.

Setting Value
Build base golang:1.20-alpine
Runtime base alpine:3.19
Runtime user app
Runtime entrypoint /bin/token-service
Container port 8083
Build style Multi-stage binary image

US Data Gateway Image Build

services/us-data-gateway/Dockerfile

services/us-data-gateway/Dockerfile follows the same Go packaging model as the token service. It builds /bin/us-data-gateway from ./cmd/us-data-gateway, runs it inside alpine:3.19, creates the non-root app user, sets PORT=8084, exposes 8084, and uses the binary as the entrypoint.

Setting Value
Build base golang:1.20-alpine
Runtime base alpine:3.19
Runtime user app
Runtime entrypoint /bin/us-data-gateway
Container port 8084
Build style Multi-stage binary image

Runtime Coupling and Operational Movement

Operational set Containers Why they are coupled
Core monorepo pair apps/api, apps/worker Shared workspace build, shared packages, shared database-backed delivery flow
Node side services services/consent-service, services/scoring-orchestrator Separate Node images with their own package-lock and src/index.js entrypoints
Go side services services/token-service, services/us-data-gateway Separate binary images with fixed ports and non-root runtime users

Observability, Audit, and Delivery Infrastructure

Observability Bootstrap

[!IMPORTANT] apps/api and apps/worker are the only images that are built from the same workspace root and share the same monorepo package set. They form the release pair in this repository because the worker consumes the webhook delivery records that the API side creates and because both images depend on the same shared workspace packages.

apps/api/src/server.ts

The API container initializes telemetry before any Fastify registration happens. buildServer() calls initOtel() first, then creates Fastify with the logger returned by buildLogger(). That means telemetry and logging are part of the server bootstrap path, not a later plugin.

Function Responsibility
initOtel Initializes OpenTelemetry before the HTTP server is constructed
buildLogger Supplies the logger instance used by Fastify
buildServer Connects telemetry, logging, plugins, and routes in one startup path

Webhook Delivery Worker

apps/worker/src/index.ts, apps/api/src/routes/v1/webhooks.ts

The worker is the delivery engine for webhook records. The API side creates and queues webhook deliveries through @lita/webhooks, while the worker reads due rows from prisma.webhookDelivery, signs the body with signWebhook(), and sends the delivery to the endpoint URL. On failure it increments the attempt counter, schedules a retry, and writes an audit event through recordAuditEvent().

Component Responsibility
enqueueWebhookDelivery API-side queueing of webhook deliveries
processDelivery Worker-side transport and state transitions
signWebhook Produces the X-Lita-Signature value used for delivery verification
recordAuditEvent Records delivery failure events in the audit trail
sequenceDiagram
    participant API as API side
    participant Queue as enqueueWebhookDelivery
    participant DB as prisma
    participant Worker as pollDeliveries
    participant Process as processDelivery
    participant Endpoint as Delivery endpoint
    participant Audit as recordAuditEvent

    API->>Queue: create webhook delivery
    Queue->>DB: persist delivery row
    Worker->>DB: findMany due deliveries
    DB-->>Worker: delivery rows
    Worker->>Process: deliveryId
    Process->>DB: load delivery and endpoint
    Process->>Endpoint: POST signed payload
    alt delivery accepted
        Process->>DB: mark delivered
    else delivery rejected
        Process->>DB: mark retrying or failed
        Process->>Audit: webhook.delivery.failed
    end

Runtime Probe Endpoints

apps/api/src/server.ts registers three public probe/documentation endpoints after the plugin stack is installed. The auth plugin treats /healthz, /readyz, and /openapi.json as public paths, so they bypass auth while still flowing through the global Fastify stack.

Health Check

apps/api/src/server.ts

Health Check

{
    "title": "Health Check",
    "description": "Returns the public liveness probe response. The route is exempt from auth through the auth plugin publicPaths set.",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/healthz",
    "headers": [],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"status\": \"ok\"\n}"
        }
    }
}

Readiness Check

apps/api/src/server.ts

Readiness Check

{
    "title": "Readiness Check",
    "description": "Returns the public readiness probe response. The route is exempt from auth through the auth plugin publicPaths set.",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/readyz",
    "headers": [],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"status\": \"ready\"\n}"
        }
    }
}

OpenAPI Document

apps/api/src/server.ts

OpenAPI Document

{
    "title": "OpenAPI Document",
    "description": "Returns the OpenAPI document payload emitted by the API process. The route is exempt from auth through the auth plugin publicPaths set.",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/openapi.json",
    "headers": [],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"openapi\": \"3.0.3\",\n    \"info\": {\n        \"title\": \"Lita Platform API\",\n        \"version\": \"1.2.0\"\n    },\n    \"paths\": []\n}"
        }
    }
}

Compose Assembly

[!NOTE] GET /openapi.json returns a static object with paths: {} even though buildServer() registers route plugins and probe endpoints. The emitted document does not enumerate the live HTTP surface.

docker-compose.api.yml

docker-compose.api.yml is the orchestration layer for the image set documented here. It is the file that brings the workspace-built API and worker together with the standalone consent, scoring, token, and US gateway services.

Key Classes Reference

Class Responsibility
apps/api/Dockerfile Builds the monorepo API image from the workspace and emits the production runtime container
apps/worker/Dockerfile Builds the monorepo worker image and packages the webhook delivery loop
services/consent-service/Dockerfile Packages the standalone consent service as a production Node container
services/scoring-orchestrator/Dockerfile Packages the standalone scoring orchestrator as a production Node container
services/token-service/Dockerfile Builds the token service into a non-root Go binary image
services/us-data-gateway/Dockerfile Builds the US data gateway into a non-root Go binary image
apps/api/src/server.ts Creates the Fastify server, telemetry, plugins, routes, and public probe endpoints
apps/api/src/index.ts Resolves the runtime port and starts the API listener
apps/worker/src/index.ts Runs the webhook delivery polling loop and delivery processor
docker-compose.api.yml Composes the service images into a single deployment stack