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
..
2025-12-22 09:50:12 +02:00
2025-12-22 19:10:27 +02:00
2025-12-14 16:24:16 +02:00
2025-12-12 09:35:37 +02:00
2025-12-11 02:32:18 +02:00
2025-12-11 02:32:18 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-13 18:08:55 +02:00
2025-12-13 18:08:55 +02:00
2025-12-13 18:08:55 +02:00
2025-12-10 19:13:29 +02:00
2025-12-05 08:01:47 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-12 09:35:37 +02:00
2025-11-25 22:09:44 +02:00
2025-12-12 09:35:37 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-20 01:26:42 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-12 09:35:37 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-13 18:08:55 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-13 18:08:55 +02:00
2025-12-11 02:32:18 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-07 22:49:53 +02:00
2025-12-10 19:13:29 +02:00
2025-12-07 22:49:53 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-13 18:08:55 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-21 08:29:51 +02:00
2025-12-12 09:35:37 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-11 02:32:18 +02:00
2025-12-10 19:13:29 +02:00
2025-12-11 02:32:18 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-11 02:32:18 +02:00
2025-12-10 19:13:29 +02:00
2025-12-11 02:32:18 +02:00
2025-12-10 19:13:29 +02:00
2025-12-11 02:32:18 +02:00
2025-12-11 02:32:18 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-11 02:32:18 +02:00
2025-12-11 02:32:18 +02:00
2025-12-11 02:32:18 +02:00
2025-12-10 19:13:29 +02:00
2025-12-11 02:32:18 +02:00
2025-12-11 02:32:18 +02:00
2025-12-10 19:13:29 +02:00
2025-12-11 02:32:18 +02:00
2025-12-21 17:51:58 +02:00
2025-12-11 02:32:18 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-11 02:32:18 +02:00
2025-12-11 02:32:18 +02:00
2025-12-11 02:32:18 +02:00
2025-12-11 08:20:04 +02:00
2025-12-11 02:32:18 +02:00
2025-12-14 16:24:16 +02:00
2025-12-11 02:32:18 +02:00
2025-12-11 02:32:18 +02:00
2025-12-11 02:32:18 +02:00
2025-12-11 02:32:18 +02:00
2025-12-06 21:48:12 +02:00
2025-12-06 21:48:12 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-11 02:32:18 +02:00
2025-12-14 16:24:16 +02:00
2025-12-10 19:13:29 +02:00
2025-12-21 08:29:51 +02:00
2025-12-13 00:20:26 +02:00
2025-12-13 00:20:26 +02:00
2025-12-13 00:20:26 +02:00
2025-12-14 16:24:16 +02:00
2025-12-13 00:20:26 +02:00
2025-12-10 19:13:29 +02:00
2025-12-21 08:29:51 +02:00
2025-12-13 18:08:55 +02:00
2025-12-13 18:08:55 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-16 10:44:00 +02:00
2025-12-16 10:44:00 +02:00
2025-12-16 10:44:24 +02:00
2025-12-16 10:44:00 +02:00
2025-12-16 10:44:24 +02:00
2025-12-19 22:19:08 +02:00
2025-12-18 00:47:24 +02:00
2025-12-16 10:44:24 +02:00
2025-12-19 22:19:08 +02:00
2025-12-18 13:15:13 +02:00
2025-12-18 13:15:13 +02:00
2025-12-18 13:15:13 +02:00
2025-12-19 22:19:08 +02:00
2025-12-18 00:47:24 +02:00
2025-12-18 00:47:24 +02:00
2025-12-18 00:47:24 +02:00
2025-12-18 00:47:24 +02:00
2025-12-18 00:47:24 +02:00
2025-12-12 09:35:37 +02:00
2025-12-14 23:20:14 +02:00
2025-12-13 18:08:55 +02:00
2025-12-13 18:08:55 +02:00
2025-12-13 18:08:55 +02:00
2025-12-21 17:51:58 +02:00
2025-12-21 17:51:58 +02:00
2025-12-20 12:15:16 +02:00
2025-12-13 18:08:55 +02:00
2025-12-13 18:08:55 +02:00
2025-12-22 19:10:27 +02:00
2025-12-21 17:51:58 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-14 18:45:56 +02:00
2025-12-18 00:47:24 +02:00
2025-12-14 18:45:56 +02:00
2025-12-18 00:47:24 +02:00
2025-12-18 00:47:24 +02:00
2025-12-18 00:47:24 +02:00
2025-12-18 00:47:24 +02:00
2025-12-18 00:47:24 +02:00
2025-12-18 00:47:24 +02:00
2025-12-18 00:47:24 +02:00
2025-12-18 00:47:24 +02:00
2025-12-14 18:45:56 +02:00
2025-12-14 18:45:56 +02:00
2025-12-14 18:45:56 +02:00
2025-12-14 18:45:56 +02:00
2025-12-14 18:45:56 +02:00
2025-12-14 18:45:56 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-11 19:47:43 +02:00
2025-12-12 09:35:37 +02:00
2025-12-12 09:35:37 +02:00
2025-12-11 08:20:15 +02:00
2025-12-12 09:35:37 +02:00
2025-12-12 09:35:37 +02:00
2025-12-12 09:35:37 +02:00
2025-12-12 09:35:37 +02:00
2025-12-11 02:32:18 +02:00
2025-12-11 02:32:18 +02:00
2025-12-16 10:44:24 +02:00
2025-12-16 10:44:24 +02:00
2025-12-16 10:44:24 +02:00
2025-12-16 10:44:24 +02:00
2025-12-16 10:44:24 +02:00
2025-12-16 10:44:24 +02:00
2025-12-22 09:50:12 +02:00
2025-12-18 13:15:13 +02:00
2025-12-18 13:15:13 +02:00
2025-12-18 13:15:13 +02:00
2025-12-18 13:15:13 +02:00
2025-12-18 13:15:13 +02:00
2025-12-18 13:15:13 +02:00
2025-12-22 09:50:12 +02:00
2025-12-22 09:50:12 +02:00
2025-12-22 23:21:21 +02:00
2025-12-22 23:21:21 +02:00
2025-12-19 22:19:08 +02:00
2025-12-18 00:47:24 +02:00
2025-12-18 00:47:24 +02:00
2025-12-16 10:44:24 +02:00
2025-12-16 10:44:24 +02:00
2025-12-16 10:44:24 +02:00
2025-12-18 13:15:13 +02:00
2025-12-18 20:37:12 +02:00
2025-12-19 22:19:08 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-18 00:47:24 +02:00
2025-12-10 19:13:29 +02:00
2025-12-22 19:10:27 +02:00
2025-12-10 19:13:29 +02:00
2025-12-18 00:47:24 +02:00
2025-12-18 00:47:24 +02:00
2025-12-12 09:35:37 +02:00
2025-12-19 22:19:08 +02:00
2025-12-10 19:13:29 +02:00
2025-12-19 22:19:08 +02:00
2025-12-10 19:13:29 +02:00
2025-12-18 00:47:24 +02:00
2025-12-10 19:13:29 +02:00
2025-12-18 00:47:24 +02:00
2025-12-10 19:13:29 +02:00
2025-12-22 19:10:27 +02:00
2025-12-10 19:13:29 +02:00
2025-12-10 19:13:29 +02:00
2025-12-07 22:49:53 +02:00
2025-12-19 22:19:08 +02:00
2025-12-13 18:08:55 +02:00
2025-12-19 22:19:08 +02:00
2025-12-11 17:48:25 +02:00
2025-12-14 15:50:38 +02:00
2025-12-19 22:19:08 +02:00
2025-12-18 13:15:13 +02:00
2025-12-18 13:15:13 +02:00
2025-12-22 19:10:27 +02:00
2025-12-18 13:15:13 +02:00
2025-12-20 01:26:42 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-19 22:19:08 +02:00
2025-12-18 13:15:13 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-18 13:15:13 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-19 22:19:08 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-19 22:19:08 +02:00
2025-12-19 22:19:08 +02:00
2025-12-19 22:19:08 +02:00
2025-12-19 22:19:08 +02:00
2025-12-20 01:26:42 +02:00
2025-12-19 22:19:08 +02:00
2025-12-22 19:10:27 +02:00
2025-12-23 09:23:42 +02:00
2025-12-18 00:47:24 +02:00
2025-12-23 09:23:42 +02:00
2025-12-20 01:26:42 +02:00
2025-12-20 01:26:42 +02:00
2025-12-18 13:15:13 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-18 13:15:13 +02:00
2025-12-22 19:10:27 +02:00
2025-12-23 09:23:42 +02:00
2025-12-19 22:19:08 +02:00
2025-12-23 09:23:42 +02:00
2025-12-22 19:10:27 +02:00
2025-12-16 10:44:24 +02:00
2025-12-18 13:15:13 +02:00
2025-12-18 13:15:13 +02:00
2025-12-16 10:44:24 +02:00
2025-12-16 10:44:24 +02:00
2025-12-16 10:44:24 +02:00
2025-12-19 22:19:08 +02:00
2025-12-19 22:19:08 +02:00
2025-12-19 22:19:08 +02:00
2025-12-19 22:19:08 +02:00
2025-12-19 22:19:08 +02:00
2025-12-19 22:19:08 +02:00
2025-12-19 22:19:08 +02:00
2025-12-19 22:19:08 +02:00
2025-12-19 22:19:08 +02:00
2025-12-22 09:50:12 +02:00
2025-12-19 22:19:08 +02:00
2025-12-19 22:19:08 +02:00
2025-12-19 22:19:08 +02:00
2025-12-20 01:26:42 +02:00
2025-12-19 22:19:08 +02:00
2025-12-19 22:32:38 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-19 22:19:08 +02:00
2025-12-19 22:19:08 +02:00
2025-12-19 22:19:08 +02:00
2025-12-20 01:26:42 +02:00
2025-12-20 01:26:42 +02:00
2025-12-20 01:26:42 +02:00
2025-12-20 01:26:42 +02:00
2025-12-20 01:26:42 +02:00
2025-12-19 22:19:08 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-19 22:19:08 +02:00
2025-12-22 23:21:21 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 23:21:21 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-19 22:19:08 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-22 19:10:27 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-22 19:10:27 +02:00
2025-12-23 09:23:42 +02:00
2025-12-22 19:10:27 +02:00
2025-12-23 11:05:55 +02:00
2025-12-22 19:10:27 +02:00
2025-12-23 11:05:55 +02:00
2025-12-22 19:10:27 +02:00
2025-12-23 11:05:55 +02:00
2025-12-22 19:10:27 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 10:56:38 +02:00
2025-12-23 10:56:38 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-16 10:44:24 +02:00
2025-12-16 10:44:24 +02:00
2025-12-20 01:26:42 +02:00
2025-12-22 23:21:21 +02:00
2025-12-23 09:23:42 +02:00
2025-12-22 23:21:21 +02:00
2025-12-22 23:21:21 +02:00
2025-12-22 23:21:21 +02:00
2025-12-22 23:21:21 +02:00
2025-12-22 23:21:21 +02:00
2025-12-22 23:21:21 +02:00
2025-12-22 23:21:21 +02:00
2025-12-22 23:21:21 +02:00
2025-12-23 09:23:42 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-22 19:10:27 +02:00
2025-12-23 09:23:42 +02:00
2025-12-23 09:23:42 +02:00
2025-12-22 19:10:27 +02:00
2025-12-23 07:28:21 +02:00
2025-12-23 07:28:21 +02:00
2025-12-23 07:28:21 +02:00
2025-12-23 07:28:21 +02:00
2025-12-23 07:28:21 +02:00
2025-12-23 07:46:40 +02:00
2025-12-21 08:29:51 +02:00