tolaria/docs/adr

Architecture Decision Records

This folder contains Architecture Decision Records (ADRs) for the Laputa app.

Format

Each ADR is a markdown note with YAML frontmatter. Template:

---
type: ADR
id: "0001"
title: "Short decision title"
status: proposed        # proposed | active | superseded | retired
date: YYYY-MM-DD
superseded_by: "0007"  # only if status: superseded
---

## Context
What situation led to this decision? What forces and constraints are at play?

## Decision
**What was decided.** State it clearly in one or two sentences — bold so it stands out.

## Options considered
- **Option A** (chosen): brief description — pros / cons
- **Option B**: brief description — pros / cons
- **Option C**: brief description — pros / cons

## Consequences
What becomes easier or harder as a result?
What are the positive and negative ramifications?
What would trigger re-evaluation of this decision?

## Advice
*(optional)* Input received before making this decision — who was consulted, what they said, when.
Omit if the decision was made unilaterally with no external input.

Status lifecycle

proposed → active → superseded
                 ↘ retired      (decision no longer relevant, not replaced)

Rules

• One decision per file
• Files named NNNN-short-title.md (monotonic numbering)
• Once active, never edit — supersede instead
• When superseded: update status: superseded and add superseded_by: "NNNN"
• ARCHITECTURE.md reflects the current state (active decisions only)

Index

ID	Title	Status
0001	Tauri v2 + React as application stack	active
0002	Filesystem as the single source of truth	active
0003	Single note open at a time (no tabs)	active
0004	Vault vs app settings for state storage	active
0005	Tauri v2 iOS for iPad support (vs SwiftUI rewrite)	active
0006	Flat vault structure (no type-based folders)	active
0007	Title equals filename (slug sync)	active
0008	Underscore convention for system properties	active
0009	Keyword-only search (remove semantic indexing)	active
0010	Dynamic wikilink relationship detection	active
0011	MCP server for AI tool integration	active
0012	Claude CLI subprocess for AI agent	active
0013	Remove vault-based theming system	active
0014	Git-based incremental vault cache	active
0015	Auto-save with 500ms debounce	active
0016	Sentry + PostHog telemetry with consent	active
0017	Canary release channel and feature flags	superseded → 0057
0018	CodeScene code health gates in CI	superseded → 0064
0019	GitHub device flow OAuth for vault sync	superseded → 0056
0020	Keyboard-first design principle	active
0021	Push directly to main (no PRs)	active
0022	BlockNote as the rich text editor	active
0023	Repair Vault auto-bootstrap pattern	active
0024	Vault cache stored outside vault directory	active
0025	type: as canonical field (replacing Is A:)	active
0026	Props-down callbacks-up (no global state)	active
0027	Dual AI architecture (API chat + CLI agent)	superseded
0028	CLI agent only — no direct Anthropic API key	active
0029	Domain command builder pattern for useCommandRegistry	active
0030	Rust commands/ module split by domain	active
0031	Full App instance for secondary note windows	active
0032	Git actions (Changes, Pulse, Commit) in status bar, not sidebar	active
0033	Subfolder scanning and folder tree navigation	active
0034	Git repo required — blocking modal enforces vault prerequisite	active
0035	Path-suffix wikilink resolution for subfolder vaults	active
0036	External rename detection via git diff on focus regain	active
0037	Language-based markdown syntax highlighting in raw editor	active
0038	Frontmatter-backed favorites (_favorite, _favorite_index)	active
0039	Git history as source of truth for note creation/modification dates	active
0040	Custom Views — .laputa/views/*.yml with YAML filter engine	active
0041	fileKind field — scan all vault files, not just markdown	active
0042	Trash auto-purge safety model	superseded → 0045
0043	Reactive vault state: editor changes propagate immediately to all UI	active
0044	H1 as primary title source — filename as stable identifier	superseded → 0055
0045	Permanent delete with confirm modal — no Trash system	active
0046	Starter vault cloned from GitHub at runtime — no bundled content	active
0047	Regex mode for view filter conditions	active
0048	Relative date expressions in view filter conditions	active
0049	Per-note icon property (_icon on individual notes)	active
0050	Deterministic shortcut command routing	superseded → 0051
0051	Shared shortcut manifest for testable routing	superseded → 0052
0052	Renderer-first shortcut execution with native-menu dedupe	active
0053	Webview-init prevention for browser-reserved shortcuts	active
0054	Deterministic shortcut QA matrix	active
0055	H1 is the only editor title surface	active
0056	System git auth only — no provider-specific OAuth or repo APIs	active
0057	Alpha/stable release channels with PostHog beta cohorts	active
0058	Claude Code first-launch onboarding gate	superseded → 0062
0059	Local-only git commits for vaults without a remote	active
0060	Network-aware UI gating for remote-dependent features	active
0061	AI prompt bridge — module-level event bus for cross-component prompt routing	active
0062	Selectable CLI AI agents with a shared panel architecture	active
0063	BlockNote code-block package for editor syntax highlighting	active
0064	Ratcheted CodeScene thresholds as the quality gate baseline	active
0065	Root-managed AI guidance files with Claude shim	active