Private architecture review notes on Mac

Architecture reviews and technical RFC (Request for Comments) evaluation boards represent the most consequential technical decision-making sessions in a software organization. During these meetings, principal engineers, software architects, and technical leads debate distributed system designs, consensus protocols, database partitioning schemas, and security boundaries that will dictate system performance and operational scalability for years to come.

Yet capturing high-stakes architecture reviews is notoriously difficult:

Participating architects must actively interrogate failure modes, challenge scaling assumptions, and debate algorithmic trade-offs. Asking them to simultaneously transcribe verbal debates into written documentation results in superficial notes that miss critical nuance. Conversely, inviting a third-party cloud AI transcription bot into the architecture review poses serious intellectual property and security risks: engineers routinely discuss unpatched system bottlenecks, internal network topologies, and proprietary architectural designs that should never leave local infrastructure.

Oyma resolves this architecture documentation challenge on macOS. Leveraging Apple’s native ScreenCaptureKit framework, Oyma captures the audio of your architecture review board silently, without injecting an automated bot into your Zoom, Google Meet, or Slack call. Transcriptions execute 100% on-device on Apple Silicon using local Whisper models, converting spoken technical debate into rigorous Architecture Decision Records (ADRs) stored directly in your local Markdown vault.

The documentation crisis in software architecture

Architecture decisions endure long after the engineers who made them have changed roles, making rigorous historical context vital:

1. Lost technical trade-off rationale: Written RFCs usually document the winning proposal, but fail to record why viable alternatives were rejected. Years later, new engineers often re-introduce previously rejected approaches because the original verbal trade-off debate was never documented.
2. Administrative ADR drafting fatigue: Drafting formal Architecture Decision Records (ADRs) requires hours of tedious post-meeting documentation that busy staff engineers routinely postpone, resulting in documentation drift across distributed services.
3. The distraction of virtual recording bots: Architecture reviews require intense, candid intellectual debate where engineers must feel safe admitting that their original proposal has flaws. When a recording bot sits in the participant list, engineers become hesitant to express technical doubt.
4. Proprietary system topology exposure: Architecture sessions delve into confidential software designs, encryption schemes, and infrastructure perimeters. Streaming this audio to cloud transcription platforms violates fundamental enterprise infosec standards.

The staff engineer’s architecture vault in plain Markdown

Oyma organizes technical architecture records directly into an interconnected, sovereign Markdown repository:

vault/
├── architecture/
│   ├── adr/
│   │   ├── ADR-0021-event-sourcing-storage.md
│   │   ├── ADR-0022-raft-consensus-engine.md
│   │   └── ADR-0023-multi-tenant-partitioning.md
│   └── rfc/
│       ├── RFC-108-graphql-federation.md
│       └── RFC-109-ebpf-network-tracing.md
└── services/
    ├── ingest-pipeline.md
    └── consensus-coordinator.md

By connecting ADRs to service documentation and incident retrospectives via [[wikilinks]], teams build a living, verifiable knowledge graph of technical decisions.

Sample on-device Architecture Decision Record (ADR) note

Here is an authentic Markdown artifact generated during an architecture review board session in Oyma:

---
adrId: ADR-0022
title: "Adoption of Raft Consensus for Metadata Coordination"
status: Accepted
date: 2026-10-09
reviewLead: "[[team/marcus-vance]]"
participants:
  - "Elena Rostova (Principal Distributed Systems Architect)"
  - "Dave Kaufman (Staff Infrastructure Engineer)"
  - "Alex Rivera (Senior Platform Engineer)"
tags:
  - architecture-review
  - adr
  - distributed-systems
---

# Architecture Decision Record: ADR-0022 (Raft Consensus Engine)

## 1. Context & Problem Statement
Our distributed ingest coordinator currently relies on an external ZooKeeper cluster for leader election and partition assignment. Under high network jitter across availability zones, ZooKeeper session expirations frequently cause coordinator thrashing and intermittent partition ownership re-elections. We must determine whether to maintain external ZooKeeper or embed a consensus protocol directly within the coordinator binary.

## 2. Considered Architectural Alternatives
1. **Option A: Maintain External ZooKeeper 3.9 Cluster** (Current baseline).
2. **Option B: Embed HashiCorp Raft (Go) Engine Directly into Coordinator**.
3. **Option C: Migrate to Apache Kafka Metadata Quorum (KRaft)**.

