bigtux/caronte
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

CARONTE v1.0 - Plataforma de Gestão Social

Browse Source
This commit is contained in:
bigtux
2026-02-08 23:10:32 -03:00
commit c98c806865
60 changed files with 9450 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

456
docs/ARQUITETURA-TECNICA.md Normal file
View File

@@ -0,0 +1,456 @@
# 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*