ADR-016: Medicine Catalog API Contracts
Status
Accepted. The initial contract-only stage below is now implemented; see the Medicine workflow for the current behavior. The implementation uses organization-style response envelopes and PostgreSQL, with authentication, audit, and events deferred.
Context
Prescriptoo needs a shared medicine catalog that signed-in users can search and platform administrators can maintain. Neighboring services define validated Huma contracts before implementing persistence and business behavior.
Decision
Medicine is a separate Go module at services/medicine, composed into the existing API server. It owns manufacturers, named generics (including combinations), brands linked to a manufacturer/generic, and drug variants linked to a brand with textual form and strength. Drug read DTOs include related display summaries. No clinical reference content, prices, structured ingredient catalog, or form catalog is added.
Reader routes use /api/v1/medicines. Admin workflows use /api/v1/admin/medicines and delegate through individually selected medicine/public capabilities. All future readers require active authentication; only platform admin and super_admin can write. No organization scoping or organization-admin write permission applies. Medicine owns authoritative mutations and events after commit.
PATCH retains omitted fields, supports description clearing with null, rejects empty patches, and protects server-owned identifiers/timestamps. Soft deletion and explicit restoration preserve IDs and prior status. Non-deleted dependents block parent removal, including inactive records; no cascades occur. Restoration requires non-deleted parents and validates conflicts. Ordinary reads expose active, non-deleted entries; Admin reads support inactive and deleted entries.
All 32 HTTP operations validate input and return 501 for valid requests, regardless of absent or placeholder credentials. Security annotations document future rules; authentication, persistence, state checks, search and events are not implemented. Both composition roots register matching operations and capability wiring.
Prescription contracts and service wiring remain unchanged. Use-case TODO comments brief future catalog validation and preservation of medication display data.
Consequences
The catalog has clear ownership and testable frontend contracts without duplicating storage in Admin. Clients must handle 501 until operational use cases are added. There are no migrations, seed data, or deployment changes in this release.