## 3. Trade-Off Evaluation & Debate Synthesis
| Evaluation Axis | Option A: ZooKeeper 3.9 | Option B: Embedded Raft | Option C: Apache KRaft |
| :--- | :--- | :--- | :--- |
| Operational Complexity | High (separate JVM stateful set to manage) | Minimal (single compiled binary) | Moderate (tied to Kafka cluster upgrades) |
| Failover Latency | 3,500ms p99 on session timeout | 450ms p99 on heartbeat loss | 1,200ms p99 |
| Operational Footprint | 3 dedicated r6i.xlarge instances | In-process memory (negligible) | Tied to existing broker nodes |
| Cross-AZ Split Brain Risk | Well-understood quorum mechanics | Proven mathematical safety | Dependent on Kafka broker stability |

## 4. Decision Consensus & Technical Rationale
The Architecture Review Board unanimously selected **Option B (Embedded Raft Engine)**:
- **Primary Driver:** Embedding the consensus engine eliminates the external JVM operational dependency, reducing deployment complexity across staging and air-gapped customer environments.
- **Failover Performance:** In-process Raft heartbeats provide sub-second leader election recovery during network partitions, resolving the coordinator thrashing observed in [[incidents/2026/INC-842-redis-cluster-exhaustion]].

## 5. Rejected Alternatives & Documented Reasons
- **Rejection of Option A (ZooKeeper):** The team concluded that JVM garbage collection pauses on ZooKeeper nodes were the root trigger of false-positive leader failovers during peak ingestion spikes.
- **Rejection of Option C (KRaft):** Tying coordinator metadata directly to Kafka brokers creates a circular dependency when Kafka itself experiences partition degradation.

## 6. Implementation Milestones & Commitments
| Milestone | Description | Assignee | Target Date |
| :--- | :--- | :--- | :--- |
| Prototype Validation | Benchmark embedded Raft under 20% simulated packet loss | Alex Rivera | 2026-10-18 |
| Migration RFC | Draft zero-downtime metadata migration strategy from ZooKeeper | Marcus Vance | 2026-10-25 |
| Canary Cutover | Deploy embedded Raft to staging cluster and execute chaos suites | Dave Kaufman | 2026-11-04 |

The architecture review lifecycle: from design debate to immutable ADR

Codifying verbal RFC deliberations into durable Architecture Decision Records follows an automated engineering discipline:

1. Zero-interruption bridge audio capture

When an architecture review board convenes across Slack Huddles, Zoom, or Teams, trigger Oyma‘s native audio hook. Operating at the core macOS ScreenCaptureKit layer, audio records unobtrusively. Without an automated attendee bot announcing itself, staff engineers debate distributed consensus, partition recovery, and protocol compromises with total candor.

2. High-precision hardware ASR on Apple Silicon

Spoken technical dialogue—including distributed algorithms, database engine flags, and container orchestrator parameters—undergoes immediate speech recognition via local Whisper models. Processing executes 100% locally on your Mac’s hardware with zero network transmission.

3. Extracting consensus records and rejected alternatives

Once the architectural debate concludes, apply Oyma‘s ADR extraction prompt via local Ollama inference or your private API key. The parser structures:

• Boundary constraints and fundamental problem context
• Evaluated architectural options and explicit rationales for rejected designs
• Comparative trade-off matrix evaluating latency, failure resilience, and maintenance overhead
• Approved technical consensus and subsequent implementation roadmap

4. Committing ADR documents into version control

The structured Markdown file saves into your repository’s local docs/adr/ directory. Through bidirectional wikilinks, decisions map to service runbooks and incident retrospectives in your Obsidian knowledge graph.

Protecting mission-critical infrastructure intellectual property

System architecture documentation represents an organization’s most guarded technical intellectual property:

• Infosec perimeter safety: Architecture reviews discuss firewall topologies, cryptographic key rotation schedules, and internal authentication protocols. Keeping these discussions strictly on local encrypted drives protects your core assets.
• Verifiable audit history: Unlike ephemeral cloud wiki pages that are casually overwritten without context, local Markdown ADRs committed to git provide an immutable, verifiable record of engineering evolution.
• Air-gapped operation: With Local-only mode, architects can synthesize RFC notes, explore system dependencies, and navigate complex technical graphs completely offline.

To learn more about our local audio architecture, read about botless meeting recording, explore spreadsheet-like Markdown tables, or review our zero-leak privacy architecture.