Architecture Decision Record (ADR)

Template Overview

Software architectures evolve over years. When senior engineers depart an organization without documenting why critical technical choices were made, new team members inevitably question past designs: “Why are we using SQLite instead of an in-memory tree?” or “Why did we choose ScreenCaptureKit over virtual audio drivers?”

Without written Architecture Decision Records (ADRs), teams suffer from architectural amnesia, wasting weeks revisiting the same settled debates or accidentally re-introducing flaws that were previously solved.

This template provides an industry-standard ADR format based on Michael Nygard’s framework: title, status, technical context, decision taken, alternative options rejected, and comprehensive positive and negative consequences.

Markdown Template Structure

Copy the block below or click Download .md File to add this template directly to your personal vault:

---
title: "ADR-0044: [Short Architectural Decision Title]"
date: [YYYY-MM-DD]
adr_number: 44
authors:
  - "[[Lead Systems Engineer]]"
  - "[[Chief Architect]]"
status: [Proposed | Accepted | Superseded | Deprecated]
superseded_by: ""
tags: [adr, architecture, engineering, decisions, systems]
---

# ADR-0044: [Short Architectural Decision Title] — [YYYY-MM-DD]

## 1. Technical Context & Problem Statement
- **Context:** The macOS desktop application requires real-time capturing of both system output audio (Zoom/Meet calls) and user microphone audio without requiring users to install third-party kernel extensions or virtual audio devices.
- **Problem:** Legacy CoreAudio aggregate devices introduce high installation friction, require administrator privileges, and fail to pass modern macOS App Sandbox notarization.
- **Driver:** We need a low-latency, zero-driver capture pipeline that runs entirely in user-space with native Apple Silicon hardware acceleration.

## 2. Decision Taken
> [!IMPORTANT] Architectural Decision
> We will adopt Apple's native **ScreenCaptureKit** audio tap APIs for all desktop meeting recording on macOS Sonoma and newer. Audio streams will be ingested directly into a 1024-sample circular ring buffer and dispatched to on-device Whisper models via Apple Silicon Unified Memory.

## 3. Alternative Architectures Considered & Rejected
### Alternative A: Virtual Audio Device Kernel Extension (kext)
- **Rejection Reason:** Modern macOS severely restricts kernel extensions, requiring users to reboot into Recovery Mode and lower System Integrity Protection (SIP). Unacceptable user onboarding friction.

### Alternative B: Third-Party Virtual Audio Driver (HAL Plugin)
- **Rejection Reason:** Introduces fragile third-party binary dependencies that frequently break during major macOS operating system upgrades.

### Alternative C: Cloud-Based Headless Meeting Bot
- **Rejection Reason:** Violates our fundamental architectural principle of 100% on-device data sovereignty.

## 4. Consequences & Trade-Offs
### Positive Consequences
- Zero kernel extensions or virtual drivers required; seamless user onboarding with standard macOS permission prompt.
- Hardware-accelerated resampling handled automatically by macOS audio subsystems with zero CPU penalty.
- Passable through strict Apple Developer ID signing and App Store / notarization sandboxing.

### Negative Consequences & Mitigations
- **OS Version Constraint:** ScreenCaptureKit audio taps require macOS 13 (Ventura) or newer; drops support for legacy Intel Macs running older OS releases (Accepted trade-off).
- **Permission Sensitivity:** If the user revokes Screen Recording permissions while an active session is in flight, the audio stream terminates abruptly. Mitigated by registering dedicated delegate failure handlers.

## 5. Compliance & Verification
- Benchmark verified: Zero frame drops over 4-hour continuous recording stress tests on base M1 hardware.
- Linked Specs: [[RFC-Audio-Pipeline]], [[PRD-Desktop-Recorder]].

Filled Real-World Example

Here is a realistic example demonstrating how this template captures actual deliberations:

---
title: "ADR-0038: Local Search Engine via SQLite FTS5"
date: 2026-10-06
adr_number: 38
status: Accepted
tags: [adr, architecture]
---

# ADR-0038: Local Search Engine via SQLite FTS5 — October 6, 2026

## 1. Context
Markdown note search was slow across 15,000+ files.

## 2. Decision
Adopt embedded SQLite FTS5 with custom WAL mode. P95 latency reduced to 4.2ms.

## 3. Status
Accepted. Code merged in PR #418.

When to Use and When to Avoid

When to Use

• Use whenever making significant, irreversible architectural decisions in software systems.
• Use to preserve historical technical context, trade-offs, and alternative architectures rejected.
• Use to prevent architectural drift and eliminate repeated debates across engineering teams.

When to Avoid

• Avoid using for routine code refactoring or trivial library version bumps.
• Avoid using for marketing or non-technical business proposals.

On-Device AI Integration

Capture Architecture Decision Records with Oyma on macOS:

Analyze the engineering architecture discussion transcript:
1. Synthesize the technical context, framing problem, and core architectural drivers.
2. Clearly articulate the exact architectural decision taken in an executive callout block.
3. Detail candidate alternatives considered and the technical rationales for their rejection.
4. Document the positive consequences and negative trade-offs with explicit engineering mitigations.
Output in standard Michael Nygard ADR CommonMark format.

Your sensitive software architecture specifications and engineering decisions remain strictly on your Mac.