Admin

Responsibility and dependencies

Admin owns platform administrator memberships and the future doctor-verification workflow. Authorization owns configurable roles, permission grants, and assignments. Admin orchestrates privileged changes through Identity, Organization, Subscription, and Medicine capabilities. Organizations, accounts, catalog records, and billing records remain owned by their provider services. An organization-admin membership is distinct from a platform-admin membership.

Current implementation

Every HTTP operation maps its request DTO through toDomain and its application result through toPresentation. Admin operation inputs live in services/admin/internal/domain; shared account, organization, medicine, billing, verification, and administrator models live in pkg/types without HTTP tags or service dependencies. Use cases translate curated provider contracts at their boundaries, while HTTP DTOs retain validation, JSON field names, and response envelopes.

POST /api/v1/admin/auth/login accepts the same email and password body as ordinary Identity login and returns the same access_token, refresh_token, token_type, and expires_in fields. Its use case requires an active Identity account and an active platform-admin membership before issuing credentials or creating a session. Incorrect credentials, non-admin accounts, and inactive memberships/accounts return 401. Login shares Identity's limit of ten attempts per normalized email per 15-minute window and returns 429 when exceeded. Responses use Cache-Control: no-store; missing provider dependencies return 503. Identity exposes this authentication capability through Module.Authentication(), injected separately from account provisioning and bearer verification.

GET /api/v1/admin/profile returns a success envelope with message, status_code, and data. Identity fields (ID, name, email, account status, email verification, and timestamps) appear directly in data, alongside profile (admin membership ID, user ID, status, and timestamps), roles (assigned platform role metadata without nested permissions), and permissions (effective own/any decisions after direct allows and denials). Identity and membership must both be active, and the bearer session must be valid. Reading your own profile requires no management permission. Lookups always use the verified caller; there is no target-user parameter. Unassigned roles return an empty array. Success responses use Cache-Control: no-store; invalid credentials return 401, absent/inactive admin membership returns 403, and unavailable dependencies return 503. The authorization reader is supplied through ConfigureAuthorization.

User administration and organization/member provisioning are implemented. Most protected operations resolve bearer tokens through Identity and look up a platform-admin principal in the admin repository. Creating another administrator requires super_admin; assignable platform roles are validated by the use case. Missing token/provider capabilities fail closed. With a database, module construction uses pgx persistence; documentation-only construction can omit database dependencies.

CreateOrganizationUseCase receives types.IIdentityService and types.IAuthorizationService through the Admin module's Dependencies. It verifies the complete Authorization header, requests admin.organization.create for the verified user, and delegates creation only after a successful permission result. It has no principal resolver or account-reader dependency. Audit attribution uses the verified user ID, omits membership ID, and falls back to the user ID for the actor name. The shared Authorization service currently returns true, nil, so this creation path temporarily allows any verified active identity; its authorization-owned eligibility and grant functions remain TODOs. Other Admin operations retain their existing checks.

Medicine administration and manual billing are documentation-first interfaces: valid requests delegate into provider use cases returning 501. Declared bearer permissions and future state rules for those operations are not yet enforced. Doctor administration implements the doctor directory/detail, verification submission/review, global account suspension/activation and organization assignment with enforced admin permissions and transactional audit recording.

Management API contracts includes grant revocation and generic Identity account directory/status operations that still return 501. Doctor credential submission/review is implemented; submission authenticates a doctor, while review requires the corresponding platform-admin permission.

Workflows

Platform admins create and discover organizations, update details, change lifecycle status, and provision ordinary members using provider-owned capabilities. Admin combines Identity account operations with Organization membership operations without copying either service's domain models into its contracts. These multi-provider calls should not be assumed to form one cross-service database transaction.

Organization workflows use one public AdminOrganizationService, including member creation and lookup. Account provisioning and individual/batch lookups use one public AdminIdentityService. Both providers expose Module.Administration(); the API injects them through the matching fields in Admin's Dependencies. Admin's internal ports alias the public contracts. Activation and restoration share one organization dependency for reads and status changes, and member provisioning shares one identity dependency for account creation and lookup. Credential verification continues through the separate identity/authentication contracts.

For intended catalog management, read Medicine workflows. For plans, subscription snapshots, invoices, and manual payments, read Subscription workflows. Their named HTTP examples are contract payloads and do not prove persistence or authorization.

Storage, events, and testing

Admin provides embedded migrations for platform-admin users (admin_users). Its membership role identifies ordinary admins and scope owners; configurable roles and permissions live in Authorization's authz_* tables. Apply migrations through pcli, after Identity. Existing event publication includes administrator creation; provider-owned organization changes publish from Organization. Unit and HTTP tests verify principal resolution, delegation, role checks, and error mapping. Composition-root tests verify wiring and the current medicine/billing 501 behavior.

Code reference

See module dependencies, use cases, and HTTP presentation.

Audit history

This service owns its scoped list/detail audit HTTP endpoints and consumes internal Audit capabilities. Persistent working mutations append history in their authoritative PostgreSQL transactions. Admin-originated changes remain in admin history, including delegated organization writes. Audit has no direct HTTP API.

Organization type, summary, real usage counts, affiliation lists and target-aware picker extensions are documented in Organization management API. Billing projections are explicitly mocked through a Subscription-owned provider.

Clinical input catalogs

See the clinical suggestion workflow for authenticated Doctor queries, Admin CRUD permissions, DTOs, and seed setup.