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.

🎯 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:

📖 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