Architecture Review Board (ARB) Minutes

Template Overview

An Architecture Review Board (ARB) safeguards the long-term scalability, maintainability, and security posture of software systems. Engineering teams present proposed changes, architectural spikes, and protocol upgrades to senior staff engineers for thorough evaluation.

Without a rigorous written record of ARB discussions, engineering teams risk revisiting the same technical debates, overlooking critical edge cases, and drifting from agreed non-functional requirements.

This template provides an engineering-grade layout designed to capture technical context, alternative designs considered, non-functional requirement assessments, and binding technical verdicts.

Markdown Template Structure

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

---
title: "Architecture Review Board: [RFC/System Title]"
date: [YYYY-MM-DD]
proposal_author: "[[Author Name]]"
review_lead: "[[Lead Architect Name]]"
reviewers:
  - "[[Staff Engineer A]]"
  - "[[Staff Engineer B]]"
  - "[[Security Principal]]"
rfc_document: "[[RFC-0042 System Architecture]]"
adr_link: "[[ADR-0042]]"
verdict: [Approved | Approved with Conditions | Rejected | Needs Revision]
tags: [architecture, engineering, arb, systems]
---

# Architecture Review Board: [RFC/System Title] — [YYYY-MM-DD]

## 1. Architectural Proposal Overview
- **Core Problem:** Detailed technical summary of the bottleneck or requirement motivating this change.
- **Proposed Architecture:** High-level topology, new modules, and subsystem interactions.
- **Target SLA/NFRs:** Latency target, throughput, RAM footprint, disk I/O, security surface.

## 2. Technical Evaluation Matrix
| Evaluation Criterion | Assessment | Trade-Off / Risk | Mitigation |
| :--- | :--- | :--- | :--- |
| Computational Complexity | $O(N \log N)$ search | High CPU during re-indexing | Offload to background GCD queue |
| Memory Overhead | +45MB RSS | Risk of pressure on 8GB Macs | Mmap index file into virtual memory |
| Persistence & Crash Safety | SQLite WAL mode | Potential DB lock on abrupt kill | Strict transactional write-ahead logging |
| Security & Blast Radius | Zero network egress | Potential privilege escalation | Sandbox within macOS App Sandbox |

## 3. Considered Alternatives & Rejection Rationales
### Alternative A: Custom In-Memory Radix Tree
- **Rejection Reason:** High engineering maintenance burden and prolonged crash recovery rebuild time.

### Alternative B: External Client-Server Daemon
- **Rejection Reason:** Violates local single-binary architecture and complicates silent app auto-updates.

## 4. Final Verdict & Architectural Stipulations
> [!IMPORTANT] Board Verdict: Approved with Conditions
> The proposal is approved subject to completing the following engineering verifications:
> 1. Formal benchmark verifying zero frame drops during CoreAudio capture on Apple Silicon.
> 2. Proof of crash recovery under SIGKILL within 500ms.

Filled Real-World Example

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

---
title: "ARB: Local Full-Text Search Engine via SQLite FTS5"
date: 2026-10-06
proposal_author: "[[Alex Rivera]]"
review_lead: "[[Elena Rostova]]"
reviewers:
  - "[[Sophia Wu]] (Security)"
  - "[[David Park]] (Product)"
rfc_document: "[[RFC-0038 Local Search Engine]]"
adr_link: "[[ADR-0038]]"
verdict: Approved
tags: [architecture, engineering, arb, search]
---

# ARB: Local Full-Text Search Engine via SQLite FTS5 — October 6, 2026

## 1. Architectural Context
Alex Rivera presented the technical proposal to migrate note indexing from a bespoke flat-file scanner to an embedded SQLite FTS5 engine with custom unicode tokenization.

## 2. Key Deliberations
- **Index Size:** Benchmark showed an SQLite index adds approximately 8% storage overhead relative to raw Markdown vault size. Accepted as an optimal trade-off.
- **Search Latency:** P95 response time dropped from 420ms to 4.2ms across a 15,000-note test vault.
- **Concurrency:** Confirmed WAL mode enables concurrent background indexing while the user types in the editor.

## 3. Architecture Stipulations
> [!IMPORTANT] Final Board Approval
> Unanimously approved. Must implement automatic vacuum on vault closure and enforce SQLite integrity check on app startup.

## 4. Action Items
- [x] [[Alex Rivera]] Commit FTS5 schema migration script.
- [ ] [[Sophia Wu]] Verify App Sandbox entitlement for temporary SQLite shared memory files.

When to Use and When to Avoid

When to Use

• Use during formal technical architecture evaluations and system design reviews.
• Use when introducing new infrastructure dependencies, storage engines, or security primitives.
• Use to create an auditable historical trail before committing an Architecture Decision Record (ADR).

When to Avoid

• Avoid using for trivial refactorings or routine bug fixes that do not alter system topology.
• Avoid using for high-level business strategy or product feature marketing sessions.

On-Device AI Integration

Use this prompt in Oyma to synthesize your Architecture Review Board recording:

Analyze the attached engineering review transcript:
1. Summarize the core technical problem and system architectural changes proposed.
2. Outline the trade-offs discussed regarding memory, latency, and crash safety.
3. Document rejected alternative architectures and the technical rationale for rejection.
4. Record the final board verdict and all mandatory pre-merge conditions.
Format using clean Markdown tables and architectural callout blocks.

Your technical designs and architectural secrets stay strictly on your local device.