Fastify (TypeScript) gateway for the Concordia cooperative mediation and negotiation stack (Phase 179).
Stack decision — Fastify over Python#
Phase 179 179.2.4.5 requires an explicit choice between a TypeScript Fastify
service and a Python FastAPI service for apps/concordia/orchestrator/. We
chose Fastify for this gateway.
Rationale:
- Repo convention. Every existing gateway-style service in this monorepo
(
apps/hestia/api,apps/arete/api,apps/lilith/svc-*) runs on Fastify. Adding a new Python gateway here would fragment the operational surface (logging, deployments, docker, middleware) without corresponding benefit. - Contract alignment. The Concordia OpenAPI contract is generated into
TypeScript clients under
libs/openapi/src/generated/concordia.tsvia@oshun/codegen. The orchestrator can consume the same types without a cross-language boundary. - Streaming RPC homogeneity.
libs/proto/src/concordia/concordia.protois generated forgrpc-jsvia ts-proto. Hosting the orchestrator on Node keeps the gRPC server and REST gateway in the same runtime. - Python lives in workers, not the gateway. Phase 179 explicitly splits preference learning, evaluation, agent simulation, and ML experimentation into Python (≈30%). Those run as separate workers (future) that the orchestrator calls via HTTP/gRPC. Keeping the gateway in TypeScript does not close the door on Python — it keeps the Python footprint concentrated where it's actually justified.
- Solver sidecars. CP-SAT / MILP kernels (tasks 179.4.2.4+) and NSGA-II / MAP-Elites search kernels (179.4.2.2+) will live as Rust or Python sidecar services. The orchestrator is the coordinating layer, not the numerics engine.
Repo-convention surfaces wired up#
| Surface | Path | Notes |
|---|---|---|
| Liveness | GET /health |
Always 200 while the process is running. |
| Readiness | GET /health/ready |
Runs dependency checks (OpenAPI spec availability today; DB / Redis / workers later). |
| Startup | GET /health/startup |
Readiness cached for 30s to avoid boot storms. |
| OpenAPI (raw) | GET /openapi.yaml |
Serves libs/openapi/src/specs/concordia/concordia-api.yaml directly. |
| OpenAPI (parsed) | GET /openapi.json |
Parsed JSON form of the same spec. |
| OpenAPI metadata | GET /openapi/metadata |
Title / version / description / path count for service registries. |
| Service discovery | GET /.well-known/concordia-orchestrator |
Registration payload — serviceId, advertised base URL, tags, capabilities. |
| Discovery alias | GET /service/discovery |
Same payload at a convention path for internal registries. |
| Register upstream | POST /service/discovery/register |
POSTs the registration to SERVICE_REGISTRY_URL when configured; no-op in local dev / CI. |
Nx / project integration#
project.jsondeclaresbuild,dev,start,lint,test, andtypechecktargets usingnx:run-commands— aligned withapps/hestia/apiandapps/arete/api.tsconfig.jsonusesNodeNextmodule resolution withstrict: true, matching every other gateway service.vitest.config.tsruns Node environment tests from__tests__/andsrc/.
Configuration#
Environment variables (all optional, sane defaults for local dev):
| Variable | Default | Purpose |
|---|---|---|
HOST |
0.0.0.0 |
Bind address. |
PORT |
8090 |
Listen port. |
NODE_ENV |
development |
Enables pino-pretty in development. |
LOG_LEVEL |
info |
Pino log level. |
CONCORDIA_OPENAPI_PATH |
Resolves to libs/openapi/src/specs/concordia/concordia-api.yaml |
Path to the spec that /openapi.* serves. |
CONCORDIA_SERVICE_ID |
concordia-orchestrator-primary |
Service identity advertised to discovery registries. |
CONCORDIA_ADVERTISED_BASE_URL |
http://${HOST}:${PORT} |
URL that other services should use to reach the gateway. |
CONCORDIA_DISCOVERY_TAGS |
mediation,negotiation,orchestrator |
Comma-separated tags stamped onto the discovery document. |
SERVICE_REGISTRY_URL |
(unset) | Optional registry to POST registrations to on boot. |
Docker#
Dockerfile builds a minimal Node 20 Alpine image, adds tini for signal
handling, and exposes 8090. The HEALTHCHECK hits /health so container
orchestrators can detect stalled processes without depending on external probes.
Next steps#
179.3–179.4 add case / intake / preference / search routes behind this
gateway. 179.5.5.3 adds the kill-switch and feature flags. 179.7 wires the
domain integrations. The scaffold in this directory is the substrate those tasks
plug into.