25 KiB
25 KiB
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
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 é:
- API oficial → usar diretamente (Gov.br, CRC)
- Portal com login → guiar o usuário com tutorial passo-a-passo integrado
- Sem API → gerar documento preenchido para protocolo presencial
- 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:
- Privacidade — dados cifrados, LGPD desde o dia zero
- Simplicidade — interface para quem nunca fez um inventário
- Completude — nenhum benefício esquecido, nenhum prazo perdido
- Escalabilidade — regras por UF, extensível para novos tipos de benefício
Documento gerado em 08/02/2026 — CARONTE Project