stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

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

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-30 01:22:58 +02:00
parent 1dc4bcbf10
commit 7a5210e2aa
928 changed files with 183942 additions and 3941 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/modules/platform/AGENTS.md
View File

@@ -1,11 +1,12 @@
# Platform agent guide
## Mission
Platform module describes cross-cutting architecture, contracts, and guardrails that bind the services together.
Platform module describes cross-cutting architecture and now owns the Platform Service that aggregates health, quotas, onboarding, preferences, and global search for the Console UI.
## Key docs
- [Module README](./README.md)
- [Architecture](./architecture.md)
- [Platform Service](./platform-service.md)
- [Implementation plan](./implementation_plan.md)
- [Task board](./TASKS.md)
- [Architecture overview](./architecture-overview.md)
@@ -24,6 +25,7 @@ Platform module describes cross-cutting architecture, contracts, and guardrails
## Required Reading
- `docs/modules/platform/README.md`
- `docs/modules/platform/architecture.md`
- `docs/modules/platform/platform-service.md`
- `docs/modules/platform/implementation_plan.md`
- `docs/modules/platform/architecture-overview.md`

17
docs/modules/platform/README.md
View File

@@ -2,15 +2,16 @@
Platform module describes cross-cutting architecture, contracts, and guardrails that bind the services together.
## Latest updates (2025-11-30)
- Sprint tracker `docs/implplan/SPRINT_0324_0001_0001_docs_modules_platform.md` and module `TASKS.md` added to mirror status.
- README now points to architecture overview, AOC references, and offline guidance entry points.
- Platform module remains docs-only; no runtime services.
## Latest updates (2025-12-29)
- Added Platform Service definition (`platform-service.md`) and sprint scope for service foundation.
- README updated to reflect runtime service ownership alongside cross-cutting docs.
- Platform-facing UI sprints now depend on Platform Service aggregation endpoints.
## Responsibilities
- Maintain the system-wide architecture overview and integration diagrams.
- Capture Aggregation-Only Contract guidance and migration playbooks.
- Document shared services such as API gateway, tenancy, quotas, and offline posture.
- Define and maintain Platform Service API contracts and aggregation behavior.
- Coordinate platform-wide epics and compliance checklists.
## Key components
@@ -24,7 +25,7 @@ Platform module describes cross-cutting architecture, contracts, and guardrails
- Docs guild for cross-module onboarding.
## Operational notes
- Docs-only module; focus is architectural governance and cross-module guardrails.
- Module spans architecture governance and the Platform Service aggregation APIs.
- Glossaries and guardrails cross-linked across docs; keep AOC references current.
- Status mirrors: sprint file and `docs/modules/platform/TASKS.md`.
@@ -58,9 +59,9 @@ Platform module describes cross-cutting architecture, contracts, and guardrails
- Glossaries and guardrails: cross-linked across all module documentation
### Technical Notes
- Platform is docs-only; no runtime services
- Focus on architectural governance and cross-module guardrails
- Ensures discoverability of Offline Kit and AOC references from README/architecture
- Platform includes the Platform Service runtime plus docs ownership
- Focus on architectural governance and cross-module aggregation endpoints
- Ensure discoverability of Offline Kit and AOC references from README/architecture
## Epic alignment
- Aligns with the Aggregation-Only Contract reference, Policy and Policy Studio guides, Graph/Vulnerability Explorer documentation, and the Orchestrator, Advisory AI, and Notifications implementation plans to keep platform guardrails consistent across services.

19
docs/modules/platform/TASKS.md Normal file
View File

@@ -0,0 +1,19 @@
# Platform Module Task Board
This board mirrors the active platform sprint(s). Update alongside the sprint tracker.
## Active sprint tasks
Source of truth: `docs/implplan/SPRINT_20251229_043_PLATFORM_platform_service_foundation.md`.
| Task ID | Status | Notes |
| --- | --- | --- |
| PLAT-SVC-001 | DONE | Platform Service project scaffold. |
| PLAT-SVC-002 | DONE | Health aggregation endpoints. |
| PLAT-SVC-003 | DONE | Quota aggregation endpoints. |
| PLAT-SVC-004 | DONE | Onboarding state storage + APIs. |
| PLAT-SVC-005 | DONE | Preferences storage + APIs. |
| PLAT-SVC-006 | DONE | Global search aggregation. |
| PLAT-SVC-007 | DONE | Gateway route registration + scopes. |
| PLAT-SVC-008 | DONE | Observability metrics/logging. |
| PLAT-SVC-009 | DONE | Determinism/offline tests. |
| PLAT-SVC-010 | DONE | Docs/runbooks update. |

