Arquitetura — canta-igreja

Gerado pelo Architect (Reversa) em 2026-05-11 doc_level: detalhado | Linguagem: TypeScript / React Native 0.84.1

---

Visão Geral

O canta-igreja é um aplicativo móvel (iOS e Android) com suporte experimental para web, voltado para músicos e cantores de celebrações litúrgicas católicas. Ele fornece:

• Catálogo de cânticos litúrgicos com busca FTS5 (SQLite)
• Gerenciamento local de repertórios musicais
• Calendário litúrgico offline (romcal) + leituras do dia online (API DANCRF)
• Compartilhamento de repertórios via API própria e geração de folhetos PDF
• Player YouTube integrado para audição de músicas
• Biblioteca de obras (hinários) baixáveis

Toda a lógica de dados é 100% local para uso offline, com funcionalidades de rede opcionais (compartilhamento, liturgia online, download de obras).

---

Pilha de Tecnologias

Camada	Tecnologia	Versão	Confiança
UI Framework	React Native	0.84.1	🟢
Linguagem	TypeScript	—	🟢
Web support	react-native-web + Vite	—	🟢
Navegação	React Navigation 7	7.x	🟢
Estado global	Redux Toolkit (slices + RTK Query)	2.11.2	🟢
Banco de dados	SQLite via op-sqlite (nativo) / WASM (web)	15.2.12	🟢
Key-value store	MMKV	^4.3.1	🟢
Autenticação	Google OAuth 2.0 / PKCE (AppAuth)	8.1.0	🟢
Credenciais nativas	Keychain / Android Keystore	10.0.0	🟢
Estilos	Unistyles 3	3.2.4	🟢
Monitoramento	Sentry	8.10.0	🟢
Calendário litúrg.	romcal (Brasil)	^3.0.0-dev	🟢
Animações	Reanimated 4	4.3.0	🟢

---

Padrões Arquiteturais

Camadas

┌─────────────────────────────────────────────────────────┐
│  View (screens/ + fragment/ + component/ + base/)       │
├─────────────────────────────────────────────────────────┤
│  Store (Redux Toolkit — slices, RTK Query, thunks)      │
├─────────────────────────────────────────────────────────┤
│  Service (lógica de negócio e orquestração)             │
├─────────────────────────────────────────────────────────┤
│  Repository (acesso a dados: SQLite, MMKV, Keychain)    │
├─────────────────────────────────────────────────────────┤
│  Model (interfaces TypeScript de domínio)               │
└─────────────────────────────────────────────────────────┘

• View: React Native (screens + fragments). Sem lógica de negócio.
• Store: Redux Toolkit. Slices por domínio + RTK Query para APIs externas (Liturgia, Biblioteca).
• Service: Orquestra múltiplos repositórios. Ex.: RepertorioService, ObraService, CalendarioLiturgicoService.
• Repository: Abstrai acesso ao SQLite, MMKV e Keychain. Isolam o código de persistência.
• Model: Interfaces TypeScript puras. Sem métodos.
• arch/: Infraestrutura transversal — auth, error (Sentry), migrations, estilo, hooks.

Padrões identificados

Padrão	Uso	Confiança
Strategy	3 estratégias de busca (sem termo / por índice / por FTS5)	🟢
Strategy	3 estratégias de folheto (slug / base64 / noop)	🟢
Strategy	Credenciais: Keychain nativo vs localStorage web	🟢
Repository	Camada de persistência isolada por domínio	🟢
Entity Adapter	Redux EntityAdapter em Musicas, Repertorios, SugestoesRepertorio	🟢
RTK Query	Requisições às APIs REST (Liturgia, Biblioteca)	🟢
CQRS leve	Thunks para escrita; seletores/RTK Query para leitura	🟡
Soft Delete	data_exclusao em repertorio	🟢

---

Módulos Funcionais

