ADR-008: Service Boundaries and Responsibilities
Status
Accepted
Context
We need clear boundaries for each service to avoid duplication and ensure single responsibility.
Decision
We define the following service boundaries:
Service Responsibilities
Identity Service
Owns: User authentication and profiles
| Entity | Description |
|---|---|
| User | Base identity (email, password, name, status) |
| StaffProfile | Staff-specific info (designation, department) |
Responsibilities:
- User registration and authentication
- Token management (JWT)
- Profile management (CRUD)
- Identity account and staff profile management; professional doctor profiles belong to Doctor
Does NOT own:
- Doctor verification (Admin service)
- Doctor-organization relationships (Organization service)
Doctor Service
Owns: Professional doctor profiles (license and specialization).
Responsibilities:
- Independent and invited doctor registration using identity-owned account capabilities
- Doctor self-profile reads and organization discovery
- Join-request orchestration through organization-owned capabilities
Does NOT own: Credentials, organization memberships/affiliations, or prescriptions. Doctors may affiliate with multiple organizations (ADR-013).
Organization Service
Owns: Organizations, teams, ordinary memberships, separate doctor affiliations, doctor registration invitations, and doctor join requests
| Entity | Description |
|---|---|
| Organization | Medical organization/clinic |
| Team | Grouping within organization |
| Member | Ordinary user-organization relationship with role |
| DoctorAffiliation | Separate doctor-organization relationship |
| DoctorInvitation | New-doctor registration invitation |
| DoctorJoinRequest | Doctor-originated request requiring organization-admin approval |
Responsibilities:
- Organization CRUD
- Team management
- Member invitation and role management
- Active context management (which org is user working in)
Does NOT own:
- User profiles (Identity service)
- Subscription details (Subscription service)
Subscription Service
Owns: Shared plans, organization subscriptions, invoices, and manual payment records
| Entity | Description |
|---|---|
| Plan | Subscription plan template |
| Subscription | Organization-plan relationship |
| Feature snapshot/overrides | Assigned terms and per-subscription effective features |
| Invoice | Single-charge draft/issued invoice with payment balance |
| Payment | Manually recorded receipt, retained when voided |
Responsibilities:
- Shared-plan catalog and platform-admin management through curated capabilities
- One current subscription per organization, assigned snapshots, and feature overrides
- Explicit access status/expiry management, extension, and history-preserving deletion
- Invoice lifecycle and manual partial payments with void-and-replace corrections
- Future effective-limit checks against organization-owned active usage
Billing records do not activate or extend subscriptions. BDT amounts use integer minor units. See ADR-014 for the accepted rules and current 501-only implementation.
Does NOT own:
- Payment gateway processing (deferred; current contracts cover manual recording)
- Organization details (Organization service)
Patient Service
Owns: Organization-scoped patient demographic profiles, contact details and addresses.
Responsibilities: Minimal registration, profile updates, patient search and curated authorized patient lookups. Patient is a separate Go module, composed into the API server, with no dependency on Prescription. It owns no prescription or encounter model. Current HTTP contracts validate input and return 501.
Prescription Service
Owns: Prescriptions (doctor-owned, org-contextual)
| Entity | Description |
|---|---|
| Prescription | Medical prescription |
| ClinicalContent | Ordered clinical sections including structured medication orders |
| Issuance snapshots | Immutable patient/doctor display data captured when issued |
Key Concept: Prescriptions are owned by doctors, not organizations. organization_id is the context (which org was it created for).
Responsibilities:
- Draft creation, retrieval, listing and partial updates; cancellation retains history
- Issue/cancel workflow
- Detailed ordered clinical content and prescription-derived patient history
- Author-private drafts, organization-shared issued/canceled history and immutable issuance snapshots
Does NOT own:
- Patient registration, demographics and search (Patient service)
- Doctor profiles (Doctor service)
- Organization details (Organization service)
Medicine Service
Medicine owns the global manufacturer, generic, brand and drug catalog. It supplies signed-in read APIs and curated administration capabilities consumed by Admin. Brands link to a manufacturer and named generic; drugs add textual form/strength. Admin orchestrates catalog management without owning catalog storage. Current contracts return 501; authentication and persistence are deferred (ADR-016).
Admin Service
Owns: System administration
| Entity | Description |
|---|---|
| Admin | System administrator |
| DoctorVerification | Doctor credential verification |
Responsibilities:
- Organization administration via organization-owned public capabilities
- Platform-admin billing workflows via subscription-owned public capabilities
- Doctor verification workflow
- System analytics
Does NOT own:
- User authentication (Identity service)
- Subscription billing (Subscription service)
Notification Service
Owns: Email/SMS delivery
| Entity | Description |
|---|---|
| Notification | Notification to be sent |
| Template | Reusable notification template |
Responsibilities:
- Send notifications (email/SMS)
- Template management
- Delivery tracking
Does NOT own:
- Business logic that triggers notifications (other services publish events)
Service Communication
Identity ──events──> Organization
Identity ──events──> Notification
Organization ──events──> Notification
Subscription ──events──> Notification
Admin ──events──> Notification
Doctor ──public capabilities──> Identity / Organization
Admin ──public capabilities──> Identity / Organization / Subscription
Organization ──public contracts──> Doctor / Subscription
Prescription ──public contracts / future capabilities──> PatientSynchronous commands/queries use curated public interfaces (ADR-012); events follow authoritative commits for notifications and projections. Organization, doctor, patient, prescription, and subscription contract APIs currently document these rules and return 501; they do not enforce permissions or persist changes. Doctor verification remains a future admin workflow; profile storage belongs to Doctor.
Consequences
Positive
- Clear ownership
- No duplication
- Easy to reason about
Negative
- Need to enforce boundaries
- Cross-service queries require events or API calls
Related Decisions
ADR-001: Modular Monolith Architecture
ADR-003: Event-Driven Architecture
ADR-004: Doctor as Role
ADR-005: Doctor Verification in Admin Service
ADR-006: Notification Service