10
docs/modules/platform/architecture-overview.md
View File

@@ -53,7 +53,7 @@ graph TD
Notify[Notifier]
end
subgraph Experience["UX & Export"]
UIService[Console Backend]
PlatformSvc[Platform Service<br/>(Console Backend)]
Exporters[Export / Offline Kit]
end
Observability[Telemetry Stack]
@@ -70,9 +70,9 @@ graph TD
RawStore --> Policy
Policy --> Scheduler
Policy --> Notify
Policy --> UIService
Scheduler --> UIService
UIService --> Exporters
Policy --> PlatformSvc
Scheduler --> PlatformSvc
PlatformSvc --> Exporters
Exporters --> CLI
Exporters --> Offline[Offline Kit]
Observability -.-> ScannerWeb
@@ -83,6 +83,8 @@ graph TD
Observability -.-> Notify
```
Platform Service (StellaOps.Platform.WebService) aggregates cross-service status for the Console UI (health, quotas, onboarding, preferences, global search) and does not mutate raw evidence.
Key boundaries:
- **AOC border.** Everything inside the Ingestion subgraph writes only immutable raw facts plus link hints. Derived severity, consensus, and risk remain outside the border.

2
docs/modules/platform/architecture.md
View File

@@ -5,12 +5,14 @@ This module aggregates cross-cutting contracts and guardrails that every StellaO
## Anchors
- High-level system view: `../../07_HIGH_LEVEL_ARCHITECTURE.md`
- Platform overview: `architecture-overview.md`
- Platform service definition: `platform-service.md`
- Aggregation-Only Contract: `../../aoc/aggregation-only-contract.md` (referenced across ingestion/observability docs)
## Scope
- **Identity & tenancy**: Authority-issued OpToks, tenant scoping, RBAC, short TTLs; see Authority module docs.
- **AOC & provenance**: services ingest evidence without mutating/merging; provenance preserved; determinism required.
- **Offline posture**: Offline Kit parity, sealed-mode defaults, deterministic bundles.
- **Platform Service**: aggregation endpoints for health, quotas, onboarding, preferences, and global search.
- **Observability baseline**: metrics/logging/tracing patterns reused across modules; collectors documented under Telemetry module.
- **Determinism**: stable ordering, UTC timestamps, content-addressed artifacts, reproducible exports.

32
docs/modules/platform/implementation_plan.md Normal file
View File

@@ -0,0 +1,32 @@
# Platform Module Implementation Plan
## Purpose
Provide a lightweight, living plan for platform-level capabilities, with the Platform Service as the primary delivery vehicle for cross-service aggregation needed by the Console UI and CLI.
## Active work
- `docs/implplan/SPRINT_20251229_043_PLATFORM_platform_service_foundation.md` (Platform Service foundation).
## Near-term deliverables
- `StellaOps.Platform.WebService` skeleton with health endpoint and auth wiring.
- Aggregation endpoints for health, quotas, onboarding, preferences, and global search.
- Deterministic caching behavior with "data as of" metadata for offline display.
- Platform metadata endpoint and capability listing for UI bootstrapping.
- Gateway registration and scoped access policies.
- Unit + integration tests for ordering, caching, and error handling.
- Postgres schema stub for platform state (`docs/db/schemas/platform.sql`).
## Dependencies
- Authority (identity, scopes, tenant claims).
- Gateway/Router (route registration, auth headers, rate limits).
- Orchestrator, Notifier, and storage services for aggregation inputs.
## Evidence of completion
- Service project under `src/Platform/StellaOps.Platform.WebService`.
- Updated platform documentation and runbooks.
- Postgres schema spec at `docs/db/schemas/platform.sql`.
- Passing deterministic aggregation tests.
## Reference docs
- `docs/modules/platform/platform-service.md`
- `docs/modules/platform/architecture.md`
- `docs/modules/platform/architecture-overview.md`

86
docs/modules/platform/platform-service.md Normal file
View File

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