Skip to content

Design Principles

The Substrate platform is built on core engineering and architectural principles that ensure long-term maintainability, security, and scalability.

1. SOLID and DRY are Mandatory

  • Single Responsibility: Keep domain modules small and cohesive. Avoid "god" services, routers, or settings objects.
  • Open/Closed: New functionality should be added through extensions (like connectors or policy packs) without modifying the core system.
  • Interface Segregation: Use specific, typed contracts for inter-module communication.
  • Dependency Inversion: Shared logic belongs in reusable base classes, helper modules, or dependency providers.

2. API-First Development

  • OpenAPI as Master Contract: FastAPI-generated OpenAPI remains the source of truth for the entire platform.
  • Generated Frontend Types: UI types must always be generated from the backend OpenAPI output. No handwritten request/response shapes.
  • Contract Integrity: Any API change must update the backend route, the OpenAPI spec, the generated frontend types, and the corresponding tests.

3. Determinism for Governance

  • OPA over LLM: Governance enforcement (pass/fail) must be deterministic. All PR blocking and policy checks are executed via OPA/Rego.
  • Traceability: Developers must be able to trace a policy violation to a specific graph condition and an exact Rego clause.
  • Probabilistic Assistance: LLMs are used for explanation, reasoning, and synthesis (e.g., "Why is this blocked?"), but never for the enforcement decision itself.

4. Platform Modularity

  • Bounded Contexts: Modules like auth, iam, marketplace, governance, and connectors have explicit boundaries.
  • Service Extraction Readiness: The modular monolith is designed to be split into independent services (e.g., connector_runtime, policy_runtime) when scale requires it, without rewriting the API contracts.

5. Security and Identity Authority

  • Keycloak Centrality: Keycloak is the single authority for identity and credentials.
  • Backend-Owned Authorization: While Keycloak manages identity, the backend owns the final authorization truth and access context projection.
  • No Production Fallback: Production environments must not rely on local JSON users or fallback role logic.

6. Visual Source of Truth

  • Theme Consistency: ui/theme.md is the visual source of truth. All primitive components and global styles must align with the "Obsidian Atlas" design system.
  • No Theme Drift: Avoid parallel theme systems or duplicate Tailwind configurations.