Skip to main content

Architecture Decision Records (ADRs)

Architecture Decision Records document significant architectural choices made in Prism. Each ADR captures the problem context, decision rationale, alternatives considered, and consequences—creating a historical record of "why" behind the architecture.

Prism Architecture at 10,000 Meters​

Key architectural decisions:

  • ADR-001: Rust proxy for 10-100x performance over JVM
  • ADR-002: Client-originated configuration for self-service
  • ADR-003: Protobuf as single source of truth
  • ADR-005: Pluggable backend architecture

🎯 New to Prism? Start Here​

If you're exploring Prism's architecture, start with these foundational decisions:

  1. ADR-001: Rust for Proxy - Why Rust powers Prism's core
  2. ADR-003: Protobuf Single Source of Truth - Data modeling philosophy
  3. ADR-002: Client-Originated Configuration - How apps declare requirements
  4. ADR-005: Backend Plugin Architecture - Pluggable backend design

📚 Reading Paths by Intent​

Understanding the Core Architecture​

Learn the foundational decisions that shaped Prism:

Building Backend Plugins​

Decisions that affect plugin development:

Deploying and Operating Prism​

Operational decisions for platform engineers:

Setting Up Local Development​

Decisions that affect your dev environment:

🚀 What's New​

Recently Completed​

Framework-Less Web UI (ADR-061):

  • Go templates + HTMX replace React/Vue framework complexity
  • Zero build step, instant feedback, 87% smaller bundle sizes
  • Native Go HTTP server with embedded templates
  • D3.js + Mermaid.js for visualization without framework overhead

Podman Container Optimization (ADR-049):

  • Scratch-based containers achieving 87% size reduction (45MB → 6MB)
  • Daemonless, rootless containers for Mac/Linux
  • Three-tier testing strategy: in-process → Podman → optimized containers
  • Sub-1ms tests for 80% of development workflow

Up-and-Coming​

Massive-Scale Graph Infrastructure (In Planning):

  • 100B vertex distributed graph system (RFC-057 through RFC-061)
  • Multi-level indexing for sub-second queries (RFC-058)
  • Hot/cold storage tiers with 95% cost reduction (RFC-059)
  • Distributed Gremlin query execution (RFC-060)
  • Fine-grained vertex-level authorization (RFC-061)

Configuration Schema System (MEMO-082):

  • JSON Schema as source of truth preventing config drift
  • Automated generation of docs, validation, and examples
  • CI validation ensuring examples always match schemas

Unified Configuration Model (RFC-056):

  • Client-declared needs with automatic backend provisioning
  • Eliminates duplication across namespace/pattern/backend config
  • Smart defaults with override capability

📖 ADRs by Category​

🏛️ Foundation Decisions​

Core technology choices that define Prism's architecture:

🏗️ Architecture Patterns​

How Prism is structured and organized:

🔒 Security & Multi-Tenancy​

Authentication, authorization, and isolation:

🔧 Operations & Reliability​

How Prism runs in production:

🧪 Testing & Quality Assurance​

How we ensure code quality and correctness:

🛠️ Developer Tooling​

Tools and workflows for local development:

📚 Documentation & Process​

How we document and share knowledge:

🔄 ADR Status Meanings​

ADRs progress through these states:

  • Proposed → Under discussion, not yet decided
  • Accepted → Decision made and documented
  • Implemented → Decision implemented in code
  • Deprecated → No longer applicable
  • Superseded → Replaced by a newer ADR (with reference)

💡 Why ADRs Matter​

ADRs help teams:

  • Understand why certain decisions were made (prevents revisiting settled debates)
  • Evaluate alternatives that were considered (shows due diligence)
  • Learn from past decisions (builds institutional knowledge)
  • Onboard new team members to architectural philosophy (accelerates ramp-up)

📝 Contributing ADRs​

When making a significant architectural decision:

  1. Create a new ADR using the template: docs-cms/adr/000-template.md
  2. Number it sequentially (next available ADR-XXX number)
  3. Structure it with: Context, Decision, Rationale, Consequences
  4. Submit for review with the core team
  5. Update status as the decision progresses

What Deserves an ADR?​

Write an ADR when:

  • Choosing between technology alternatives (e.g., Rust vs Go)
  • Defining system-wide patterns (e.g., error handling)
  • Making security or compliance decisions
  • Establishing development workflows (e.g., testing strategy)
  • Selecting third-party tools/services

Don't write an ADR for:

  • Implementation details (use code comments)
  • Temporary workarounds (use TODOs)
  • Personal preferences (use code reviews)

🔗 Related Documentation​

  • RFCs - Detailed technical specifications for features
  • MEMOs - Implementation diagrams and visual documentation
  • Changelog - Recent documentation updates

Total ADRs: 50+ architectural decisions documented

Latest Updates: See the Changelog for recent ADRs