396e9b75a4
Created detailed architectural documentation showing component interactions, communication patterns, and data flows across all StellaOps services. ## New Documentation **docs/ARCHITECTURE_DETAILED.md** - Comprehensive architecture guide: - Component topology diagram (all 36+ services) - Infrastructure layer details (PostgreSQL, Valkey, RustFS, NATS) - Service-by-service catalog with responsibilities - Communication patterns with WHY (business purpose) - 5 detailed data flow diagrams: 1. Scan Request Flow (CLI → Scanner → Worker → Policy → Signer → Attestor → Notify) 2. Advisory Update Flow (Concelier → Scheduler → Scanner re-evaluation) 3. VEX Update Flow (Excititor → IssuerDirectory → Scheduler → Policy) 4. Notification Delivery Flow (Scanner → Valkey → Notify → Slack/Teams/Email) 5. Policy Evaluation Flow (Scanner → Policy.Gateway → OPA → PostgreSQL replication) - Database schema isolation details per service - Security boundaries and authentication flows ## Updated Documentation **docs/DEVELOPER_ONBOARDING.md**: - Added link to detailed architecture - Simplified overview with component categories - Quick reference topology tree **docs/07_HIGH_LEVEL_ARCHITECTURE.md**: - Updated infrastructure requirements section - Clarified PostgreSQL as ONLY database - Emphasized Valkey as REQUIRED (not optional) - Marked NATS as optional (Valkey is default transport) **docs/README.md**: - Added link to detailed architecture in navigation ## Key Architectural Insights Documented **Communication Patterns:** - 11 communication steps in scan flow (Gateway → Scanner → Valkey → Worker → Concelier → Policy → Signer → Attestor → Valkey → Notify → Slack) - PostgreSQL logical replication (advisory_raw_stream, vex_raw_stream → Policy Engine) - Valkey Streams for async job queuing (XADD/XREADGROUP pattern) - HTTP webhooks for delta events (Concelier/Excititor → Scheduler) **Security Boundaries:** - Authority issues OpToks with DPoP binding (RFC 9449) - Signer enforces PoE validation + scanner digest verification - All services validate JWT + DPoP on every request - Tenant isolation via tenant_id in all PostgreSQL queries **Database Patterns:** - 8 dedicated PostgreSQL schemas (authority, scanner, vuln, vex, scheduler, notify, policy, orchestrator) - Append-only advisory/VEX storage (AOC - Aggregation-Only Contract) - BOM-Index for impact selection (CVE → PURL → image mapping) This documentation provides complete visibility into who calls who, why they communicate, what data flows through the system, and how security is enforced at every layer. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
StellaOps Concelier & CLI
This repository hosts the StellaOps Concelier service, its plug-in ecosystem, and the
first-party CLI (stellaops-cli). Concelier ingests vulnerability advisories from
authoritative sources, stores them in PostgreSQL, and exports deterministic JSON and
Trivy DB artefacts. The CLI drives scanner distribution, scan execution, and job
control against the Concelier API.
Quickstart
- Prepare a PostgreSQL instance and (optionally) install
trivy-db/oras. - Copy
etc/concelier.yaml.sampletoetc/concelier.yamland update the storage + telemetry settings. - Copy
etc/authority.yaml.sampletoetc/authority.yaml, review the issuer, token lifetimes, and plug-in descriptors, then edit the companion manifests underetc/authority.plugins/*.yamlto match your deployment. - Start the web service with
dotnet run --project src/Concelier/StellaOps.Concelier.WebService. - Configure the CLI via environment variables (e.g.
STELLAOPS_BACKEND_URL) and trigger jobs withdotnet run --project src/Cli/StellaOps.Cli -- db merge.
Detailed operator guidance is available in docs/10_CONCELIER_CLI_QUICKSTART.md. API and
command reference material lives in docs/09_API_CLI_REFERENCE.md.
Pipeline note: deployment workflows should template etc/concelier.yaml during CI/CD,
injecting environment-specific PostgreSQL connection strings and telemetry endpoints.
Upcoming releases will add Microsoft OAuth (Entra ID) authentication support—track
the quickstart for integration steps once available.
Documentation
docs/README.mdnow consolidates the platform index and points to the updated high-level architecture.- Module architecture dossiers now live under
docs/modules/<module>/. The most relevant here aredocs/modules/concelier/ARCHITECTURE.md(service layout, merge engine, exports) anddocs/modules/cli/ARCHITECTURE.md(command surface, AOT packaging, auth flows). Related services such as the Signer, Attestor, Authority, Scanner, UI, Excititor, Zastava, and DevOps pipeline each have their own dossier in the same hierarchy. - Offline operation guidance moved to
docs/24_OFFLINE_KIT.md, which details bundle composition, verification, and delta workflows. Concelier-specific connector operations stay indocs/modules/concelier/operations/connectors/*.mdwith companion runbooks indocs/modules/concelier/operations/.