# 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.