Documentação: inglês como versão principal e português em *.pt-BR.md

README, ROADMAP, CHANGELOG, CONTRIBUTING, SECURITY e docs/ passam a ter a versão principal em inglês. As versões em português ficam em *.pt-BR.md e docs/pt-BR/, com seletor de idioma no topo de cada arquivo. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RRZm8uTVN3WLTwcbrDQAUM
2026-10-20 09:48:51 -03:00
1 parent 3755fc7d2a
commit b93ad02a0e
@@ -0,0 +1,97 @@
+# Arquitetura
+
+[English](../architecture.md) · **Português**
+
+O Guará é um workspace Rust com três partes: um núcleo (`guara-core`), um binário de terminal (`guara-cli`) e uma interface (`apps/gui`) que é a mesma página web servida de duas formas.
+
+```
+crates/guara-core   biblioteca: tudo que lê, interpreta e recupera
+crates/guara-cli    binário `guara`: comandos e servidor local da interface
+apps/gui/ui         HTML, CSS e JS da interface
+apps/gui/src-tauri  casca desktop (Tauri) que carrega a mesma interface
+```
+
+## Fluxo de uma varredura
+
+```
+origem (dispositivo ou imagem)
+   │  source / device         leitura somente leitura, setores ruins tolerados
+   ▼
+disco virtual                 (opcional)
+   │  assemble                junta imagem E01/AFF4, RAID, LVM e volumes cifrados
+   ▼
+partições e volumes
+   │  partition, volume       MBR, GPT, volumes perdidos por assinatura
+   ▼
+duas buscas em paralelo
+   ├─ fs/*                    metadados: NTFS, FAT, exFAT, ext, HFS+, Btrfs, XFS, APFS
+   └─ carve + signatures      estrutura dos arquivos no espaço livre e fora de partições
+        + formats, jpegscan, defrag, mp4rebuild
+   ▼
+scan                          funde sem duplicatas e atribui a confiança
+   ▼
+sessão salva                  retomar, exportar, relatar
+   ▼
+recover                       copia com MD5, SHA-1 e SHA-256 e grava o manifesto
+```
+
+## Módulos do núcleo
+
+### Acesso e montagem
+| Módulo | Função |
+|---|---|
+| `source`, `device` | Abrir dispositivos e imagens somente para leitura; listar discos |
+| `image` | Imagem bruta tolerante a setores ruins, com mapa de erros |
+| `ewf`, `aff4` | Ler e gravar E01/Ex01 e AFF4 |
+| `assemble` | Monta o disco virtual: imagem, RAID, LVM e volume cifrado |
+| `raid`, `raid_detect`, `lvm` | Remontagem de RAID (com descoberta automática de parâmetros) e LVM2 |
+| `crypt/` | BitLocker, LUKS e FileVault 2 |
+| `reconnect` | Reconhecer o mesmo disco que voltou com outro nome |
+
+### Interpretação
+| Módulo | Função |
+|---|---|
+| `partition`, `volume` | Tabelas de partição e detecção de volumes |
+| `fs/` | Um leitor por sistema de arquivos |
+| `signatures`, `formats` | Detectores de formato pela estrutura |
+| `carve`, `scan` | Varredura por assinatura e fusão com os metadados |
+| `jpegscan`, `defrag`, `mp4rebuild` | JPEG fragmentado e MP4 sem `moov` |
+| `meta`, `sqlite`, `thumb` | Metadados, leitor de SQLite, miniaturas |
+
+### Resultado e perícia
+| Módulo | Função |
+|---|---|
+| `recover` | Copia os arquivos, confere os hashes, grava o manifesto, retoma recuperação |
+| `hashing`, `search` | Hashes e busca de texto no disco inteiro |
+| `report`, `explorer` | Relatório HTML, CSV, filtros e agrupamentos do explorador |
+| `health`, `external` | SMART e ferramentas externas (`smartctl`) |
+
+### Serviço
+`service`, `http`, `settings`, `notify`, `owner`: a camada que a interface usa (API local, configurações, notificações, e gravação com o dono certo quando roda como administrador).
+
+## Interface
+
+A interface é uma página só (`apps/gui/ui`). Há duas formas de rodá-la:
+
+- **App desktop (Tauri):** a janela carrega a página e fala com o núcleo diretamente.
+- **`guara ui`:** o binário sobe um servidor em `127.0.0.1` protegido por token e abre o navegador.
+
+Como o front-end é o mesmo, tudo que existe em um existe no outro.
+
+## Decisões de projeto
+
+- **Somente leitura na origem, por construção.** Todo acesso a dispositivo passa por `source::open_path`. Revisão de código recusa qualquer escrita na origem.
+- **Recusa de destino no mesmo disco** da origem (Linux e macOS), para não sobrescrever o que se quer recuperar.
+- **Confiança por arquivo.** Cada detector declara o quanto conseguiu conferir; a fusão fica com a melhor evidência.
+- **Leitores próprios.** Sistemas de arquivos, cifras, SQLite e contêineres de imagem são implementados no núcleo, para tolerar estruturas corrompidas, que é exatamente o caso de uso.
+- **Segredos fora da sessão.** Senhas nunca são gravadas; no máximo a chave do volume, e só com `--remember-keys`.
+- **Privilégios.** Ler disco bruto exige administrador, mas tudo que o Guará grava (sessões, relatórios, recuperados) fica com o dono e as permissões do usuário que o abriu.
+
+## Testes
+
+Cerca de cem testes, em `crates/guara-core/tests/` (um arquivo por área: `ext4`, `xfs`, `apfs`, `bitlocker`, `raid`, `ewf`, `jpegscan`, `mp4rebuild`, `sqlite` e outros).
+
+- **Imagens geradas na hora** com `mtools`, `ntfs-3g`, `e2fsprogs` e afins (`scripts/make-fixtures.sh`).
+- **Imagens de referência** de projetos externos (cryptsetup, dfvfs, AFF4) baixadas por `scripts/fetch-testdata.sh` para `target/testdata`. Sem elas, os testes correspondentes são pulados.
+- Os testes de BitLocker levam cerca de 75 s por causa da derivação de chave.
+- No CI os testes com imagens reais rodam só no Linux.