Technical RFC Proposal Framework

Template Overview

Major architectural decisions should not be made in private silos. The Request for Comments (RFC) process invites broad peer review, exposes unforeseen technical trade-offs, and documents design rationale for future engineers. The Technical RFC Proposal Framework organizes motivation, detailed design, alternative approaches, and security implications in structured Markdown.

Markdown Template Structure

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

---
title: "RFC: [Concise Feature / Architecture Name]"
date_proposed: [YYYY-MM-DD]
author: "[[Staff Systems Engineer]]"
rfc_number: "RFC-2026-042"
status: "Draft / Under Review / Accepted / Rejected"
target_implementation_sprint: "2026-Q4-Sprint-3"
tags: [rfc, engineering, architecture, systems-design, proposal]
---

# Technical RFC Proposal Draft — [Feature / Architecture Name]

## 1. Summary & Motivation
- **Executive Summary:** This proposal specifies the transition of our local note indexing engine from flat directory traversal to an embedded SQLite database utilizing Full-Text Search (FTS5) and write-ahead logging (WAL).
- **The Problem:** As user vaults scale beyond 10,000 Markdown files, naive recursive file system scans cause search latency to degrade from 12ms to over 850ms on macOS.
- **Desired Outcome:** Achieve sub-10ms full-text search across vaults containing up to 100,000 Markdown documents while preserving 100% plain text file durability.

## 2. Detailed Technical Design
```text
[User Note .md on Disk] ──(FSEvents change)──> [Background Worker]
                                                       │
                                                       ▼
[Instant UI Fuzzy Search] <──(FTS5 Query)── [Embedded SQLite WAL]

2.1 File System Synchronization Protocol

• Utilize native macOS FSEvents API to register directory watch notifications.
• Debounce file write events with a 250ms sliding window to prevent redundant index churn during active typing.
• Parse YAML frontmatter using native C-bindings; insert AST tokens into the FTS5 virtual table.

2.2 Schema Definition

CREATE VIRTUAL TABLE IF NOT EXISTS note_search_fts USING fts5(
    file_path UNINDEXED,
    title,
    tags,
    body_content,
    tokenize = 'porter unicode61'
);

3. Evaluated Alternatives Considered

Architecture Alternative	Pros	Cons	Why Rejected
Option A: Flat File Grep (ripgrep)	Zero indexing overhead; raw files	High CPU spikes on battery power	Unacceptable battery drain on multi-hour searches
Option B: In-Memory JSON Index	Fast lookups for small vaults	Memory footprint scales linearly to RAM	OOM crashes on large 100k vaults
Option C: Embedded SQLite FTS5	Sub-5ms queries; tiny RAM; zero server	Requires disk write for cache	Selected: Perfect balance of speed and efficiency

4. Security, Privacy & Data Integrity Implications

• Crash Recovery: SQLite WAL mode ensures that sudden power loss or force-quit cannot corrupt the user’s primary Markdown files on disk.
• Data Sovereignty: The SQLite index resides strictly inside ~/Library/Application Support/ with zero network sockets or external telemetry.

5. Migration & Rollback Strategy

• Migration: Background migration runs on startup; existing vaults are scanned asynchronously without blocking UI interactions.
• Rollback: If SQLite database file is corrupted, app deletes cache and falls back to flat regex file search while rebuilding index.

6. Review & Open Questions

• Question 1: What should the maximum allowable file size be for FTS indexing (e.g., exclude raw logs > 20MB)?
• Question 2: How should CJK (Chinese, Japanese, Korean) tokenization be handled? (Recommend ICU tokenizer).

7. Action Items

• Open Pull Request for RFC review across Core Systems team.
• Implement prototype branch benchmarking FTS5 on 50,000-note fixture.

## Filled Real-World Example

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

```markdown
---
title: "RFC: Local Whisper Ring Buffer"
date_proposed: 2026-10-06
author: "[[Devin Zhao]]"
rfc_number: "RFC-2026-038"
status: "Accepted"
tags: [rfc, audio, apple-silicon]
---

# Technical RFC Proposal Draft — Local Whisper Ring Buffer

## 1. Overview
Devin Zhao proposed replacing heap-allocated audio buffers with a lock-free circular ring buffer for real-time microphone stream ingestion.

## 2. Review Resolution
Accepted unanimously. Eliminates memory allocation jitter on high-frequency CoreAudio callback threads.

When to Use and When to Avoid

When to Use

• Use when proposing major technical refactors, database migrations, or new API protocols.
• Use to establish asynchronous engineering consensus across distributed remote teams.
• Use to document architectural rationale for future developers.

When to Avoid

• Avoid using for small non-architectural bug fixes or minor CSS tweaks.
• Avoid writing RFCs without evaluating at least two viable alternative solutions.

On-Device AI Integration

Summarize your recording in Oyma with this local instruction:

Analyze the proposed engineering initiative and technical problem:
1. Synthesize the core technical motivation and desired operational outcome.
2. Outline the detailed architectural design with ASCII dataflow diagrams and schemas.
3. Compare at least two alternative architectures and formulate an engineering RFC proposal in Markdown.

Your data remains securely on your Mac with zero cloud exposure.