Files
git.stella-ops.org/docs/implplan/archived
master 396e9b75a4 docs: Add comprehensive component architecture documentation
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>
2025-12-23 11:05:55 +02:00
..
up
2025-12-14 16:24:16 +02:00
up
2025-12-12 09:35:37 +02:00
up
2025-12-13 18:08:55 +02:00
up
2025-12-13 18:08:55 +02:00
up
2025-12-12 09:35:37 +02:00
up
2025-11-25 22:09:44 +02:00
up
2025-12-12 09:35:37 +02:00
up
2025-12-12 09:35:37 +02:00
up
2025-12-13 18:08:55 +02:00
up
2025-12-13 18:08:55 +02:00
up
2025-12-13 18:08:55 +02:00
up
2025-12-14 16:24:16 +02:00
up
2025-12-14 16:24:16 +02:00
up
2025-12-13 00:20:26 +02:00
up
2025-12-13 00:20:26 +02:00
up
2025-12-13 00:20:26 +02:00
up
2025-12-14 16:24:16 +02:00
up
2025-12-13 00:20:26 +02:00
up
2025-12-13 18:08:55 +02:00
up
2025-12-13 18:08:55 +02:00
up
2025-12-14 18:45:56 +02:00
up
2025-12-14 18:45:56 +02:00
up
2025-12-14 18:45:56 +02:00
up
2025-12-14 18:45:56 +02:00
up
2025-12-14 18:45:56 +02:00
up
2025-12-14 18:45:56 +02:00
up
2025-12-14 18:45:56 +02:00
up
2025-12-12 09:35:37 +02:00
up
2025-12-12 09:35:37 +02:00
up
2025-12-11 08:20:15 +02:00
up
2025-12-12 09:35:37 +02:00