Skip to main content

Platform and Connector Architecture Cross-Check

Executive Summary​

The current architecture set mixes two different snapshots of SecurityV0:

  • Current-state docs: the processing pipeline, authority path model, and drift evaluator docs line up well with the live codebase.
  • Older-state docs: the overview, API, UI, and Entra-ServiceNow reference docs still describe an earlier pre-W1 / pre-authority-path / pre-Azure-Foundry version of the system.

The most important outcome of this review is:

  1. The documentation is missing shipped capabilities in the core overview/API/database/UI narratives.
  2. Some architecture docs are ahead of implementation and should be labelled more clearly as planned or deferred.
  3. Azure Foundry now needs a first-class architecture/reference document comparable to the Entra-ServiceNow connector doc.

This was a static repo cross-check only. I reviewed documentation and source code, but I did not run live scans, hit API endpoints, or compare against a running tenant.

Scope​

Documentation reviewed​

  • docs/architecture/00-overview.md
  • docs/architecture/01-data-model.md
  • docs/architecture/02-processing-pipeline.md
  • docs/architecture/03-database.md
  • docs/architecture/04-api-layer.md
  • docs/architecture/05-connectors.md
  • docs/architecture/06-scim-oaa-integration.md
  • docs/architecture/07-ui-reporting.md
  • docs/architecture/08-reference-impl-entra-servicenow.md
  • docs/architecture/09-drift-evaluator-framework.md
  • docs/architecture/10-access-paths.md
  • docs/architecture/11-platform-mental-model.md
  • docs/architecture/decisions/adr-015-connector-sdk-language.md

