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

15 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.
  • Persist authenticated user language preference for shared Web/CLI locale selection.
  • Provide global search aggregation across entities.
  • Provide global context selectors (region/environment/time window) and per-user persistence for Pack 22 top-bar context.
  • Provide Pack 22 release read-model projections for list/detail/activity/approvals queue views.
  • Provide Pack 22 topology inventory read-model projections for regions/environments/targets/hosts/agents/promotion paths/workflows/gate profiles.
  • Surface platform metadata for UI bootstrapping (version, build, offline status).
  • Expose analytics lake aggregates for SBOM, vulnerability, and attestation reporting.

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/preferences/language
  • PUT /api/v1/platform/preferences/language
  • 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
  • Legacy notice: both endpoints now emit deprecation metadata (Deprecation, Sunset, Link, Warning) and are being replaced by Unified Search POST /api/v1/search/query.

Metadata

  • GET /api/v1/platform/metadata
  • Response includes a capabilities list for UI bootstrapping; analytics capability is reported only when analytics storage is configured.

Localization

  • GET /platform/i18n/{locale}.json (anonymous, cacheable UI translation bundle)
  • GET /api/v1/platform/localization/bundles/{locale}
  • GET /api/v1/platform/localization/bundles/{locale}/{namespace}
  • GET /api/v1/platform/localization/locales (catalog used by Web and CLI locale selectors)
  • PUT /api/v1/platform/localization/bundles
  • DELETE /api/v1/platform/localization/strings/{locale}/{key}
  • Backend locale resolution contract: X-Locale -> Accept-Language -> default locale.
  • Runtime bundle layering consumed by backend services: shared embedded common -> service embedded bundle -> Platform override bundle.
  • Platform ships locale-complete ui and platform namespace bundles for en-US, de-DE, bg-BG, ru-RU, es-ES, fr-FR, uk-UA, zh-TW, zh-CN; shared localization library now provides common bundles for the same locale set.
  • Bundled locales currently shipped: en-US, de-DE, bg-BG, ru-RU, es-ES, fr-FR, uk-UA, zh-TW, zh-CN.

API surface (v2)

Global context

  • GET /api/v2/context/regions
  • GET /api/v2/context/environments?regions=
  • GET /api/v2/context/preferences
  • PUT /api/v2/context/preferences

Releases read model

  • GET /api/v2/releases
  • GET /api/v2/releases/{releaseId}
  • GET /api/v2/releases/activity
  • GET /api/v2/releases/approvals

Topology inventory read model

  • GET /api/v2/topology/regions
  • GET /api/v2/topology/environments
  • GET /api/v2/topology/targets
  • GET /api/v2/topology/hosts
  • GET /api/v2/topology/agents
  • GET /api/v2/topology/promotion-paths
  • GET /api/v2/topology/workflows
  • GET /api/v2/topology/gate-profiles

Security read model

  • GET /api/v2/security/findings
  • GET /api/v2/security/disposition
  • GET /api/v2/security/disposition/{findingId}
  • GET /api/v2/security/sbom-explorer

Integrations read model

  • GET /api/v2/integrations/feeds
  • GET /api/v2/integrations/vex-sources

Analytics (SBOM lake)

  • GET /api/analytics/suppliers
  • GET /api/analytics/licenses
  • GET /api/analytics/vulnerabilities
  • GET /api/analytics/backlog
  • GET /api/analytics/attestation-coverage
  • GET /api/analytics/trends/vulnerabilities
  • GET /api/analytics/trends/components

