Architecture Decision Records

Architecture Decision Records (ADRs) capture the reasoning behind significant technical decisions. They document the context, constraints, alternatives considered, and trade-offs that led to each choice.

TIP

ADRs are the highest-value documentation in a project. They prevent re-debating the same decisions and help new contributors (human or AI) understand why the codebase is shaped the way it is.

Active Decisions

ADR	Decision	Status
ADR-001	Support YAML and JSON for Pod Template Files	Accepted
ADR-002	Stateless Signed Session Cookies for Proxy Auth	Accepted
ADR-003	Peer Discovery for Session Key Sharing	Accepted
ADR-004	Three-Source Theme Merge with Built-In Fallback	Accepted
ADR-005	Session Cookie Coverage for All Endpoints	Accepted
ADR-006	Packaged UI Asset and Built-in Resource Resolution	Accepted
ADR-007	Schema-Driven Configuration & Unified Annotation Keys	Accepted
ADR-008	Managed-Only Pod Access Control	Accepted
ADR-009	Eager MCP Server Initialization with K8s Health Check	Accepted
ADR-010	Graceful ConfigMap Template Fallback	Accepted
ADR-011	UI BASE_URL Contract and Cookie Path Consistency	Accepted
ADR-012	Per-Session McpServer Factory Pattern	Accepted
ADR-013	Workspace App Authorization Support	Accepted
ADR-014	Hardened Administrator Access with Scope and Role Mapping	Accepted
ADR-015	Workspace View Consolidation, Safe Template Upgrades, and STDIO Auth Bypass	Accepted
ADR-016	Session Cookie Reconstitution Compatibility with Custom JSONPaths	Accepted
ADR-017	Unauthenticated Workspace Redirection Recovery	Accepted
ADR-018	Workspace Owner Association and Server Metadata Reporting	Accepted
ADR-019	Split-Network OIDC Issuer Alignment and Path-Scoped Cookie Routing	Accepted
ADR-020	Fine-Grained Role Permissions, Template Creator Tracking, and Workspace API Visibility	Accepted
ADR-021	Workspace API Annotations and Routing Proxy Visibility Controls	Accepted
ADR-022	Session Key Dependent Health Check Readiness	Accepted
ADR-023	Dynamic Cookie TTL Alignment, Stale Cookie Cleanup, and Singleflight Refresh Token Rotation Safety	Accepted

How to Read ADRs

Each ADR follows a standard structure:

• Status — Accepted, Proposed, Deprecated, or Superseded by ADR-XXX
• Context — The problem, constraints, and requirements
• Decision — What was decided and how it works
• Alternatives Considered — What other options were evaluated and why they were rejected
• Consequences — What follows from the decision (both positive and negative)

Relationship Map

• Blue: Authentication & session management chain
• Green: Template & theme system
• Amber: Access control & security