Architecture Decision Records
This directory contains Architecture Decision Records (ADRs) documenting significant technical decisions made during SecurityV0 development.
ADR Index
| ADR | Title | Status | Date |
|---|---|---|---|
| ADR-000 | Documentation Strategy | Accepted | 2026-02 |
| ADR-001 | MongoDB Only for MVP | Accepted | 2026-01-22 |
| ADR-002 | Single Entities Collection | Accepted | 2026-01-27 |
| ADR-003 | Reject Apache AGE | Accepted | 2026-02-02 |
| ADR-004 | Import-by-Type Connector Architecture | Accepted | 2026-02-10 |
| ADR-005 | Platform-Only Finding Generation | Accepted | 2026-02-10 |
| ADR-006 | Entity Type Reclassification | Accepted | 2026-02-13 |
| ADR-007 | Execution Relationship Types | Accepted | 2026-02-13 |
| ADR-008 | Execution Chains Collection | Accepted | 2026-02-13 |
| ADR-009 | OAA Export Projection (Deferred) | Proposed | 2026-02-13 |
| ADR-010 | Workload Entity Type Rename | Accepted | 2026-02-17 |
| ADR-011 | ELK.js Graph Layout Engine | Accepted | 2026-02-22 |
| ADR-012 | User Authentication Strategy | Accepted | 2026-03 |
| ADR-013 | Container Registry (GHCR) | Accepted | 2026-03 |
| ADR-014 | AWS IAM Policy Entity Type — Introduce permission_set | Accepted | 2026-03-11 |
| ADR-015 | AWS Source System Tenancy Scheme | Accepted | 2026-03-11 |
| ADR-018 | Deploy-Server Security Posture Before Managed-Platform Migration | Accepted | 2026-04-20 |
| ADR-020 | Multi-Region MongoDB Strategy via Per-Region Clusters | Accepted | 2026-05-02 |
| ADR-021 | Delegated-Agent Audit Log Storage | Proposed | 2026-05-04 |
| ADR-024 | Azure Dev Deployment Lifecycle — Stable Demo + Ephemeral PR-Preview Pool | Proposed | 2026-05-14 |
| ADR-026 | Chain Re-Materialization Triggers — Sync / Evaluation / Deploy | Proposed | 2026-05-19 |
| ADR-027 | Automated Connector Pipeline — credential broker, pipeline-run root, deploy-gate | Draft | 2026-05-19 |
| ADR-030 | CI Cost & Build-Architecture Strategy — amd64-on-PR, concurrency, path-gating | Accepted | 2026-05-22 |
ADR Format
Each ADR follows this structure:
- Status - Proposed, Accepted, Deprecated, Superseded
- Context - What prompted this decision
- Decision - What we decided
- Consequences - Positive, negative, and trade-offs
- When to Reconsider - Triggers for revisiting
Key Decisions Summary
Documentation
ADR-000: Documentation Strategy - Use Markdown + MkDocs + GitHub for private, AI-accessible documentation. mkdocs.yml nav serves as the authoritative manifest; @ai-metadata HTML comments provide token-efficient AI scanning.
Database Architecture
ADR-001: MongoDB Only for MVP - Use MongoDB as the single database for MVP. Graph queries handled via materialized execution paths and application-level traversal. Neo4j to be added later when scale requires it.
ADR-002: Single Entities Collection - Store all entity types (identity, automation, connection, credential, owner, role, permission, resource, execution_evidence) in a single entities collection with entity_type discriminator. Optimizes for security investigation query patterns.
ADR-003: Reject Apache AGE - Do not adopt Apache AGE (PostgreSQL graph extension) due to poor variable-length path performance at scale and lack of AWS managed service availability.
Connector Architecture
ADR-004: Import-by-Type Connector Architecture - Replace pre-linked ExecutionChain objects with flat DiscoveredEntities + EdgeResolver. Connectors discover entities independently and resolve cross-entity relationships in an explicit step.
ADR-005: Platform-Only Finding Generation - All detection/finding logic lives in the platform evaluator. Connectors are pure discovery + classification pipelines. Connector-side detectors (detectors.py) removed.
ADR-015: Python as Connector SDK Language - Python for all connectors in sv0-connectors. Superior API client coverage for enterprise systems (Entra ID, ServiceNow, Azure Foundry) and clean separation of concerns from the TypeScript platform.
Data Model
ADR-006: Entity Type Reclassification - Split autonomous_identity into 4 distinct types: identity (authenticates), automation (executes logic), connection (outbound config), credential (holds secrets). Reduces NHI count inflation 13-18x.
ADR-007: Execution Relationship Types - Add 4 new typed edges (CALLS, INVOKES, USES, AUTHENTICATES_AS) to model the execution chain across reclassified entity types. Deprecates AUTHENTICATES_VIA, narrows EXECUTES_ON.
ADR-008: Execution Chains Collection - New execution_chains MongoDB collection to persist automation chains as durable, listable entities. Chain identity anchored to entry point, composition fingerprint for change detection.
Export
ADR-009: OAA Export Projection (Deferred) - OAA is an export projection layer, not the internal data model. SecurityV0's model is a superset of OAA. Implementation deferred until customer need.
ADR-010: Workload Entity Type Rename - Rename entity_type: "automation" to "workload" to resolve naming collision with the broader "Automation Definition" product concept. Backward-compatible alias during migration.
UI / Visualization
ADR-011: ELK.js Graph Layout Engine - Replace Dagre with ELK.js for graph visualization. Dagre's single-column-per-rank limitation creates unusable layouts at 50+ nodes. ELK's layered algorithm with partitioning distributes same-rank nodes across sub-rows while preserving causal left-to-right ordering.
AWS Connector
ADR-014: AWS IAM Policy Entity Type - Introduce type="permission_set" as the 10th entity type to model AWS IAM Managed Policies, Permission Boundaries, and SCPs. Avoids semantic conflation with type="role" (Azure RBAC assignments, ServiceNow OAuth scopes). Requires materialiser changes before AWS connector Phase 1 ships.
ADR-015: AWS Source System Tenancy Scheme - Use aws_{service}:{account_id} (e.g., aws_lambda:123456789012) as the source_system for all AWS entities. Enables entity uniqueness across multi-account environments, structural cross-account path detection, and per-account rescan scheduling.
Deployment & Security
ADR-018: Deploy-Server Security Posture Before Managed-Platform Migration - Accept audit #392 docker-group risk on Hetzner VPS hosts as a time-limited, explicitly recorded tradeoff. Reverts the brittle sudoers-allowlist mitigation (sv0-platform PR #401) that kept breaking deploys and required human root SSH to repair. Defers structural fix to the upcoming managed-platform migration (ECS / ACI / equivalent).
Related Session Notes
Detailed analysis behind these decisions is archived in session-notes/ (not published in docs):
2026-01-22-mongodb-vs-neo4j-tradeoffs.md2026-01-27-collection-architecture-decision.md2026-02-02-apache-age-evaluation.md