Proposta Técnica — Plataforma de Automação Athina + Flwe

Visão Geral

Esta proposta consolida:

alinhamentos das reuniões;
mapa mental;
arquitetura técnica;
System Design;
Clean Architecture;
workflows;
filas;
crawlers;
observabilidade;
domínio do sistema;
estratégia MVP + evolução.

O objetivo é criar uma camada externa de automação desacoplada do Flwe, utilizando Python, FastAPI, LangGraph, Redis, RabbitMQ e crawlers especializados.

Mapa Mental da Solução

O mapa mental abaixo resume a proposta em uma visão executiva, conectando contexto, arquitetura, fluxos, tecnologia, riscos e evolução da plataforma.

[Diagram]

1. Contexto do Projeto

A Athina Seguros possui processos manuais envolvendo:

leitura de e-mails;
PDFs;
propostas;
apólices;
parcelas;
Quiver;
seguradoras;
monitoramento operacional.

O Flwe já existe e continuará sendo:

o sistema operacional principal;
a interface dos usuários;
a fonte operacional da empresa.

A automação NÃO modificará o código do Flwe.

2. Objetivo da Solução

Construir uma plataforma:

desacoplada;
escalável;
resiliente;
auditável;
evolutiva.

Capaz de:

automatizar leitura de e-mails;
processar PDFs;
executar OCR;
consultar seguradoras;
atualizar Quiver;
controlar workflows;
aplicar retries;
suportar validação manual.

3. Princípios Arquiteturais

Princípio	Aplicação
Baixo acoplamento	Não alterar o Flwe
Evolução incremental	MVP simples e crescimento gradual
Clean Architecture	Separação de domínio e infraestrutura
Resiliência	Retry, fallback e DLQ
Observabilidade	Logs, métricas e auditoria
Escalabilidade	Workers e filas
Segurança	Controle de credenciais e rastreabilidade

4. Arquitetura Geral

Beautiful Mermaid

[Diagram]

5. Fluxo Principal

[Diagram]

O LangGraph será o orquestrador, cérebro do fluxo.

Responsabilidades:

decidir próxima etapa;
controlar estado da tarefa;
aplicar retries;
aplicar fallback;
decidir se vai para validação manual;
recuperar contexto no Redis;
atualizar status;
acionar workers;
finalizar ou arquivar tarefa.

Exemplo de estados:

CREATED
EMAIL_RECEIVED
DOCUMENT_EXTRACTED
WAITING_VALIDATION
READY_TO_SYNC
SYNCING_QUIVER
COMPLETED
FAILED
RETRYING
ARCHIVED

7. Redis

Redis será usado para evitar acessos repetitivos ao banco do Flwe durante uma automação.

Uso:

snapshots temporários;
cache;
locks;
contexto de task;
redução de consultas ao Flwe.

Estratégia

[Diagram]

Exemplo de chave

automation:task:{task_id}:context

Dados possíveis no Redis

{
  "task_id": "uuid",
  "proposal_id": "123",
  "customer_name": "Cliente Exemplo",
  "document": "policy.pdf",
  "insurer": "HDI",
  "product": "Auto",
  "status": "DOCUMENT_EXTRACTED",
  "attempts": 2,
  "last_error": null
}

Redis é cache e estado temporário.
A fonte definitiva continua sendo o banco do Flwe e/ou banco operacional da automação.

8. RabbitMQ

RabbitMQ será usado para processamento assíncrono robusto.

Uso:

filas;
retries;
distribuição;
DLQ;
processamento assíncrono.

[Diagram]

9. Crawlers

Estratégia:

API oficial;
Firecrawl;
Playwright;
SeleniumBase.

Funções:

login;
navegação;
download;
monitoramento;
consulta;
fallback.

10. Fluxo Principal do MVP — Vida e Saúde

[Diagram]

11. Fluxo de Crawlers por Seguradora

[Diagram]

12. Diagramas de Sequência dos Fluxos Operacionais

