# CARONTE — Arquitetura Técnica

> *O barqueiro que guia famílias enlutadas pelo rio burocrático brasileiro.*
> Versão 1.0 — Fevereiro 2026

---

## 1. Visão Geral

O CARONTE é uma plataforma que automatiza e orienta famílias no processo pós-óbito no Brasil — desde a certidão de óbito até a partilha final de bens. Elimina a desorientação burocrática transformando um processo caótico em um fluxo guiado, passo a passo.

---

## 2. Stack Tecnológico

| Camada | Tecnologia | Justificativa |
|---|---|---|
| **Backend / API** | FastAPI (Python 3.12+) | Async nativo, tipagem forte, docs automáticas (OpenAPI) |
| **Frontend** | Next.js 14 (App Router) | SSR/SSG, React Server Components, SEO |
| **Banco de dados** | PostgreSQL 16 | JSONB para docs flexíveis, full-text search, confiabilidade |
| **ORM** | SQLAlchemy 2.0 + Alembic | Migrations versionadas, async support |
| **Cache / Filas** | Redis 7 | Cache de sessão, rate limiting, filas com BullMQ |
| **Task Queue** | Celery + Redis broker | Jobs assíncronos (scraping gov, geração de PDFs) |
| **Storage** | MinIO (S3-compatible) | Documentos, certidões, PDFs gerados |
| **Auth** | JWT + OAuth2 (Gov.br) | Login cidadão via Gov.br, fallback email/senha |
| **PDF Engine** | WeasyPrint + Jinja2 | Geração de petições e requerimentos |
| **Infra** | Docker Compose → K8s | Dev local com Compose, prod em Kubernetes |
| **CI/CD** | GitHub Actions | Testes, lint, build, deploy |
| **Monitoramento** | Sentry + Prometheus + Grafana | Erros, métricas, alertas |

---

## 3. Diagrama de Módulos

```
┌─────────────────────────────────────────────────────────────────────┐
│                        FRONTEND (Next.js 14)                        │
│  ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌─────────┐ │
│  │Dashboard │ │Checklist │ │ Benefícios│ │Documentos│ │ Perfil  │ │
│  │ Familiar │ │  Guiado  │ │  Scanner  │ │ Gerados  │ │ Família │ │
│  └────┬─────┘ └────┬─────┘ └─────┬─────┘ └────┬─────┘ └────┬────┘ │
└───────┼────────────┼─────────────┼─────────────┼────────────┼──────┘
        │            │             │             │            │
════════╪════════════╪═════════════╪═════════════╪════════════╪══════
        │         API Gateway (FastAPI)          │            │
════════╪════════════╪═════════════╪═════════════╪════════════╪══════
        ▼            ▼             ▼             ▼            ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      BACKEND (FastAPI)                              │
│                                                                     │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────┐ │
│  │  MOTOR DE        │  │  SCANNER DE     │  │  GERADOR DE         │ │
│  │  CHECKLIST       │  │  BENEFÍCIOS     │  │  DOCUMENTOS         │ │
│  │                  │  │                 │  │                     │ │
│  │ • Fluxo por UF   │  │ • FGTS          │  │ • Procurações       │ │
│  │ • Prazos legais  │  │ • PIS/PASEP     │  │ • Requerimentos     │ │
│  │ • Dependências   │  │ • Seguros vida  │  │ • Petições          │ │
│  │ • Notificações   │  │ • Previdência   │  │ • Alvará judicial   │ │
│  │ • Estado por item│  │ • Pensão morte  │  │ • Templates Jinja2  │ │
│  └────────┬─────────┘  └────────┬────────┘  └──────────┬──────────┘ │
│           │                     │                      │            │
│  ┌────────┴─────────────────────┴──────────────────────┴──────────┐ │
│  │                    CAMADA DE INTEGRAÇÃO                         │ │
│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────────┐ │ │
│  │  │Gov.br  │ │INSS    │ │Receita │ │DETRAN  │ │ Bancos       │ │ │
│  │  │(Auth)  │ │(Meu    │ │Federal │ │(veíc.) │ │ (Open Banking│ │ │
│  │  │        │ │ INSS)  │ │(e-CAC) │ │        │ │  / consulta) │ │ │
│  │  └────────┘ └────────┘ └────────┘ └────────┘ └──────────────┘ │ │
│  └────────────────────────────────────────────────────────────────┘ │
│                                                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │
│  │ Auth Module   │  │ Notificações │  │ Audit / Compliance       │  │
│  │ JWT + Gov.br  │  │ Email + Push │  │ LGPD + Logs imutáveis    │  │
│  └──────────────┘  └──────────────┘  └──────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
        │                     │                      │
        ▼                     ▼                      ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐
│ PostgreSQL   │  │    Redis     │  │     MinIO (S3)           │
│ (dados)      │  │ (cache/fila) │  │ (docs/certidões/PDFs)    │
└──────────────┘  └──────────────┘  └──────────────────────────┘
```

