Platform Admin Service — Service Overview
Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD
1. Purpose
platform-admin-service is the control-plane backend for platform operators. It owns: platform-wide and tenant-scoped configuration governance, feature-flag lifecycle and evaluation, aggregated health visibility across registered services, and cross-tenant operational oversight. It is the backend for the Super Admin console.
2. Bounded context
Platform Operations & Control Plane — classified as Generic / Supporting. In-house because:
- Configuration governance must be strongly consistent and auditable.
- Feature flags gate capability rollout; decisions must be deterministic and low-latency (p95 ≤ 120 ms internal).
- Health aggregation requires dynamic registration of service sources in an elastic environment.
- Cross-tenant oversight is sensitive; no third-party SaaS is appropriate for this data.
3. Responsibilities
| Area | What platform-admin-service owns |
|---|---|
| Platform configuration | Global and tenant-scoped KV pairs; allow-listed keys; type-schema validated; auditable history |
| Feature flags | Flag lifecycle (create, update, archive); platform-default + tenant-override evaluation; cache-backed internal evaluation |
| Platform health | Aggregate health endpoint (GET /admin/health/aggregate); dynamic service source registration; heartbeat-based lifecycle |
| Cross-tenant oversight | Multi-tenant dashboard data (aggregate metrics, tenant status summary) |
| Audit of control-plane ops | Config mutation history; flag change log |
| License governance (future) | License enforcement oversight at platform level (S2) |
| Data residency enforcement (future) | Platform-level data residency policy controls (S3) |
4. Non-responsibilities
| Area | Owner |
|---|---|
| Tenant lifecycle (create/activate/suspend) | tenant-service |
| User identity and credentials | identity-service |
| Module licensing assignments | identity-service |
| Organization hierarchy | tenant-service |
| Billing transactions | billing-service |
| Application-level feature flag evaluation (per-user rollout) | Client SDKs / future feature-flag service |
5. Upstream & downstream dependencies
| Dependency | Pattern | Purpose |
|---|---|---|
| All 26 platform services | Pull (internal HTTP healthcheck) | Register health sources; poll health endpoints |
| tenant-service | Event consumer (tenant.tenant.activated.v1) | Trigger default config provisioning for new tenant |
| config-service | — | platform-admin-service IS the authoritative config store; config-service may read from it |
| NATS JetStream | Outbox producer | Publish platform.config.updated.v1, platform.flag.updated.v1 |
| audit-service | Event consumer | All config/flag mutations land in audit trail |
| Kong | Downstream | Kong reads feature flags via /internal/admin/flags/:key/evaluate |
6. Slice involvement
| Slice | Scope | Milestone |
|---|---|---|
| S0 | Platform config CRUD + history, feature flag lifecycle + evaluation, aggregate health | M0 |
| S1 | Dynamic health source registration, tenant flag visibility, compatibility routes | M1 |
| S2 | Cross-tenant health dashboard, incident operations, license governance oversight | M2 |
| S3 | Data residency enforcement controls, feature flag per-user targeting | M3 |
7. Architecture diagram
8. Key design decisions
- Config allow-list only. Platform config keys are defined in code; unknown keys are rejected at the API boundary. Prevents runaway key proliferation.
- Feature flags are evaluation-first. The internal evaluate endpoint is the hot path; p95 ≤ 120 ms via Redis cache with 60 s TTL.
- Archived flags always evaluate to false. No complex state — archive is a terminal disable with history preserved.
- Health aggregation is pull-based. Services register health endpoints dynamically; platform-admin-service polls them on a configurable interval.
- Config and licensing are independent. Config controls platform behavior settings; licensing controls module entitlement. They do not merge (BR-ADM-002).
9. Source reconciliation
Single source module: _sources/platform-admin/. No legacy FR prefix conflicts — legacy refs FR-ADM-* map 1:1 to FR-PLTADM-*.