Legacy alias compatibility (/api/v1/*)

  • GET /api/v1/context/regions (alias of /api/v2/context/regions)
  • GET /api/v1/releases (alias of /api/v2/releases)
  • GET /api/v1/topology/regions (alias of /api/v2/topology/regions)
  • GET /api/v1/security/findings (alias of /api/v2/security/findings)
  • GET /api/v1/integrations/feeds (alias of /api/v2/integrations/feeds)
  • GET /api/v1/integrations/vex-sources (alias of /api/v2/integrations/vex-sources)
  • Alias usage telemetry is emitted as deterministic event keys (alias_<method>_<route_pattern>) with tenant hash metadata only.

Data model

  • platform.dashboard_preferences (dashboard layout, widgets, filters, optional user locale preference key)
  • 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)
  • platform.translations (tenant + locale scoped translation override store)
  • platform.context_regions (global region selector inventory)
  • platform.context_environments (global environment selector inventory with region linkage)
  • platform.ui_context_preferences (tenant + actor scoped region/environment/time-window selections)
  • release.release_read_model (Pack 22 release list/detail projection root)
  • release.release_activity_projection (cross-release timeline projection with run/approval correlation keys)
  • release.release_approvals_projection (cross-release approval queue projection with blocker summaries)
  • release.security_finding_projection (Pack 22 consolidated findings projection with pivot/filter fields)
  • release.security_disposition_projection (read-only join projection for VEX + exception disposition state)
  • release.security_sbom_component_projection (component-level SBOM explorer table projection)
  • release.security_sbom_graph_projection (edge-level SBOM graph projection used by graph and diff modes)
  • release.integration_feed_source_health (advisory feed source health/freshness projection)
  • release.integration_vex_source_health (VEX source health/freshness projection with statement-format metadata)
  • release.integration_source_sync_watermarks (source family synchronization watermark projection state)
  • release.topology_region_inventory (region-level topology projection with deterministic ordering counts)
  • release.topology_environment_inventory (environment-level topology projection with region linkage and aggregate counters)
  • release.topology_target_inventory (target/component deployment inventory projection)
  • release.topology_host_inventory (host runtime inventory projection linked to targets and agents)
  • release.topology_agent_inventory (agent fleet projection with capability and assignment summaries)
  • release.topology_promotion_path_inventory (region-aware promotion-path projection with workflow and gate links)
  • release.topology_workflow_inventory (workflow template projection for topology routes)
  • release.topology_gate_profile_inventory (gate profile projection bound to region/environment inventory)
  • release.topology_sync_watermarks (projection synchronization watermark state for deterministic replay/cutover checks)
  • 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)

Runtime boundary policy

  • Runtime read-model services (/api/v2/releases, /api/v2/topology/*, /api/v2/security/*, /api/v2/integrations/*) must depend only on explicit query contracts:
  • IReleaseControlBundleStore
  • IPlatformContextQuery
  • Foreign module persistence references are migration/admin-only and limited to explicit allowlist surfaces (SeedEndpoints, MigrationModulePlugins).
  • Runtime read endpoints must not inject foreign *.Persistence* types, DbContext from other modules, or migration runners directly.
  • Guard tests: src/Platform/__Tests/StellaOps.Platform.WebService.Tests/PlatformRuntimeBoundaryGuardTests.cs.

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
  • Context: platform.context.read, platform.context.write
  • Releases read model: orch:read (platform.releasecontrol.read policy mapping in Platform service)
  • Topology read model: orch:read (platform.topology.read policy mapping in Platform service)
  • Security read model: findings:read (platform.security.read policy mapping in Platform service)
  • Integrations feed read model: advisory:read (platform.integrations.read policy mapping in Platform service)
  • Integrations VEX source read model: vex:read (platform.integrations.vex.read policy mapping in Platform service)
  • Search: search.read plus downstream service scopes (findings:read, policy:read, etc.)
  • Metadata: platform.metadata.read
  • Analytics: analytics.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.

Analytics ingestion configuration

Analytics ingestion runs inside the Platform WebService and subscribes to Scanner, Concelier, and Attestor streams. Configure ingestion with Platform:AnalyticsIngestion:

Platform:
  AnalyticsIngestion:
    Enabled: true
    PostgresConnectionString: "" # optional; defaults to Platform:Storage
    AllowedTenants: ["tenant-a"]
    Streams:
      ScannerStream: "orchestrator:events"
      ConcelierObservationStream: "concelier:advisory.observation.updated:v1"
      ConcelierLinksetStream: "concelier:advisory.linkset.updated:v1"
      AttestorStream: "attestor:events"
      StartFromBeginning: false
    Cas:
      RootPath: "/var/lib/stellaops/cas"
      DefaultBucket: "attestations"
    Attestations:
      BundleUriTemplate: "bundle:{digest}"

BundleUriTemplate supports {digest} and {hash} placeholders. The bundle: scheme maps to cas://<DefaultBucket>/{digest} by default. Verify offline bundles with stella bundle verify before ingestion.

Analytics maintenance configuration

Analytics rollups + materialized view refreshes are driven by PlatformAnalyticsMaintenanceService when analytics storage is configured.
Use BackfillDays to recompute recent rollups on the first maintenance run (set to 0 to disable).

Platform:
  Storage:
    PostgresConnectionString: "Host=...;Database=...;Username=...;Password=..."
  AnalyticsMaintenance:
    Enabled: true
    RunOnStartup: true
    IntervalMinutes: 1440
    ComputeDailyRollups: true
    RefreshMaterializedViews: true
    BackfillDays: 7

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.

Setup Wizard

The Platform Service exposes setup wizard endpoints to support first-run configuration and reconfiguration workflows. These endpoints replace UI-mock implementations with real backend state management.

API surface (v1)

Sessions

  • GET /api/v1/setup/sessions - Get current setup session for tenant
  • POST /api/v1/setup/sessions - Create new setup session
  • POST /api/v1/setup/sessions/resume - Resume existing or create new session
  • POST /api/v1/setup/sessions/finalize - Finalize setup session

Steps

  • POST /api/v1/setup/steps/execute - Execute a setup step (runs Doctor checks)
  • POST /api/v1/setup/steps/skip - Skip an optional setup step

Definitions

  • GET /api/v1/setup/definitions/steps - List all step definitions

Setup step identifiers

Step ID Title Required Depends On
Database Database Setup Yes -
Valkey Valkey/Redis Setup Yes -
Migrations Database Migrations Yes Database
Admin Admin Bootstrap Yes Migrations
Crypto Crypto Profile Yes Admin
Vault Vault Integration No -
Scm SCM Integration No -
Notifications Notification Channels No -
Environments Environment Definition No Admin
Agents Agent Registration No Environments

Setup session states

Status Description
NotStarted Setup not begun
InProgress Setup in progress
Completed All steps completed
CompletedPartial Required steps completed, optional skipped
Failed Required step failed
Abandoned Setup abandoned by user

Setup step states

Status Description
Pending Not yet started
Current Currently active step
Passed Completed successfully
Failed Validation failed
Skipped Explicitly skipped
Blocked Blocked by dependency

Security and scopes

  • Read: platform.setup.read
  • Write: platform.setup.write
  • Admin: platform.setup.admin

Offline posture

  • Sessions include DataAsOfUtc for offline rendering with stale indicators
  • Step results cached with Doctor check pass/fail status
  • Suggested fixes generated for failed checks

Related documentation

  • UX flow specification: docs/setup/setup-wizard-ux.md
  • Repository inventory: docs/setup/setup-wizard-inventory.md
  • Doctor checks: docs/setup/setup-wizard-doctor-contract.md