API composition root

Responsibility and startup

services/api is the single running API application. It loads config.Env, validates authentication settings, opens/pings PostgreSQL, connects RabbitMQ, constructs the shared email sender, and wires each service's selected capabilities. It owns startup/shutdown and routing, not provider business records.

The process listens on PORT, installs request-ID, real-IP, logging, CORS, and recovery middleware, and registers Huma operations for migrated services. Notification and selected organization operations remain legacy mounts. /healthz is provided here. The health workspace module does not supply this route.

Capability wiring

Identity provides account and authentication capabilities. Organization provides organization/member facades. Subscription and Medicine provide curated billing/catalog capabilities. Admin receives only the operations it needs. Patient, Doctor, Prescription, and the contract-only parts of other modules are registered for validated OpenAPI contracts without inventing functional persistence.

Startup failure releases acquired resources. Interrupt/termination starts graceful HTTP shutdown with a five-second deadline and then closes dependencies. Redis configuration exists but is not initialized by the current server. See deployment and architecture.

OpenAPI generation

cmd/generate-openapi registers documentation-safe Huma operations without live infrastructure and writes api/openapi.yaml. go run ./tools/cli generate openapi explicitly refreshes that tracked artifact. The docs image serves this file to Scalar and Swagger; site builds do not silently modify it. Legacy Chi handlers are not automatically added to the Huma specification.

Composition tests verify startup validation, route registration/precedence, delegation, and generated/runtime contract consistency. See server package and OpenAPI generator.