---

## 4. Módulos Detalhados

### 4.1 Motor de Checklist Burocrático

O coração do sistema. Modela o processo pós-óbito como uma **máquina de estados** com dependências entre etapas.

**Fluxo principal:**
```
Óbito registrado
  └─→ Certidão de Óbito
       └─→ Comunicação ao banco / empregador / INSS
            ├─→ Pensão por Morte (INSS)
            ├─→ Saque FGTS / PIS-PASEP
            ├─→ Seguro de Vida (se houver)
            ├─→ Inventário (judicial ou extrajudicial)
            │    ├─→ Avaliação de bens
            │    ├─→ Cálculo ITCMD
            │    └─→ Partilha
            └─→ Transferência de veículos / imóveis
```

**Características:**
- Checklist dinâmico por UF (regras estaduais de ITCMD, cartórios)
- Prazos legais com alertas (ex: inventário em 60 dias para isenção de multa)
- Itens condicionais (só mostra "transferir veículo" se falecido tinha veículo)
- Status por item: `pendente` → `em_andamento` → `concluido` → `nao_aplicavel`

### 4.2 Scanner de Benefícios

Identifica automaticamente todos os direitos financeiros dos herdeiros.

| Benefício | Fonte | Prazo |
|---|---|---|
| FGTS | Caixa Econômica | Sem prazo (mas quanto antes melhor) |
| PIS/PASEP | Caixa / Banco do Brasil | 5 anos |
| Pensão por Morte | INSS | 90 dias (retroativa) / 180 dias (integral) |
| Seguro de Vida | Seguradoras (SUSEP) | 3 anos |
| Restituição IR | Receita Federal | 5 anos |
| Seguro DPVAT | Seguradora Líder | 3 anos |
| Previdência Privada | Bancos / Seguradoras | Varia |

### 4.3 Gerador de Documentos

Motor de templates usando **Jinja2 + WeasyPrint** para gerar PDFs prontos para uso.

**Documentos gerados:**
- Procuração para herdeiro(a) representante
- Requerimento de saque FGTS por falecimento
- Requerimento de pensão por morte (INSS)
- Petição de alvará judicial (para valores < limite extrajudicial)
- Declaração de herdeiros únicos
- Comunicação de óbito a instituições financeiras

### 4.4 Dashboard Familiar

Painel compartilhado entre membros da família com:
- **Progresso geral** (% do processo concluído)
- **Próximos passos** com prioridade por urgência/prazo
- **Documentos** organizados por categoria
- **Linha do tempo** de tudo que já foi feito
- **Convites** para outros membros da família

---

## 5. Modelo de Dados

### 5.1 Diagrama Entidade-Relacionamento

