Frontend gaps fill work. Testing fixes work. Auditing in progress.

docs/modules/platform/platform-service.md

@@ -0,0 +1,86 @@
+# Platform Service (StellaOps.Platform.WebService)
+
+## Purpose
+Provide a single, deterministic aggregation layer for cross-service UX workflows (health, quotas, onboarding, preferences, global search) so the Console UI and CLI do not fan out to multiple modules directly.
+
+## Non-goals
+- Replace module-owned APIs (Authority, Policy, Scanner, Orchestrator, etc.).
+- Ingest or mutate raw evidence or policy overlays.
+- Store high-volume evidence payloads (SBOMs, VEX, audit bundles).
+
+## Responsibilities
+- Aggregate platform health and dependency status.
+- Aggregate quota usage across Authority, Gateway, Orchestrator, and storage backends.
+- Persist onboarding progress and tenant setup milestones.
+- Persist dashboard personalization and layout preferences.
+- Provide global search aggregation across entities.
+- Surface platform metadata for UI bootstrapping (version, build, offline status).
+
+## API surface (v1)
+
+### Health aggregation
+- GET `/api/v1/platform/health/summary`
+- GET `/api/v1/platform/health/dependencies`
+- GET `/api/v1/platform/health/incidents`
+- GET `/api/v1/platform/health/metrics`
+
+### Quota aggregation
+- GET `/api/v1/platform/quotas/summary`
+- GET `/api/v1/platform/quotas/tenants/{tenantId}`
+- GET `/api/v1/platform/quotas/alerts`
+- POST `/api/v1/platform/quotas/alerts`
+
+### Onboarding
+- GET `/api/v1/platform/onboarding/status`
+- POST `/api/v1/platform/onboarding/complete/{step}`
+- POST `/api/v1/platform/onboarding/skip`
+- GET `/api/v1/platform/tenants/{tenantId}/setup-status`
+
+### Preferences
+- GET `/api/v1/platform/preferences/dashboard`
+- PUT `/api/v1/platform/preferences/dashboard`
+- GET `/api/v1/platform/dashboard/profiles`
+- GET `/api/v1/platform/dashboard/profiles/{profileId}`
+- POST `/api/v1/platform/dashboard/profiles`
+
+### Global search
+- GET `/api/v1/search` (alias to `/api/v1/platform/search`)
+- GET `/api/v1/platform/search`
+
+### Metadata
+- GET `/api/v1/platform/metadata`
+
+## Data model
+- `platform.dashboard_preferences` (dashboard layout, widgets, filters)
+- `platform.dashboard_profiles` (saved profiles per tenant)
+- `platform.onboarding_state` (step state, timestamps, actor)
+- `platform.quota_alerts` (per-tenant quota alert thresholds)
+- `platform.search_history` (optional, user-scoped, append-only)
+- Schema reference: `docs/db/schemas/platform.sql` (PostgreSQL; in-memory stores used until storage driver switches).
+
+## Dependencies
+- Authority (tenant/user identity, quotas, RBAC)
+- Gateway (rate-limit status and request telemetry)
+- Orchestrator (job quotas, SLO state)
+- Notifier (alert policies and delivery status)
+- Policy/Scanner/Registry/VexHub (search aggregation sources)
+
+## Security and scopes
+- Health: `ops.health` (summary), `ops.admin` (metrics)
+- Quotas: `quota.read` (summary), `quota.admin` (alerts/config)
+- Onboarding: `onboarding.read`, `onboarding.write`
+- Preferences: `ui.preferences.read`, `ui.preferences.write`
+- Search: `search.read` plus downstream service scopes (`findings:read`, `policy:read`, etc.)
+- Metadata: `platform.metadata.read`
+
+## Determinism and offline posture
+- Stable ordering with explicit sort keys and deterministic tiebreakers.
+- All timestamps in UTC ISO-8601.
+- Cache last-known snapshots for offline rendering with "data as of" markers.
+
+## Observability
+- Metrics: `platform.aggregate.latency_ms`, `platform.aggregate.errors_total`, `platform.aggregate.cache_hits_total`
+- Logs include `traceId`, `tenantId`, `operation`, and cache-hit indicators.
+
+## Gateway exposure
+The Platform Service is exposed via Gateway and registered through Router discovery. It does not expose direct ingress outside Gateway in production.