Skip to content

SwisperStudio - Architecture Decision Records

Last Updated: 2026-06-03
Total ADRs: 11

Quick Reference

# Decision Impact Phase
001 Use MUI Instead of Tailwind 🟢 Frontend Phase 1
002 Database Separation Strategy 🔴 Architecture Overall
003 Two-Mode Configuration System 🟡 Backend Phase 4
004 Data-Driven Admin UI via SAP 🟡 Full Stack Phase 4
005 Graph-Level Auto-Instrumentation 🟢 SDK Phase 1
006 Build from Scratch vs Fork 🔴 Strategy Overall
007 Pragmatic Async Testing Strategy 🟢 Testing Overall
008 Phase 2 Architecture 🟡 Backend Phase 2
009 Prompt Architecture Simplification 🔴 Architecture Prompt Studio
010 MCP Trace Tools Reuse Route Handlers In-Process 🟡 Backend MCP Server
011 MCP OAuth RS — RFC 9728 Host-Root Bridge + Fail-Closed Dev Auth 🔴 Security MCP Server

Legend: - 🔴 Critical (affects entire system) - 🟡 Significant (affects major feature) - 🟢 Tactical (affects specific component)

By Category

Infrastructure & Data

Frontend

Backend

SDK & Integration

Strategy

Testing & Quality

Architecture & Design

Timeline

Nov 1, 2025
├── ADR-001: MUI vs Tailwind
├── ADR-002: Database Separation
├── ADR-003: Two-Mode Config
├── ADR-004: Data-Driven UI
├── ADR-005: Auto-Instrumentation
└── ADR-006: Build vs Fork

Nov 7, 2025
├── ADR-007: Async Testing Strategy
└── ADR-008: Phase 2 Architecture

Nov 12, 2025
└── ADR-009: Prompt Architecture Simplification ⭐

Jun 3, 2026
├── ADR-010: MCP Trace Tools Reuse Route Handlers In-Process ⭐
└── ADR-011: MCP OAuth Resource Server (security) ⭐

Future ADRs (Planned)

Decisions we'll make later: - Phase 2: State diff algorithm choice - Phase 2: LLM telemetry capture method - Phase 3: Graph layout algorithm - Phase 4: SAP versioning strategy - Phase 5: ClickHouse migration approach

How to Use ADRs

Before Starting a Phase

  1. Read relevant ADRs
  2. Understand context and rationale
  3. Follow implementation notes
  4. Validate decision is still correct

When Making New Decisions

  1. Check if ADR exists
  2. If yes, follow it
  3. If no, create new ADR
  4. Get approval before implementation

When Revisiting Decisions

  1. Review ADR
  2. Check validation metrics
  3. Update status if superseded
  4. Create new ADR if changing approach

Created By: Development Team
Maintained By: Lead Architect