```
┌──────────────┐       ┌──────────────────┐       ┌──────────────────┐
│   usuario    │       │     familia      │       │    falecido      │
├──────────────┤       ├──────────────────┤       ├──────────────────┤
│ id (PK)      │──┐    │ id (PK)          │    ┌──│ id (PK)          │
│ nome         │  │    │ nome             │    │  │ familia_id (FK)  │
│ email        │  │    │ created_at       │    │  │ nome_completo    │
│ cpf_hash     │  │    │ status           │    │  │ cpf_cifrado      │
│ govbr_id     │  │    │ uf               │    │  │ data_nascimento  │
│ created_at   │  │    └──────────────────┘    │  │ data_obito       │
└──────────────┘  │             │               │  │ certidao_obito   │
                  │             │ 1:N            │  │ tinha_emprego    │
                  │             ▼               │  │ tinha_veiculo    │
              ┌───┴──────────────────┐         │  │ tinha_imovel     │
              │  membro_familia      │         │  │ tinha_previdencia│
              ├──────────────────────┤         │  └──────────────────┘
              │ id (PK)              │         │           │
              │ usuario_id (FK)      │         │           │ 1:N
              │ familia_id (FK)      │         │           ▼
              │ papel (enum)         │         │  ┌──────────────────┐
              │ parentesco           │         │  │ checklist_item   │
              │ is_responsavel       │         │  ├──────────────────┤
              └──────────────────────┘         │  │ id (PK)          │
                                               │  │ falecido_id (FK) │
┌──────────────────┐    ┌──────────────────┐   │  │ template_id (FK) │
│ beneficio        │    │   documento      │   │  │ status (enum)    │
├──────────────────┤    ├──────────────────┤   │  │ responsavel_id   │
│ id (PK)          │    │ id (PK)          │   │  │ prazo_legal      │
│ falecido_id (FK) │────│ falecido_id (FK) │───┘  │ concluido_em     │
│ tipo (enum)      │    │ tipo (enum)      │      │ notas            │
│ instituicao      │    │ nome             │      │ ordem            │
│ valor_estimado   │    │ storage_path     │      │ depende_de (FK)  │
│ status           │    │ gerado_por_sistema│     └──────────────────┘
│ prazo_limite     │    │ uploaded_at      │
│ valor_sacado     │    │ hash_sha256      │      ┌──────────────────┐
└──────────────────┘    └──────────────────┘      │ checklist_tpl    │
                                                  ├──────────────────┤
┌──────────────────┐    ┌──────────────────┐      │ id (PK)          │
│ notificacao      │    │  audit_log       │      │ titulo           │
├──────────────────┤    ├──────────────────┤      │ descricao        │
│ id (PK)          │    │ id (PK)          │      │ categoria        │
│ usuario_id (FK)  │    │ usuario_id (FK)  │      │ uf (nullable)    │
│ tipo             │    │ acao             │      │ condicao (JSONB) │
│ titulo           │    │ entidade         │      │ prazo_dias       │
│ corpo            │    │ entidade_id      │      │ documentos_req   │
│ lida             │    │ dados_antes      │      │ links_uteis      │
│ created_at       │    │ dados_depois     │      └──────────────────┘
└──────────────────┘    │ ip_address       │
                        │ created_at       │
                        └──────────────────┘
```

### 5.2 Enums Principais

```python
class StatusChecklist(str, Enum):
    PENDENTE = "pendente"
    EM_ANDAMENTO = "em_andamento"
    AGUARDANDO_DOCUMENTO = "aguardando_documento"
    CONCLUIDO = "concluido"
    NAO_APLICAVEL = "nao_aplicavel"
    BLOQUEADO = "bloqueado"  # dependência não atendida

class TipoBeneficio(str, Enum):
    FGTS = "fgts"
    PIS_PASEP = "pis_pasep"
    PENSAO_MORTE = "pensao_morte"
    SEGURO_VIDA = "seguro_vida"
    RESTITUICAO_IR = "restituicao_ir"
    DPVAT = "dpvat"
    PREVIDENCIA_PRIVADA = "previdencia_privada"

class PapelFamilia(str, Enum):
    INVENTARIANTE = "inventariante"
    HERDEIRO = "herdeiro"
    CONJUGE = "conjuge"
    ADVOGADO = "advogado"
    CONTADOR = "contador"
```

---

## 6. APIs e Integrações Externas

### 6.1 APIs Governamentais

| Serviço | API / Método | Finalidade |
|---|---|---|
| **Gov.br** | OAuth2 (login único) | Autenticação cidadã (selo prata/ouro) |
| **INSS (Meu INSS)** | API + scraping assistido | Consulta vínculos, requerimento pensão por morte |
| **Receita Federal (e-CAC)** | API / certificado digital | Consulta situação fiscal, restituição IR |
| **DETRAN** | API estadual (varia por UF) | Consulta veículos em nome do falecido |
| **Caixa Econômica** | API parceiro / orientação | FGTS, PIS |
| **Banco do Brasil** | API parceiro / orientação | PASEP |
| **SUSEP** | Consulta pública | Verificar apólices de seguro ativas |
| **CRC Nacional** | API cartórios | Certidões (nascimento, casamento, óbito) |

### 6.2 APIs de Terceiros

