Arquitetura, Modelo de Dados & UX

01 Visão do produto

phai conecta ao agregador open-finance Pluggy, normaliza tudo num store relacional e produz relatórios legíveis por humanos (padrão) ou JSON estruturado (--raw) consumido por agentes e dashboards.

02 Arquitetura

Binário único, zero cerimônia. Sem Postgres, sem Redis, sem servidor de dashboard. SQLite embarcado no binário; BigQuery por HTTPS. Migrations embutidas em tempo de compilação.

Mapa de camadas

Os 8 princípios que governam tudo

Fluxo de sync (Pluggy → store)

# phai sync pluggy
Pluggy.list_items() → fetch_transactions()      // TransactionRecord[] (Decimal)
  → store.existing_transaction_ids(ids)        // BTreeSet<String>
  → store.upsert_transactions(novos + alterados) // idempotente, ON CONFLICT
  → store.insert_audit_events([Sync{…}])       // 1 evento por write
  → resumo humano  |  --json-summary

Chaves de idempotência derivadas do payload Pluggy em idempotency.rs. Re-rodar sync é seguro: não duplica.

Stack técnico

03 Modelo de dados

Shapes intencionalmente planos: uma linha entra, uma linha sai. Join e formatação acontecem em views SQL, não em structs.

A trait FinanceStore — a única costura

async, Send + Sync, ~50 métodos, 2 implementações. É larga de propósito: o domínio é finito (não é ORM genérico), e relatórios são métodos de primeira classe (daily_pulse, card_summary, cashflow…) porque empacotam a regra de negócio que distingue “valor bruto” de “o que você deve ver”.

Invariantes da trait

1. Nenhum valor interpolado em SQL. Todo parâmetro é bound. O único identificador dinâmico permitido é nome de tabela, e passa por validate_table_name (allowlist).
2. Relatórios retornam Decimal — nunca f64, nunca string-fingindo-decimal.
3. Todo write emite AuditEvent — o caller insere; testes asseguram a linha de auditoria.
4. Upserts idempotentes — ON CONFLICT/MERGE, nunca insert+dedup na aplicação.
5. Migrations append-only — prefixos monotônicos; migration liberada nunca é editada, só superseded.

Entidades centrais

TransactionRecord — a unidade atômica

“Anatomia da transação” = os campos humanos (description/merchant_name/purpose) separados do raw_description técnico — ADR-0014.

AuditEvent — log append-only de toda mutação

pub struct AuditEvent {
  pub id: Uuid,            // v7 — ordenável cronologicamente
  pub actor_id: String,    // quem disparou (CLI actor, agente, device)
  pub action: String,      // "tx.categorize", "sync.pluggy", "split.apply"
  pub entity: String,      // "transaction", "rule", "budget"
  pub entity_id: String,
  pub payload: Value,      // snapshot before/after
  pub created_at: DateTime<Utc>,
}

Gramática entity.verb: tx.upsert, tx.split.apply, rule.upsert, forecast.upsert, sync.pluggy, import.legacy.

Outras entidades do domínio

Idempotência

idempotency.rs deriva chaves estáveis de payloads. Detalhe relevante (achado na auditoria): a chave de forecast usa actor + descrição + data + valor + conta + categoria + recorrência + template_id — status não entra. Por isso duas previsões que só diferem no vocabulário de status (ativo vs active) geram a mesma chave e deduplicam corretamente.

04 A cadeia de views canônica

Relatórios não leem tabelas cruas — leem uma única cadeia de views que assa a regra de negócio. É a regra que impede os números de fluxo de caixa de regredirem (ADR-0026). CLI, gráfico de cashflow e app web leem a mesma cadeia.

O que isso garante