Os diagramas anteriores mostram a arquitetura e os fluxos em alto nível.
Os diagramas de sequência abaixo detalham quem chama quem, em qual ordem, e como os serviços interagem durante a execução real.

Essa seção é importante para alinhar o comportamento esperado entre desenvolvimento, infraestrutura, gestão do projeto e evolução futura da solução.

12.1 Sequência — MVP Vida e Saúde: E-mail/PDF até Quiver

Este fluxo representa a primeira entrega recomendada para o MVP, focada em documentos recebidos por e-mail, extração de dados e atualização do Quiver.

[Diagram]

12.2 Sequência — Validação Manual no Flwe

Este fluxo acontece quando a extração automática não tem confiança suficiente ou quando os dados extraídos não batem com as regras esperadas.

[Diagram]

12.3 Sequência — Crawler com Firecrawl e Fallback

Este fluxo representa a execução dos crawlers para portais de seguradoras.
O Firecrawl é tratado como ferramenta principal candidata, com fallback para Playwright e SeleniumBase.

[Diagram]

12.4 Sequência — Uso do Redis como Snapshot Temporário

Este fluxo mostra como evitar consultas repetidas ao banco do Flwe durante a mesma automação.

[Diagram]

12.5 Sequência — RabbitMQ, Retry e Dead Letter Queue

Este fluxo mostra como as tarefas serão distribuídas para workers e como falhas recorrentes serão tratadas.

[Diagram]

12.6 Sequência — Reprocessamento Manual de uma Tarefa

Este fluxo mostra como um operador ou usuário técnico pode solicitar retry manual após corrigir dados ou identificar falha temporária.

[Diagram]

13. Clean Architecture

[Diagram]

14. Estrutura de Pastas

src/                                  # Código-fonte principal da aplicação.

  domain/                             # Camada mais importante. Contém regras puras de negócio.
    entities/                         # Objetos com identidade e ciclo de vida.
                                      # Ex: AutomationTask, Policy, Proposal, Insurer, Document.

    value_objects/                    # Objetos imutáveis que representam valores do domínio.
                                      # Ex: CPF, CNPJ, Money, PolicyNumber, TaskStatus, ConfidenceScore.

    repositories/                     # Interfaces de persistência que o domínio espera.
                                      # Ex: TaskRepository, PolicyRepository, DocumentRepository.

    services/                         # Regras de negócio que não pertencem a uma única entidade.
                                      # Ex: PolicyMatchingService, CommissionRuleService, ValidationService.

  app/                                # Camada de aplicação. Coordena casos de uso.
    use_cases/                        # Ações que o sistema executa.
                                      # Ex: ProcessIncomingEmail, ExtractDocumentData, SyncWithQuiver.

    dto/                              # Objetos de entrada e saída entre camadas.
                                      # Ex: ExtractedPolicyDTO, CreateAutomationTaskDTO.

    ports/                            # Contratos para comunicação com mundo externo.
                                      # Ex: EmailPort, QuiverPort, CrawlerPort, StoragePort, QueuePort.

  infrastructure/                     # Implementações concretas e detalhes técnicos.
    database/                         # SQLAlchemy/SQLModel, conexões, migrations e repositories concretos.

    queues/                           # RabbitMQ, producers, consumers, retries e dead-letter queue.

    crawlers/                         # Firecrawl, Playwright, SeleniumBase e crawlers por seguradora.

    email/                            # IMAP, Gmail API, Microsoft Graph ou outro provedor de e-mail.

    quiver/                           # Cliente de API ou automação para integração com Quiver.

    storage/                          # PDFs, arquivos baixados, documentos processados e logs brutos.

  presentation/                       # Camada de entrada e saída.
    api/                              # Rotas FastAPI, controllers, dependencies e middlewares.

    workers/                          # Entrypoints de execução assíncrona.
                                      # Ex: email_worker.py, document_worker.py, crawler_worker.py.

    schemas/                          # Schemas Pydantic específicos de request/response da API.