| Serviço | Finalidade |
|---|---|
| **SendGrid / AWS SES** | Envio de emails transacionais |
| **Firebase Cloud Messaging** | Push notifications (mobile/web) |
| **ViaCEP** | Autocompletar endereços |
| **Open Banking (fase 4)** | Consulta de contas/saldos do falecido |

### 6.3 Estratégia de Integração

Nem todas as APIs gov possuem endpoints REST abertos. A estratégia é:

1. **API oficial** → usar diretamente (Gov.br, CRC)
2. **Portal com login** → guiar o usuário com tutorial passo-a-passo integrado
3. **Sem API** → gerar documento preenchido para protocolo presencial
4. **Parcerias futuras** → negociar acesso via convênios (Caixa, BB, INSS)

---

## 7. Segurança e LGPD

### 7.1 Dados Sensíveis

O CARONTE lida com dados de **pessoas falecidas** e seus **herdeiros vivos**. A LGPD (Lei 13.709/2018) se aplica integralmente aos vivos e, por extensão prática, aos dados do falecido que identificam herdeiros.

### 7.2 Medidas Técnicas

```
┌──────────────────────────────────────────────────┐
│              CAMADA DE SEGURANÇA                  │
│                                                    │
│  ┌─────────────────┐  ┌─────────────────────────┐ │
│  │ Criptografia     │  │ Controle de Acesso       │ │
│  │                  │  │                          │ │
│  │ • CPF: AES-256   │  │ • RBAC por família       │ │
│  │ • Docs: encrypt  │  │ • Convite com expiração  │ │
│  │   at rest (S3)   │  │ • MFA obrigatório        │ │
│  │ • TLS 1.3 em     │  │ • Sessão com TTL curto   │ │
│  │   trânsito       │  │ • IP allowlist (admin)   │ │
│  └─────────────────┘  └─────────────────────────┘ │
│                                                    │
│  ┌─────────────────┐  ┌─────────────────────────┐ │
│  │ Auditoria        │  │ LGPD Compliance          │ │
│  │                  │  │                          │ │
│  │ • Log imutável   │  │ • Consentimento explícito│ │
│  │   (append-only)  │  │ • Finalidade declarada   │ │
│  │ • Quem acessou   │  │ • Direito ao esquecimento│ │
│  │   o quê e quando │  │ • Portabilidade (export) │ │
│  │ • Retenção 5 anos│  │ • DPO designado          │ │
│  └─────────────────┘  └─────────────────────────┘ │
└──────────────────────────────────────────────────┘
```

### 7.3 Políticas

| Aspecto | Implementação |
|---|---|
| **CPF do falecido** | Nunca armazenado em texto plano; cifrado com AES-256-GCM, chave em vault |
| **Documentos** | Criptografados em repouso no MinIO, acesso via URL assinada com TTL |
| **Consentimento** | Tela de aceite no onboarding; registro em tabela `consentimentos` |
| **Exclusão de dados** | Endpoint `/api/v1/familia/{id}/apagar` — soft delete + hard delete em 30 dias |
| **Logs de auditoria** | Tabela `audit_log` append-only, sem UPDATE/DELETE permitido |
| **Backup** | PostgreSQL: WAL archiving + pg_basebackup diário, criptografado |
| **Acesso interno** | Zero trust; funcionários acessam via VPN + MFA + role mínimo |

---

## 8. Estrutura do Projeto