• Regime de caixa, não competência. A família vê o mês em que o dinheiro de fato sai: a fatura paga em maio “explode” nas compras individuais sob maio — não como pagamento único, não nas datas originais. Requer billing_closing_day/billing_due_day (phai account set-billing-cycle); sem isso, cai no mês-calendário do lançamento. (ADR-0025)
• Categorias internas (credit-card-payment, transfer-internal, same-person-transfer) são a única lista de exclusão, aplicada nas views — pagar fatura ou mover entre duas contas próprias rastreadas nunca dupla-conta. Dinheiro de conta não rastreada (ex.: repasse de salário) é renda real e não é excluído.
• FinanceStore::cashflow_reportable é um SELECT … FROM v_cashflow fino. Regra nova vai na view ou na lista de exclusão — nunca numa query Rust ou na camada web.

05 UX — a voz dos relatórios

phai é a única fonte de verdade operacional. Agentes (OpenClaw, Claude, ChatGPT, Codex) preferem relatórios padrão a formatar à mão.

Regras de naming & classificação

• Nunca inventar categorias. Atribuição vem de rules + overrides efetivos na camada de view.
• Display label = description quando presente; senão merchant_name; senão raw_description.
• classifier_trace é debug técnico — nunca aparece em relatório para a família.
• Nome de transação aparece com prefixo emoji das display rules.

Desambiguação de fatura (a sutileza que mais confunde)

Ex.: compra em 28/mar com closing-day 3 vive no ciclo que fecha em 3/abr → month_ref = 2026-04.

Pipeline de enriquecimento (propõe, não escreve)

O enriquecimento sugere; a tabela rules persiste. Estágios, todos opcionais:

pluggy_map  → traduz dicas de categoria do Pluggy para a taxonomia local
cnpj        → consulta CNPJ (BrasilAPI) para enriquecer descrições
heuristics  → padrões genéricos NÃO-pessoais (moeda, parcela, sufixos comuns)
fuzzy       → casa descrição desconhecida com histórico rotulado (nucleo)
llm         → último recurso via rig-core; prompt.rs controla o system prompt
rule_gen    → propõe um RuleRecord de uma sugestão confiante; usuário aceita/rejeita

Replicação de revisão humana (ADR-0033): transações recorrentes herdam description/purpose/categoria confiável de histórico do mesmo merchant — replicação direta com scoring tolerante a valor, não criação automática de regra.

Superfícies de interação

06 O app web (phai serve)

LiveStore + React (Vite), client-only (sem backend de sync LiveStore), embarcado no binário via include_dir!("web/dist"). Writes descarregam na ponte Rust (/api/*), que é o sistema de registro BigQuery/SQLite (ADR-0023).

Modelo de segurança da ponte (ADR-0036)

Sem autenticação por requisição — a fronteira de segurança é:

Protege: acesso remoto, DNS rebinding, CSRF cross-site, clickjacking. Fora de escopo (aceito): processo local malicioso — que já tem o filesystem do usuário.

Telas principais

Ativação multi-device (ADR-0034)

Convite auto-contido criptografado por senha: empacota coordenadas BigQuery + chave de service-account num único token PHAI1E-…. Argon2id deriva a chave; XChaCha20-Poly1305 cifra o payload. O blob é uma credencial. Fluxo zero-CLI: convite → install → onboarding web.

Derivações client-side

lib/derivations.ts (~1100 linhas) é o cérebro do front: filterTransactions, groupByCategory, computeMonthSums, buildWarPlan, commitmentTier, buildEnvelopeWrites. Funções puras memoizadas nos call-sites. Tudo deriva do store — consistente com o princípio #1.

07 Decisões arquiteturais que moldam o resto

37 ADRs em docs/adr/. Os que mais explicam o sistema:

08 Estado atual — release v5.28.2

Auditoria de 2026-06-24 + 9 correções entregues. A base é sólida: cripto e SQL bem feitos, servidor loopback com defesas reais.

Gates do projeto

Pontos de atenção em aberto

• MonthDetail reimplementa filtro inline em vez de filterTransactions — em sync mas sem teste (issue #227).
• Daemon porta-80 roda como root via launchd; binário em disco já é v5.28.2, falta restart manual (sudo).
• Paridade de splits SQLite ↔ BigQuery (acima).