15. Diagramas de Classes

O Diagrama de Classes abaixo representa uma primeira visão do domínio da automação.

Ele não tem o objetivo de definir todos os atributos finais do banco de dados, mas sim mostrar as principais entidades, objetos de valor, serviços de domínio e contratos que sustentam a arquitetura.

Beautiful Mermaid

[Diagram]

15.1 Diagrama de Classes por Camada

Este diagrama mostra como as classes podem ser organizadas dentro da Clean Architecture.

Beautiful Mermaid

[Diagram]

15.3. Observação Sobre o Diagrama de Classes

O Diagrama de Classes deve ser tratado como uma visão inicial do design, não como contrato definitivo de implementação.

Durante a implementação, algumas classes podem ser divididas, renomeadas ou simplificadas conforme:

evolução do entendimento do domínio;
estrutura real do banco do Flwe;
disponibilidade da API do Quiver;
complexidade dos PDFs;
complexidade dos portais das seguradoras;
decisões de MVP.

16. ERD — Modelo de Dados da Automação

Diferente do Diagrama de Classes, que representa o código Python e o domínio da aplicação, o ERD abaixo representa uma sugestão inicial de tabelas próprias da camada de automação.

Como o banco do Flwe já existe, este modelo não tenta substituir nem redesenhar o banco atual.
A ideia é criar apenas tabelas auxiliares para controle da automação, rastreabilidade, documentos, retries e integração com os fluxos existentes do Flwe.

16.1 Separação entre Banco Flwe e Tabelas da Automação

[Diagram]

16.2 Propósito de Cada Tabela

Tabela	Propósito
`automation_task`	Controlar cada automação executada
`automation_task_event`	Registrar trilha de auditoria e eventos da tarefa
`automation_document`	Registrar documentos recebidos ou baixados
`extracted_data`	Guardar dados extraídos dos PDFs/documentos
`manual_validation`	Controlar validações humanas realizadas no Flwe
`quiver_sync`	Registrar tentativas de cadastro/atualização no Quiver
`automation_retry`	Registrar histórico de tentativas e reprocessamentos
`insurer_config`	Configurar seguradoras, portais e estratégia de crawler
`credential_reference`	Referenciar credenciais protegidas em cofre/secret manager
`crawler_execution`	Registrar execuções dos crawlers por seguradora

16.3 Observação Sobre o Banco do Flwe

As entidades FLWE_PROCESS e FLWE_USER no ERD são representações simbólicas.

Elas indicam que a automação terá relacionamento com dados já existentes no Flwe, mas o nome real das tabelas dependerá da estrutura atual criada pelo Emerson.

Na implementação, essas referências podem apontar para:

tabela de processos;
tabela de solicitações;
tabela de tarefas;
tabela de usuários;
tabela de clientes;
tabela de propostas;
tabela de documentos;
ou outra estrutura já existente no Flwe.

16.4 Estratégia Recomendada para Banco

A recomendação é evitar misturar tudo diretamente nas tabelas principais do Flwe.

Preferência:

Banco Flwe existente
  ├── tabelas atuais do Flwe
  └── schema separado para automação
        ├── automation_tasks
        ├── automation_documents
        ├── extracted_data
        ├── manual_validations
        ├── quiver_syncs
        ├── crawler_executions
        └── audit_events

Exemplo:

CREATE SCHEMA automation;

Isso mantém:

baixo acoplamento;
organização;
facilidade de manutenção;
rastreabilidade;
menor risco de quebrar o Flwe existente.

17. Evolução MVP -> Microserviços

[Diagram]

18. Observabilidade

logs estruturados;
tracing;
métricas;
auditoria;
histórico operacional.

19. Conclusão

A arquitetura foi desenhada para:

começar simples;
entregar rápido;
suportar crescimento;
manter baixo acoplamento;
permitir evolução gradual;
manter rastreabilidade operacional.

20. Ajustes de Alinhamento com as Reuniões