Implementation cross-checked​

  • sv0-platform/src/api/routes/*
  • sv0-platform/src/workers/handlers/*
  • sv0-platform/src/ingestion/*
  • sv0-platform/src/storage/mongo/{collections,schema}.ts
  • sv0-platform/src/services/{posture-service,risk-cluster-service}.ts
  • sv0-platform/ui/src/{App.tsx,components/graph/*,pages/*}
  • sv0-connectors/integrations/entra-servicenow/*
  • sv0-connectors/integrations/azure-foundry/*
  • sv0-connectors/shared/{sv0_common,sv0_azure}/*

Current Implementation Baseline​

The repo currently implements:

  • A 3-job platform pipeline: sync_ingestion -> evaluate_findings -> build_evidence_pack
  • Authority path materialization and path-level findings
  • Posture snapshots and risk clusters
  • Execution chains
  • Execution evidence storage and API access
  • A React UI centered on Overview, Risk Clusters, Authority Paths, Identities, Data Domains, and Graph Explorer
  • Two live Python connector packages:
    • entra-servicenow
    • azure-foundry

The repo does not currently implement:

  • SCIM endpoints
  • OAA export endpoints
  • POST /api/v1/query
  • Manual POST /api/v1/syncs
  • Phase-2 execution-chain history collections (execution_chain_versions, execution_chain_events)

Cross-Check by Document​

DocumentAssessmentNotes
00-overview.mdPartially staleHigh-level architecture is still directionally right, but it omits current path/posture structures and still presents SCIM/OAA and a standalone query service as if they are active platform layers.
01-data-model.mdMostly alignedThe 9-entity model, workload rename, and relationship taxonomy match the implementation well. Only minor connector-specific examples need tightening.
02-processing-pipeline.mdStrongly alignedThis is one of the best current-state docs. The worker handlers match the documented 3-job flow, circuit breakers, authority path materialization, and posture snapshot capture.
03-database.mdPartially staleBaseline, sync, evidence, and chain collections are documented, but current shipped collections authority_paths and posture_snapshots are not covered, while phase-2 chain history collections are described despite not being created.
04-api-layer.mdStaleCore entity/findings/path/sync/chain coverage is decent, but authority-path, execution-evidence, and risk-cluster detail endpoints are missing, and the W1 posture/exposure contracts no longer match the live routes.
05-connectors.mdPartially staleThe NormalizedGraph contract still matches the platform boundary, but the connector inventory, roadmap, and some lifecycle language do not reflect the current Python cross-system connector repo.
06-scim-oaa-integration.mdAccurate as roadmapThis doc correctly labels SCIM as planned and OAA as deferred. The implementation gap is expected.
07-ui-reporting.mdHeavily staleThe live UI no longer matches the documented route structure, graph layout engine, execution-chain status, or automations-centric navigation model.
08-reference-impl-entra-servicenow.mdHeavily staleThe connector has moved to the workload/connection/credential model, but the doc still describes older identity-centric mappings and older evidence assumptions.
09-drift-evaluator-framework.mdMostly alignedThe documented drift rule family still maps cleanly to the evaluator code and remediation service.
10-access-paths.mdStrongly alignedThis is the clearest current-state doc for the W1.1 architecture and API surface.
11-platform-mental-model.mdUseful but partialGood bridge doc for current platform thinking, but some Azure Foundry mappings no longer match the actual connector transformer output.

Highest-Priority Documentation Gaps​

1. The overview no longer matches the real system boundary​

00-overview.md still describes:

  • a connector layer made of single-source connectors like Entra ID Connector and ServiceNow Connector
  • a live interoperability layer with OAA + SCIM
  • a standalone query service
  • an outdated MongoDB collection list

The current implementation is different:

  • the connector repo ships paired/cross-system Python connectors (entra-servicenow, azure-foundry)
  • SCIM/OAA are not implemented
  • the query module is still a placeholder
  • MongoDB now includes shipped collections such as authority_paths and posture_snapshots

2. The API reference is missing important shipped endpoints​

04-api-layer.md does not currently document these implemented routes:

  • GET /api/v1/entities/:id/execution-evidence
  • GET /api/v1/authority-paths
  • GET /api/v1/authority-paths/:id
  • GET /api/v1/authority-paths/:id/findings
  • GET /api/v1/authority-paths/:id/remediation
  • GET /api/v1/risk-clusters/:key/authority-paths
  • GET /api/v1/risk-clusters/:key/remediation
  • GET /api/v1/execution-chains/:id/entities

It also documents older W1 response contracts. The live implementation is now more path-centric:

  • posture summary returns active_paths, dormant_paths, execution totals, identity/workload counts, and delta metrics
  • risk clusters return path-based aggregates
  • exposures are workload-grain summaries, not one row per authority path

3. The database doc misses shipped collections​

03-database.md needs to be updated for the actual current schema:

  • Missing from doc, present in code:
    • authority_paths
    • posture_snapshots
  • Documented as phase 2, absent from schema manager:
    • execution_chain_versions
    • execution_chain_events

4. The UI architecture doc is describing the previous UI generation​

07-ui-reporting.md is the most visibly stale core doc.

Major mismatches:

  • The live nav is Overview / Risk Clusters / Authority Paths / Identities / Data Domains / Graph Explorer
  • The app now has top-level routes for:
    • /clusters
    • /authority-paths
    • /chains
  • /automations is not the primary navigation model anymore
  • execution chains are implemented
  • the graph layout engine is ELK, not Dagre
  • workload, connection, and execution_evidence graph nodes are implemented

5. The Entra-ServiceNow reference doc predates the current connector shape​

08-reference-impl-entra-servicenow.md still reflects an older mapping model.

Current connector behavior that needs to be reflected:

  • ServiceNow automations are emitted as workload nodes
  • OAuth artifacts are emitted as credential nodes
  • cross-system linkage uses USES + AUTHENTICATES_AS + RUNS_AS patterns
  • execution evidence comes from:
    • Entra sign-in logs
    • sys_flow_context
    • sys_trigger
  • the connector now performs much richer workload discovery than the doc suggests

6. Azure Foundry has no equivalent reference architecture doc​

This is the clearest “missing document” in the architecture set.

We now have a real connector implementation for azure-foundry, but there is no numbered architecture doc equivalent to 08-reference-impl-entra-servicenow.md covering:

  • discovered entity/edge mappings
  • Foundry project/resource modeling
  • managed identity + ARM role correlation
  • thread-proxy execution evidence limitations
  • connection/tool classification
  • platform ingestion assumptions

The closest current documentation is split between:

  • 11-platform-mental-model.md
  • session notes
  • connector README files

That is not enough for a canonical architecture reference.

Docs Ahead of Implementation​

These are cases where the architecture docs describe a capability that is still planned or deferred in code:

CapabilityDoc stateCode state
SCIM APIPlanned in 06-scim-oaa-integration.md, implied too strongly in 00-overview.mdNo routes implemented
OAA exportDeferred in 06-scim-oaa-integration.md, implied too strongly in 00-overview.mdNo routes implemented
Structured query API (POST /api/v1/query)Planned in 04-api-layer.mdPlaceholder only
Manual sync trigger (POST /api/v1/syncs)Planned in 04-api-layer.md / 07-ui-reporting.mdNo route implemented
Query Service as a standalone platform subsystemDescribed in 00-overview.mdsrc/query/index.ts is still a placeholder
execution_chain_versions / execution_chain_eventsDocumented in 03-database.md as phase 2Not created by the schema manager

Best Current Sources of Truth​

If someone needs the most reliable current-state docs today, use these first:

  • 02-processing-pipeline.md for ingestion/evaluation flow
  • 10-access-paths.md for W1.1 path model and API
  • 09-drift-evaluator-framework.md for drift rules
  • 11-platform-mental-model.md for the connector-to-platform bridge

For exact behavior, the most authoritative implementation files are:

  • sv0-platform/src/api/routes/*
  • sv0-platform/src/workers/handlers/*
  • sv0-platform/src/storage/mongo/{collections,schema}.ts
  • sv0-platform/src/services/{posture-service,risk-cluster-service}.ts
  • sv0-platform/ui/src/App.tsx
  • sv0-connectors/integrations/entra-servicenow/src/entra_servicenow/core/transformer.py
  • sv0-connectors/integrations/azure-foundry/src/azure_foundry/core/transformer.py

Priority 1​

  1. 04-api-layer.md
  2. 07-ui-reporting.md
  3. 00-overview.md

Priority 2​

  1. 03-database.md
  2. 08-reference-impl-entra-servicenow.md

Priority 3​

  1. Add 12-reference-impl-azure-foundry.md (or equivalent)
  2. Tighten 11-platform-mental-model.md Azure Foundry mapping details
  3. Resolve outdated open questions in 05-connectors.md

Suggested Next Step​

The most efficient next pass would be:

  1. Refresh 04-api-layer.md and 07-ui-reporting.md to match shipped behavior.
  2. Update 00-overview.md and 03-database.md so the top-level architecture story reflects authority paths, posture snapshots, and the actual connector inventory.
  3. Rewrite 08-reference-impl-entra-servicenow.md and add an Azure Foundry companion doc.

That would bring the core architecture set back into alignment without needing a full-documentation rewrite.