Módulo	Responsabilidade	Confiança
musicas	Busca FTS5, favoritar, visualizar, compartilhar letra	🟢
repertorios	CRUD local, compartilhar via API, gerar folheto, importar	🟢
livros	Hinários e edições — filtro na busca	🟢
biblioteca	Download + import atômico de obras SQLite	🟢
sugestao-repertorio	Sugestões litúrgicas pré-montadas, sincronização por ATTACH	🟢
liturgia	Calendário romcal offline + leituras DANCRF online + cache	🟢
auth	Google OAuth PKCE, token refresh automático	🟢
configuracoes	Preferências de UI: fonte, tamanho, tema, estilo refrão	🟢
youtube-player	Player YouTube embarcado com controle de sobreposição	🟢
arch	Migrations SQLite, sistema de estilos, hooks, error tracking	🟢

---

Integrações Externas

Serviço	Protocolo	Direção	Propósito	Auth	Confiança
canta.app API	HTTPS REST	Saída	Compartilhar repertório, autenticação, obras, slugs	Bearer (Google)	🟢
livreto.canta.app	HTTPS	Saída (URL)	Gerar e visualizar folheto PDF do repertório	Bearer / Base64	🟢
API DANCRF	HTTPS REST	Saída	Leituras litúrgicas do dia	Sem auth	🟢
YouTube	WebView	Saída	Player de vídeo embarcado (react-native-youtube-iframe)	Sem auth	🟢
Airtable	URL (form)	Saída	Formulário de reporte de erros em músicas	Sem auth	🟢
Google OAuth	HTTPS PKCE	Bidirecional	Autenticação e emissão de token	PKCE	🟢

---

Fluxo de Dados — Busca de Músicas

Usuário digita termo
       │
       ▼
Redux thunk: fetchMusicas(termo, filtros)
       │
       ▼
MusicasRepository.findAllBy()
       │
       ├── Sem termo → SELECT ORDER BY titulo (paginado)
       ├── Número → WHERE indice = ? (cantico_livro)
       └── Texto → FTS5 MATCH com BM25 ranking
       │
       ▼
Resultado paginado → Redux store (EntityAdapter)
       │
       ▼
View (FlatList) renderiza com snippet destacado

---

Fluxo de Dados — Compartilhamento de Repertório

Usuário toca "Compartilhar"
       │
       ▼
Verificar Auth → se Anônimo: iniciar Google OAuth PKCE
       │
       ▼
POST/PUT canta.app/api/v1/repertorios/{slug}
       │
       ▼
Recebe slug.corrente → persiste localmente
       │
       ▼
Gera mensagem Markdown (WhatsApp-friendly)
       │
       ▼
Share API nativa do SO

---

Dívidas Técnicas Arquiteturalmente Relevantes

ID	Impacto Arquitetural	Prioridade
DT-01	Ordenação por cantico_musica.ordem não implementada — resultados potencialmente fora de ordem no livro	Alta
DT-02	Busca por índice + livro não funciona corretamente	Alta
DT-03	Ciclos PAR/ÍMPAR ausentes no calendário litúrgico — FIXME explícito	Média
DT-08	Reordenação de itens de repertório desabilitada na UI	Média
DT-06	Auth duplicada em CompartilharService e AcessoAction — sem padronização	Baixa

---

Observações de Segurança (sumário)

Aspecto	Status
OAuth via PKCE	🟢 Sem client_secret no app
Token (nativo)	🟢 Keychain / Android Keystore
Token (web)	🟡 localStorage (sem HttpOnly)
SQL injection	🟢 Parametrized queries
ATTACH alias (web)	🟢 Validado por regex antes do ATTACH
CRC32	🟡 Verificação de atualização apenas — não criptográfico

---

Veja também:

• c4-context.md — Diagrama C4 Contexto
• c4-containers.md — Diagrama C4 Containers
• c4-components.md — Diagrama C4 Componentes
• erd-complete.md — ERD Completo
• traceability/spec-impact-matrix.md — Spec Impact Matrix