Skip to main content

Developer Onboarding Platform Overview

Date: 2026-02-09
Audience: Engineers new to SecurityV0 (backend, full-stack, data, platform)

Executive Summary​

SecurityV0 is a deterministic security platform focused on machine authority exposure: who (or what) can do what, across connected enterprise systems, and whether that access is justified and governed.

As a developer, think of the platform as a control-and-evidence engine:

  1. Ingest normalized authority data from connectors.
  2. Compare new state with previous state.
  3. Persist entities, versions, and events.
  4. Materialize access paths and blast-radius context.
  5. Evaluate deterministic finding rules.
  6. Produce explainable, auditable evidence artifacts.

The implementation goal is not “collect more logs.” It is to create a reliable control system that leadership and auditors can trust.

Two-Page Overview​

Page 1: Product and System Mental Model​

1. What SecurityV0 Actually Does​

At a business level, SecurityV0 continuously answers:

  • Which machine identities have meaningful authority?
  • Do they still have clear ownership?
  • Has access scope drifted?
  • Is granted access actually used?
  • Can we prove all of this with source-linked evidence?

At an engineering level, SecurityV0 turns connector output into a unified, queryable authority graph with historical versions and deterministic findings.

2. Core Design Principles (Do Not Violate)​

These principles are the backbone of implementation decisions:

  1. Deterministic: same inputs produce same findings.
  2. Read-only posture: platform does not mutate client source systems.
  3. Explainable outputs: findings must have walkable evidence.
  4. Temporal truth: authority state must be reconstructable over time.
  5. Tenant isolation: every read/write path is tenant-scoped.

If a change conflicts with any of these, escalate before merging.

3. End-to-End Runtime Flow (Current Target Model)​

When a sync payload arrives:

  1. Connector sends NormalizedGraph to platform ingestion.
  2. Platform normalizes and validates data contract.
  3. Graph is transformed into platform entities + execution evidence.
  4. Diff engine compares against persisted state.
  5. Changed entities are upserted; events are emitted.
  6. Historical versions are archived for temporal replay.
  7. Execution paths are materialized (including cross-system auth links).
  8. Findings evaluator processes changed scope.
  9. Evidence packs are assembled and stored.

Today, steps 1-7 are the active implementation focus. Evaluator/evidence full implementation is later-phase.

4. Collections You Should Recognize​

These collections are core to nearly all platform behaviors:

  • entities: current authority state
  • entity_versions: historical snapshots for temporal queries
  • events: change log and audit timeline
  • execution_evidence: observed behavior records
  • connector_syncs: sync lifecycle and metrics
  • sync_cursors: incremental sync progression
  • findings: deterministic control outcomes
  • evidence_packs: sealed explainability artifacts

5. Where to Start Reading in Docs​

If you are new, read in this order:

  1. architecture/00-overview.md (business and system shape)
  2. architecture/03-database.md (storage model and indexes)
  3. architecture/05-connectors.md (input contracts and normalizer semantics)
  4. architecture/04-api-layer.md (surface area and API behavior)
  5. architecture/research/2026-02-07-core-platform-implementation-plan.md (phase plan/status)

Page 2: Implementation Orientation for New Developers​

6. Codebase Map (sv0-platform)​

Use this practical map to navigate quickly:

  • src/api/: HTTP routes and middleware
  • src/ingestion/: normalization, transform, diff, path materialization
  • src/storage/: storage interface + Mongo adapter + schema/index management
  • src/workers/: async runtime and job handlers
  • src/domain/: core types and contracts
  • src/findings/: current findings store abstractions
  • test/: unit + integration suites
  • scripts/: setup/import helpers
  • ui/: thin validation UI

If you are debugging sync behavior, most relevant code is:

  • src/ingestion/*
  • src/workers/handlers/sync-ingestion.ts
  • src/storage/mongo/adapter.ts

7. Current Implementation Status (High-Level)​

Implemented (foundation + early pipeline):

  • API skeleton, tenant/auth middleware baseline, health/readiness
  • Mongo schema/index layer and CRUD adapters
  • Connector report ingestion bridge for mock findings flow
  • UI thin spike (dashboard/list/detail)
  • Sync ingestion pipeline components (transform, diff, path materialization, worker wiring)

In progress / next:

  • Full evaluator rule engine and finding lifecycle workflows
  • Evidence-pack generation and sealing pipeline
  • Full query DSL and advanced graph/temporal endpoints
  • Persistent findings path fully wired to Mongo everywhere
  • Production hardening and operational threshold automation

8. Local Developer Workflow (Day 1)​

Recommended workflow:

  1. Start Mongo locally (Docker Compose).
  2. Start API in dev mode.
  3. Import connector report fixture.
  4. Run tests (unit + integration).
  5. Start UI and validate data path end-to-end.

Typical commands:

cd sv0-platform
docker compose up -d
REQUIRE_AUTH=false npm run dev
npm run import:connector-report -- --tenant-id dev-tenant
npm test
npm run test:integration
cd ui && npm run dev

9. First-Week Developer Checklist​

Use this as practical onboarding:

  1. Run all local checks successfully (lint/typecheck/tests/build).
  2. Trace one full sync from ingest request to stored entities/events.
  3. Confirm you can explain one finding record and its evidence path.
  4. Read one ingestion integration test and one storage integration test in detail.
  5. Make one small change with tenant-scoped tests.
  6. Update docs and .ai-notes when behavior changes.

10. Common Mistakes to Avoid​

Most regressions come from a few patterns:

  1. Missing tenant filters in reads/writes.
  2. “Convenient” nondeterministic logic that breaks repeatability.
  3. Adding fields without updating schema/index/test expectations.
  4. Treating evidence as optional for critical finding logic.
  5. Forgetting that temporal correctness matters as much as current-state correctness.

11. What “Good” Looks Like for Contributions​

A solid platform change should include:

  1. Clear tenant-scoped behavior
  2. Deterministic output under repeated runs
  3. Tests covering normal + failure paths
  4. Updated docs for contracts/semantics
  5. Operational observability where behavior affects sync or evaluation

If you keep those five outcomes in mind, you will usually align with platform direction.

Next Action​

Status: adopted — shipped Onboarding narrative incorporated into AGENTS.md and runbooks. No further action required.