Architecture overview
One process, multiple Go modules
Prescriptoo follows the modular-monolith decision in ADR-001 and the Go workspace structure in ADR-010. services/api/cmd/server is the composition root. It loads configuration, validates authentication configuration, verifies PostgreSQL connectivity, connects RabbitMQ, constructs modules, and registers them on one Chi router with Huma operations. Separate Go modules do not imply separate deployments.
The common layers are:
| Layer | Responsibility |
|---|---|
public/ | Curated operation interfaces, DTOs, pagination types, and stable errors |
module/ | Construction, capability facades, and HTTP registration |
internal/domain/ | Owning business entities and rules |
internal/ports/ | Repository/provider boundaries |
internal/usecase/ | One application operation per file |
internal/adapters/ | Persistence, cryptography, and delivery integrations |
internal/presentation/ | HTTP/gRPC inputs, validation, and response mapping |
Existing modules vary: some still contain legacy layouts or in-memory adapters. Their guides describe the actual state rather than treating this layout as universal.
Request path
Chi installs request IDs, real-IP handling, structured request logging, CORS, and panic recovery. Huma validates request schemas and registers OpenAPI metadata. Implemented operations invoke use cases and provider-owned capabilities; internal errors are mapped by their presentation layer. Documentation-first operations validate local inputs and return 501.
The composition root registers Identity, Admin, Organization, Doctor, Subscription, Medicine, Patient, and Prescription through Huma. Notification uses a legacy router. Only selected legacy organization operations are mounted so they cannot shadow newer portal contracts. /healthz is supplied by the API root.
Synchronous capabilities and events
ADR-012 requires curated synchronous capabilities for operations needed during the current request. Admin receives selected Identity, Organization, Subscription, and Medicine interfaces; it does not receive complete provider modules or repositories. Providers remain authoritative for their data.
Events are intended for notifications and projections after authoritative state changes. pkg/events defines the bus contract, a synchronous in-memory implementation, and RabbitMQ fan-out. The running API uses RabbitMQ; the offline OpenAPI generator uses documentation-safe construction and does not connect to infrastructure. Transactional outbox guarantees are not currently supplied by the shared bus.
Data ownership
Audit entries commit synchronously alongside provider-owned changes. Admin and Organization own the audit HTTP routes; Audit owns append-only storage and internal read/write capabilities. See Audit.
Service-prefixed tables share PostgreSQL (ADR-002). Identity, Admin, Organization, Authorization, Audit, and Medicine provide embedded migrations used by the repository CLI. New patient, prescription, doctor, and billing contracts do not imply that their planned persistence exists. See service boundaries, database operations, and ADRs.