Após revisão das transcrições, resumos e mapa mental, os detalhes adicionados permanecem altamente alinhados com o que foi discutido nas reuniões.

Os principais pontos confirmados:

início focado em Vida e Saúde;
arquitetura evolutiva;
separação clara entre Flwe e automação;
uso de filas para evitar sobrecarga;
retries e rastreabilidade;
necessidade de validação manual;
crawlers por seguradora;
controle operacional e auditoria;
possibilidade de alto volume operacional em dias específicos;
OCR e IA para PDFs complexos;
integração prioritária via API quando possível.

20.1 Ajuste Importante — MVP

Apesar da proposta apresentar uma visão completa de microserviços e múltiplos workers, a recomendação continua sendo:

iniciar como modular monolith;
manter separação lógica das camadas;
separar serviços fisicamente apenas quando houver necessidade operacional real.

Isso mantém aderência ao que foi discutido sobre:

evitar overengineering;
entregar rápido;
reduzir complexidade inicial.

20.2 Ajuste Importante — Firecrawl

O Firecrawl continua sendo uma excelente opção candidata principal para crawling e extração.

Porém, conforme discutido tecnicamente:

nem todos os portais poderão funcionar apenas com Firecrawl;
alguns fluxos podem exigir automação browser real;
CAPTCHAs e interações complexas podem exigir Playwright ou SeleniumBase.

Por isso, a arquitetura mantém fallback progressivo:

API oficial;
Firecrawl;
Playwright;
SeleniumBase.

20.3 Ajuste Importante — Banco do Flwe

O ERD apresentado representa apenas a camada complementar da automação.

O banco principal do Flwe:

continuará sendo mantido pelo sistema atual;
não será substituído;
não será redesenhado pela automação.

A automação apenas:

consulta dados necessários;
registra rastreabilidade;
salva contexto operacional;
registra auditoria;
controla retries e workflows.

21. Revisão Técnica Final de Coerência

Após nova revisão comparando:

reuniões;
mapa mental;
alinhamentos técnicos;
decisões de MVP;
estratégia incremental;

a proposta permanece muito coerente e ainda mais madura arquiteturalmente.

21.1 Pontos Fortes Acrescentados

Os novos detalhes adicionados melhoraram significativamente:

clareza operacional;
rastreabilidade dos fluxos;
entendimento dos workers;
entendimento das filas;
entendimento do Redis;
detalhamento dos diagramas de sequência;
visão real de execução da automação;
entendimento do fallback entre crawlers;
separação entre domínio e infraestrutura;
previsibilidade de evolução do MVP.

21.2 Ajuste Recomendado — RabbitMQ na Fase 1

Na seção de roadmap, RabbitMQ aparece apenas na Fase 3.

Porém, como os fluxos já dependem diretamente de:

filas;
retries;
distribuição de tarefas;
workers assíncronos;

o RabbitMQ deve ser considerado parte do MVP inicial.

A recomendação ajustada é:

RabbitMQ presente desde a Fase 1;
evolução posterior apenas em escala, tuning e observabilidade avançada.

21.3 Ajuste Recomendado — LangGraph

O uso do LangGraph está muito alinhado com o objetivo da solução.

Porém, é importante deixar explícito que:

o LangGraph NÃO substitui filas;
NÃO substitui workers;
NÃO substitui RabbitMQ.

Ele atua como:

orquestrador de estados;
coordenador do workflow;
controlador de decisões;
motor de transição entre etapas.

RabbitMQ continua responsável por:

entrega;
distribuição;
desacoplamento;
retries;
DLQ.

21.4 Ajuste Recomendado — Escopo do MVP

Os diagramas ficaram extremamente ricos, o que é excelente para visão futura.

Porém, para evitar interpretação equivocada por stakeholders não técnicos, recomenda-se reforçar que:

nem todos os fluxos serão implementados imediatamente;
vários diagramas representam arquitetura-alvo;
o MVP inicial continuará simples e incremental.