Architecture Decision Records
All significant architecture decisions are recorded as ADRs. See the detailed documents below for rationale, alternatives, and trade-offs.
Current ADRs
| ID | Title | Status | Decided | Impact |
|---|---|---|---|---|
| 0001 | Rust core with three native GUIs (SwiftUI, WinUI 3, Qt 6) | Accepted | 2026-04-18 | FFI approach, platform coverage |
| 0002 | oMlx fat fork for SSD-paged KV cache on macOS | Accepted | 2026-04-18 | Inference backend, performance baseline |
| 0003 | Axum + mTLS for fleet wire (not gRPC) | Accepted | 2026-04-18 | Fleet transport, scalability ceiling |
| 0004 | Math core dispatch per AttentionKind | Accepted | 2026-04-18 | Accuracy, architecture support |
| 0005 | Shared crate reuse across Phenotype org | Accepted | 2026-04-18 | Code organization, dependency strategy |
| 0007 | Raw C FFI over UniFFI (WinUI/Qt fallback) | Accepted | 2026-04-18 | Windows/Linux FFI approach |
Decision Process
Each ADR includes:
- Context: Problem statement and constraints
- Decision: What was chosen and why
- Rationale: Trade-offs and alternatives considered
- Consequences: Impacts on the system and team
ADR Index by Category
Runtime & Inference
Architecture Patterns
- ADR-0001: Rust core with three native GUIs
- ADR-0004: Math core dispatch per AttentionKind
- ADR-0005: Shared crate reuse
Transport & Communication
FFI & Language Bindings
Future ADRs
Planned decisions for upcoming phases:
- ADR-0006: Query language for fleet dispatch (planned)
- ADR-0008: Cost model and spot pricing integration (planned)
- ADR-0009: Offline-first sync strategy for fleet nodes (planned)