Skip to content

System Overview

Substrate is an "active computable governance layer" — an architectural governance and institutional memory platform built on a unified multimodal knowledge base (UMKB). It enforces architectural policies, detects structural drift, preserves organizational memory, and provides natural language querying of system architecture.

Executive Summary

Substrate is designed to provide structural integrity for autonomous architectural governance. It bridges the gap between declared architecture and observed reality by maintaining a temporal graph of the entire software delivery lifecycle.

Current Stack

Layer Technology
Frontend React 19 + TypeScript + Vite + Custom CSS (Obsidian Atlas theme)
Backend FastAPI (Python 3.12) + Modular Domain Services
Auth Keycloak 26.5 + OIDC + GitHub OAuth
Relational DB PostgreSQL 16 + pgvector + pg_partman
Graph DB Neo4j 2026.02.3
Messaging NATS JetStream
Inference Local vLLM endpoints (no external API dependencies)

Persona Analysis

Substrate serves multiple personas across the engineering organization:

  • Developers: Receive structural confidence through PR violation blocking and blast radius analysis.
  • Tech Leads / Architects: Enforce authority and run pre-commitment simulations.
  • DevOps / SRE: Close the gap between IaC and runtime with temporal graph diffs.
  • Product Owners / Managers: Understand service impact of epics and roadmap feasibility.
  • Security Engineers: Analyze CVE blast radius and detect "ghost services."

Backend Architecture

The Substrate backend is a FastAPI application built with an async-first, modular architecture. It follows domain-driven design principles with clear separation between infrastructure, domain logic, and API layers.

Core Principles

  1. Async-First I/O: All database and external service calls are async (PostgreSQL, Neo4j, Redis, HTTP).
  2. Modular Organization: Each feature is a self-contained module with Router, Service, Repository, and Schemas.
  3. Dual Database Strategy: PostgreSQL for relational data (users, orgs, audit); Neo4j for graph data (topology, dependencies).
  4. Deterministic Policy Enforcement: All governance decisions use OPA/Rego, never LLM-based for enforcement.

Application Layers

┌─────────────────────────────────────────────────────────────┐
│                         API Layer                           │
│  (Routers: FastAPI endpoints, request validation, auth)    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Service Layer                          │
│  (Business logic, orchestration, domain rules)             │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Repository Layer                        │
│  (Data access: PostgreSQL, Neo4j, Redis)                   │
└─────────────────────────────────────────────────────────────┘

Frontend Architecture

The frontend is a React SPA focused on visualization and governance interaction.

Key Characteristics

  • Custom CSS Design System: Uses the "Obsidian Atlas" theme (Fraunces + Instrument Sans + JetBrains Mono). No Tailwind (except for specific primitive utilities).
  • OIDC Integration: Authenticates directly against Keycloak via react-oidc-context.
  • Generated API Types: All frontend types are generated from the backend OpenAPI contract.
  • Perspective-Based UI: UI adapts based on the user's role (Executive, Architecture, Engineering, etc.).

Infrastructure & Messaging

Substrate runs as a orchestrated set of services:

  • Keycloak: Single authority for identity and authentication.
  • NATS: Event bus for inter-module communication and notification streaming.
  • OPA: Sidecar service for deterministic policy evaluation.
  • vLLM: Local inference for embeddings, reranking, and natural language reasoning.

Current Development Status

The platform is currently in Phase 0 (Baseline): - Core modular architecture is established. - Auth foundation (Keycloak) is working. - Multi-database connectivity is stable. - The 16-phase implementation plan is active, focusing next on backend cleanup and OpenAPI contract discipline.