Architectural Decision Records (ADRs)
Decisões arquiteturais do GarraIA seguem o formato MADR simplificado. Cada ADR é imutável após merge — se a decisão mudar, escreve-se um novo ADR que superseda o antigo.
Quando escrever um ADR
Per CLAUDE.md regra 8: sempre antes de uma decisão arquitetural irreversível. Exemplos:
- Escolha de database backend
- Escolha de vector store
- Protocolo de autenticação
- Framework de UI
- Runtime de sandbox
- Estratégia de deployment
Se a decisão é fácil de reverter (ex.: qual biblioteca de logging usar), ADR é overkill.
Convenção de nome
NNNN-slug-em-kebab-case.md
NNNN— sequencial monotônico. Primeira decisão é0001.slug— identificador humano curto.
Formato mínimo
Cada ADR tem essas seções:
- Status — proposed | accepted | superseded | deprecated
- Context and Problem Statement — o que estamos decidindo e por quê
- Decision Drivers — critérios ponderados
- Considered Options — alternativas com prós/contras
- Decision Outcome — a escolha + rationale
- Consequences — positive / negative / neutral
- Links — issues, PRs, benchmarks, docs externos
Rationale curta ("porque sim") é sinal de que a decisão não deveria ser ADR — ou que falta pensamento.
Index
| # | Title | Status | Date | Issue |
|---|---|---|---|---|
| 0001 | Local inference backend (candle vs mistral.rs vs llama.cpp) | ✅ accepted | 2026-04-21 | GAR-371 |
| 0002 | Vector store (pgvector vs lancedb vs qdrant embedded) | ✅ accepted | 2026-04-21 | GAR-372 |
| 0003 | Database para Group Workspace (Postgres vs SQLite) | ✅ accepted | 2026-04-13 | GAR-373 |
| 0004 | Object storage (S3 compatible, MinIO default) | ✅ accepted | 2026-04-21 | GAR-374 |
| 0005 | Identity Provider (BYPASSRLS role + Argon2id + HS256 + lazy upgrade) | ✅ accepted | 2026-04-13 | GAR-375 |
| 0006 | Search strategy (Postgres FTS → Tantivy → Meilisearch) | ✅ accepted | 2026-04-21 | GAR-376 |
| 0007 | Desktop frontend (HTML+Vanilla baseline → SolidJS trigger) | ✅ accepted | 2026-04-21 | GAR-377 |
| 0008 | Doc collaboration (Tier 1 single-editor → y-crdt Tier 2) | ✅ accepted | 2026-04-21 | GAR-378 |
| 0009 | Web Console design system "Garra Glass" (HTML+CSS custom tokens, zero CDN) | ✅ accepted | 2026-05-14 | GAR-607 |
| 0010 | Garra Learning Agent / Self-Improving Operations Manual | ✅ accepted | 2026-05-17 | GAR-641 |
| 0011 | GarraMaxPower — Native Agent-Advanced Mode (garra max-power) | ✅ accepted | 2026-05-24 | GAR-492 |
| 0012 | Persona Amistosa do Garra — tom de voz padrão (inspirado em OpenHuman) | ✅ accepted | 2026-06-01 | GAR-771 |
| 0013 | Recorrência de agendamento em duas camadas (cron no SQLite pessoal + RRULE no workspace) | ✅ accepted | 2026-08-29 | plan 0355 |
| 0014 | Superfície Anthropic-compatible no gateway (POST /v1/messages) | ✅ accepted | 2026-08-30 | plan 0360 |
| 0015 | Toolchain de empacotamento Linux (nfpm .deb/.rpm + appimagetool AppImage) | ✅ accepted | 2026-08-31 | plan 0361 |
| 0016 | Garra Mobile — Termux como camada de execução (local-first no Android, gerações v0-v3) | ✅ accepted | 2026-09-02 | ADR + release v0.3.6 |
| 0017 | Camada de apresentação do CLI (UiEvent + TerminalRenderer) | ✅ accepted | 2026-09-05 | #942 |
| 0018 | O que fazer com o crate garraia-embeddings | 📋 proposed | 2026-09-07 | #949 |
| 0019 | Confinamento das tools — PR_SET_DUMPABLE agora, Landlock depois | ✅ accepted | 2026-09-09 | #1084 |
| 0020 | Crate garraia-hardware — abstração de dispositivos físicos | ✅ accepted | 2026-09-11 | #1124 |
| 0021 | GarraIA Desktop — Control Center (garraia desktop) | ✅ accepted | 2026-09-14 | #1181 |
| 0022 | z-ai/glm-5.3-flash via OpenRouter como LLM padrão; local como segunda opção | ✅ accepted | 2026-09-13 | #1180 |
| 0023 | WhatsApp pessoal por dispositivo vinculado (garra whatsapp) — bridge Node/Baileys por stdio + sessão cifrada | ✅ accepted | 2026-09-16 | #1238 |
| 0024 | Perfis de execução standard e isolated-pod — poder total dentro do pod, nada implícito fora; dono do WhatsApp por identidade declarada; raiz do MCP filesystem no workspace | ✅ accepted | 2026-09-21 | #1329 |
| 0025 | Classes de capacidade, teto por principal e Access Policy v2 do WhatsApp | Accepted | 2026-09-26 | |
| 0026 | Schema de billing: plan / subscription / invoice no workspace (Garra Cloud; so schema) | ✅ accepted | 2026-10-22 | #1652 |
Legenda: ✅ accepted · 📋 proposed (aguardando execução) · 🔒 blocked (issue Linear aguardando este ADR ser escrito).
Histórico de supersessões
Nenhuma até o momento.