```
caronte/
├── backend/
│   ├── app/
│   │   ├── main.py                 # FastAPI app
│   │   ├── core/
│   │   │   ├── config.py           # Settings (pydantic-settings)
│   │   │   ├── security.py         # JWT, hashing, criptografia
│   │   │   └── database.py         # Engine, session
│   │   ├── models/                 # SQLAlchemy models
│   │   │   ├── usuario.py
│   │   │   ├── familia.py
│   │   │   ├── falecido.py
│   │   │   ├── checklist.py
│   │   │   ├── beneficio.py
│   │   │   └── documento.py
│   │   ├── schemas/                # Pydantic schemas
│   │   ├── api/
│   │   │   └── v1/
│   │   │       ├── auth.py
│   │   │       ├── familias.py
│   │   │       ├── checklist.py
│   │   │       ├── beneficios.py
│   │   │       ├── documentos.py
│   │   │       └── dashboard.py
│   │   ├── services/               # Lógica de negócio
│   │   │   ├── checklist_engine.py
│   │   │   ├── beneficio_scanner.py
│   │   │   ├── document_generator.py
│   │   │   └── integrations/
│   │   │       ├── govbr.py
│   │   │       ├── inss.py
│   │   │       ├── receita.py
│   │   │       └── caixa.py
│   │   ├── tasks/                  # Celery tasks
│   │   │   ├── notificacoes.py
│   │   │   └── scrapers.py
│   │   └── templates/              # Jinja2 (docs jurídicos)
│   │       ├── procuracao.html
│   │       ├── requerimento_fgts.html
│   │       └── peticao_alvara.html
│   ├── alembic/                    # Migrations
│   ├── tests/
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── app/                    # Next.js App Router
│   │   │   ├── (auth)/
│   │   │   │   ├── login/
│   │   │   │   └── registro/
│   │   │   ├── (dashboard)/
│   │   │   │   ├── familia/[id]/
│   │   │   │   ├── checklist/
│   │   │   │   ├── beneficios/
│   │   │   │   └── documentos/
│   │   │   └── layout.tsx
│   │   ├── components/
│   │   ├── lib/
│   │   │   ├── api.ts              # Client API
│   │   │   └── auth.ts
│   │   └── types/
│   ├── Dockerfile
│   └── package.json
├── infra/
│   ├── docker-compose.yml
│   ├── docker-compose.prod.yml
│   ├── nginx.conf
│   └── k8s/
├── docs/
│   ├── ARQUITETURA-TECNICA.md      # ← este arquivo
│   ├── MODELO-NEGOCIO.md
│   └── API.md
└── README.md
```

---

## 9. Endpoints Principais (API v1)

```
POST   /api/v1/auth/login              # Login Gov.br ou email
POST   /api/v1/auth/registro           # Criar conta
GET    /api/v1/auth/me                  # Perfil do usuário

POST   /api/v1/familias                # Criar núcleo familiar
GET    /api/v1/familias/{id}            # Dados da família
POST   /api/v1/familias/{id}/membros    # Convidar membro
POST   /api/v1/familias/{id}/falecido   # Registrar falecido

GET    /api/v1/checklist/{falecido_id}          # Listar itens
PATCH  /api/v1/checklist/item/{id}              # Atualizar status
GET    /api/v1/checklist/{falecido_id}/proximo   # Próximo passo sugerido

GET    /api/v1/beneficios/{falecido_id}          # Benefícios identificados
POST   /api/v1/beneficios/{falecido_id}/scan     # Rodar scanner

POST   /api/v1/documentos/gerar                  # Gerar documento (PDF)
GET    /api/v1/documentos/{id}/download           # Baixar documento
POST   /api/v1/documentos/upload                  # Upload de certidão/doc

GET    /api/v1/dashboard/{familia_id}             # Resumo do dashboard
GET    /api/v1/dashboard/{familia_id}/timeline     # Linha do tempo

DELETE /api/v1/familia/{id}/apagar                # LGPD: exclusão de dados
GET    /api/v1/familia/{id}/exportar              # LGPD: portabilidade
```

---

## 10. Roadmap de Implementação

| Fase | Escopo | Prazo Estimado |
|---|---|---|
| **MVP (v0.1)** | Auth, checklist estático, dashboard básico | 6-8 semanas |
| **v0.2** | Scanner de benefícios, gerador de docs (3 templates) | +4 semanas |
| **v0.3** | Integração Gov.br, notificações por email | +4 semanas |
| **v1.0** | Checklist dinâmico por UF, mobile PWA, onboarding guiado | +6 semanas |
| **v1.5** | Integração parceiros (bancos, cartórios), IA para FAQ | +8 semanas |
| **v2.0** | Open Banking, marketplace de advogados/contadores | Futuro |

---

## 11. Considerações Finais

O CARONTE não substitui advogados — ele **elimina a ignorância burocrática** que faz famílias perderem dinheiro e prazos. O sistema é o guia; o profissional jurídico é o executor quando necessário.

A arquitetura prioriza:
1. **Privacidade** — dados cifrados, LGPD desde o dia zero
2. **Simplicidade** — interface para quem nunca fez um inventário
3. **Completude** — nenhum benefício esquecido, nenhum prazo perdido
4. **Escalabilidade** — regras por UF, extensível para novos tipos de benefício

---

*Documento gerado em 08/02/2026 — CARONTE Project*