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	active
0018	CodeScene code health gates in CI	active
0019	GitHub device flow OAuth for vault sync	active
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	active