stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
f2565a32246af5e6c34879b9edb68d9391418e1b
git.stella-ops.org/docs/modules/platform/platform-service.md

3.6 KiB
Raw Blame History

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.