A Arquitetura Por Trás do Hub de Identidade Digital: PostgreSQL, FastAPI, SNS e SQS em Produção

O Problema Real

Toda empresa que cresce acaba com o mesmo cenario: varios sistemas que nao se conversam.

O CRM sabe que o cliente existe. O ERP sabe que a empresa dele tem CNPJ. O juridico sabe que o contrato foi assinado. O financeiro sabe que a cobranca esta ativa. Mas nenhum deles sabe tudo ao mesmo tempo.

O resultado pratico:

• O comercial liga pro cliente pedindo um documento que o juridico ja recebeu
• O financeiro libera cobranca pra um franqueado que ainda nao assinou contrato
• O diretor pede um relatorio de "quantos franqueados temos" e recebe tres numeros diferentes de tres sistemas diferentes
• Quando um dado muda (o cliente atualiza o endereco), alguem precisa entrar em cada sistema e atualizar manualmente

Isso nao e um problema de tecnologia. E um problema de arquitetura. Cada sistema foi comprado ou construido isoladamente, e a "integracao" entre eles e uma pessoa copiando dado de uma tela pra outra.

O Hub de Identidade Digital existe pra resolver isso.

A Solucao em Uma Frase

Um unico sistema centraliza a identidade de pessoas, empresas e seus vinculos, e avisa automaticamente todos os outros sistemas quando algo muda.

Parece simples. A execucao e que exige decisoes tecnicas bem pensadas. Vamos a cada peca.

A Arquitetura: 5 Pecas Que Conversam em Sequencia

PostgreSQL (RDS) <- API Hub (ECS) -> SNS -> SQS -> Consumidores (Workers)

O dado entra pela API, e persistido no banco, e a partir dai o sistema publica um evento. Esse evento e distribuido pra todos os sistemas que precisam saber. Ninguem precisa perguntar. Ninguem precisa ficar checando.

Vamos olhar cada peca.

1. PostgreSQL (AWS RDS): A Fonte Unica de Verdade

O que faz: Armazena tudo. Clientes, empresas, vinculos entre eles, documentos enviados e o historico completo de tudo que aconteceu.

Por que PostgreSQL: E o banco relacional mais robusto do mercado open-source. Suporta JSON nativo (usado pra armazenar flags, enderecos, dados da Receita Federal), tem transacoes ACID (garante que o dado nunca fica pela metade), e escala verticalmente com facilidade.

Por que AWS RDS e nao um banco instalado num servidor: RDS e o PostgreSQL gerenciado pela AWS. Isso significa:

• Backup automatico diario
• Failover automatico (se o servidor cair, outro assume em minutos)
• Patches de seguranca aplicados sem downtime
• Monitoramento integrado (CPU, memoria, conexoes, queries lentas)

Instalar um PostgreSQL na mao significa que alguem da equipe vira "DBA acidental", acordando 3h da manha quando o disco enche. Com RDS, isso e problema da AWS.

O que mora dentro

• Cliente: nome, email, CPF, telefone, endereco, nivel de qualificacao
• Empresa: CNPJ, 19 campos da Receita Federal, quadro societario, nivel de verificacao
• Vinculo: a relacao entre uma pessoa e uma empresa, com flags de validacao e nivel de progressao
• Historico: cada mudanca que ja aconteceu, quem mudou, quando, o que era antes, o que ficou depois

Esse historico e imutavel. Ninguem edita, ninguem deleta. Cada linha e um fato que aconteceu. Isso e fundamental pra auditoria e LGPD.

2. API Hub de Identidade (FastAPI no AWS ECS): O Cerebro

O que faz: Recebe requisicoes HTTP, valida os dados, aplica as regras de negocio, salva no banco e dispara os eventos.

Por que FastAPI

1. Async nativo. Quando a API precisa consultar a Receita Federal ou publicar um evento na fila, ela nao fica travada esperando a resposta. Libera a thread pra atender outra requisicao enquanto espera. Isso e critico pra performance sob carga.

2. Validacao automatica com Pydantic. Cada endpoint tem um schema tipado. Se o CPF vier no formato errado, a API rejeita antes de tocar no banco. Sem if manual pra cada campo.

3. Documentacao gerada automaticamente. O Swagger/OpenAPI e gerado pelo framework. Qualquer sistema que precise integrar sabe exatamente quais endpoints existem, quais campos sao obrigatorios, e quais respostas esperar.

Por que AWS ECS

ECS e o servico de containers da AWS. A API roda dentro de um container Docker, e o ECS cuida de:

• Escalar horizontalmente: se a carga aumenta, sobe mais containers automaticamente
• Health checks: se um container trava, mata e sobe outro
• Deploy sem downtime: atualiza a versao gradualmente, container por container
• Logs centralizados: tudo vai pro CloudWatch automaticamente

A alternativa seria rodar num EC2 (maquina virtual), mas ai voce gerencia o sistema operacional, os patches, o monitoramento. ECS abstrai tudo isso.

O Motor de Regras: o diferencial

A API carrega um arquivo YAML que define as regras de progressao. Quando um dado muda (por exemplo, o cliente envia o documento de CPF), o motor reavalia automaticamente em que nivel aquele vinculo esta.

O ponto critico: as regras nao estao no codigo. Estao num arquivo de configuracao. Se amanha a empresa decide que franqueados precisam de biometria validada, basta adicionar uma linha no YAML. Nenhum programador precisa alterar codigo. Nenhum deploy precisa acontecer. O motor le as regras e se adapta.

Isso inverte a dinamica tradicional onde cada mudanca de regra vira um ticket de TI com estimativa de 2 sprints.

3. AWS SNS (Simple Notification Service): O Megafone

O que faz: Recebe um evento da API e distribui pra todos que precisam ouvir.

Como funciona na pratica: Quando a API salva uma mudanca (por exemplo, o contrato foi assinado), ela publica uma mensagem no SNS com uma routing key como vinculo.flag.contrato_assinado.

O SNS funciona como um megafone: ele nao sabe nem se importa com quem esta ouvindo. Ele so grita a mensagem. Quem quiser ouvir, se inscreve.

Por que SNS e nao mandar direto pra cada sistema

Se a API mandasse diretamente pro CRM, pro ERP e pro financeiro, ela precisaria:

• Saber que esses sistemas existem (acoplamento)
• Esperar cada um responder (lentidao)
• Lidar com falhas de cada um (se o CRM cair, a API trava?)

Com SNS no meio, a API tem um unico destino. Publica e segue. Se amanha aparecer um quarto sistema que precisa saber sobre contratos assinados, ele se inscreve no SNS. A API nao muda.

Esse padrao se chama fan-out: uma mensagem entra e sai pra N destinos.

4. AWS SQS (Simple Queue Service): O Buffer de Seguranca

O que faz: Recebe as mensagens do SNS e as guarda numa fila ate que o consumidor esteja pronto pra processar.

Por que nao entregar direto do SNS pro consumidor

Porque sistemas caem. Ficam lentos. Reiniciam. Se o CRM estiver fora do ar quando o SNS disparar o evento, a mensagem se perde. O SQS resolve isso:

• Persistencia: a mensagem fica na fila ate ser explicitamente confirmada como processada
• Retry automatico: se o consumidor falha ao processar, a mensagem volta pra fila e tenta de novo
• Dead Letter Queue: se falhar N vezes, vai pra uma fila separada pra investigacao (nunca some silenciosamente)
• Desacoplamento temporal: o produtor e o consumidor nao precisam estar online ao mesmo tempo

Cada sistema tem sua propria fila

Se o CRM ficar fora 2 horas, as mensagens acumulam na fila dele. Quando voltar, processa tudo em sequencia. Nenhum dado se perde. Nenhum outro sistema e afetado.

5. Consumidores (Workers / Webhooks): Quem Reage

O que fazem: Ficam ouvindo suas filas SQS e executam acoes quando uma mensagem chega.

Exemplos concretos

• Worker CRM: Recebe vinculo.criado.vinculado, cria o lead no CRM com os dados que vieram no payload. Recebe cliente.updated, atualiza o cadastro no CRM.
• Worker ERP: Recebe vinculo.flag.contrato_assinado, cria o cadastro fiscal da empresa no ERP. Recebe cliente.updated, sincroniza nome e endereco.
• Worker Storage: Recebe cliente.document.uploaded, copia o arquivo pro bucket de backup com versionamento.

O ponto critico: Cada worker e independente. Se o worker do CRM tiver um bug e parar, o ERP e o storage continuam funcionando normalmente. Nao existe efeito domino.

Como adicionar um novo sistema

Amanha a empresa contrata um novo software de compliance. Pra integrar:

• Cria uma fila SQS nova (fila-compliance)
• Configura o filtro (quais eventos quer ouvir)
• Escreve um worker que consome dessa fila

A API nao muda. O SNS nao muda. O banco nao muda. Nenhum sistema existente e afetado. O novo sistema simplesmente se pluga na infraestrutura que ja existe.

O Fluxo Completo: Do Clique ao CRM

Vamos seguir uma acao real de ponta a ponta.

O comercial clica "Assinar Contrato" no sistema interno:

• O sistema envia POST /clientes/{id}/vinculos/{cnpj}/flags/contrato_assinado pra API
• A API valida que a flag contrato_assinado existe no YAML
• Grava a flag no vinculo (banco PostgreSQL via RDS)
• Cria um registro no historico: "flag contrato_assinado ativada, origem: site, 14:32:07"
• O motor de regras reavalia: o vinculo tinha nivel "validado", agora tem todas as condicoes pra "assinante", atualiza o nivel
• Cria outro registro no historico: "nivel atualizado de validado para assinante"
• Publica no SNS: vinculo.flag.contrato_assinado com o payload completo (dados do cliente, empresa, vinculo)
• O SNS distribui pra todas as filas inscritas
• A fila do CRM recebe, o worker atualiza o status do deal
• A fila do ERP recebe, o worker cria o cadastro fiscal
• A fila de compliance recebe, o worker registra o aceite contratual

Tempo total: menos de 2 segundos. Intervencao humana: zero apos o clique. Sistemas que precisaram ser modificados pra isso funcionar: zero, cada um ja estava ouvindo.

O Que Essa Arquitetura Resolve (De Verdade)

Por Que Cada Decisao Foi Tomada

A arquitetura nao e complexa por vaidade tecnica. Cada camada existe pra resolver um problema especifico:

• PostgreSQL porque os dados sao relacionais (pessoa TEM vinculos COM empresa) e precisam de consistencia transacional
• RDS porque ninguem quer ser DBA as 3h da manha
• FastAPI porque a API precisa ser async (consultas externas) e auto-documentada (integracao com terceiros)
• ECS porque a API precisa escalar sem gerenciar servidores
• SNS porque a API nao pode saber nem se importar com quem consome os eventos
• SQS porque mensagens nao podem se perder quando um consumidor esta fora
• Workers separados porque a falha de um sistema nao pode derrubar os outros

Tirar qualquer camada cria um problema. Adicionar outra camada criaria complexidade desnecessaria. E o minimo necessario pra resolver o problema completo.

Resumo Tecnico

O Hub de Identidade Digital nao e "mais um sistema". E a camada de identidade que faltava entre os sistemas que a empresa ja tem.

Ele nao substitui o CRM, o ERP ou o juridico. Ele alimenta todos eles com uma unica fonte de verdade, em tempo real, sem intervencao manual, com rastreabilidade total.

A infraestrutura foi desenhada pra que:

• Nada se perca (filas com retry e dead letter)
• Nada dependa de nada (sistemas desacoplados via eventos)
• Nada precise parar pra mudar (regras em YAML, deploy sem downtime)
• Tudo seja rastreavel (historico imutavel de cada mudanca)

Se a empresa crescer de 50 pra 500 franqueados, a arquitetura escala horizontalmente. Se aparecerem 3 novos sistemas pra integrar, eles se plugam sem tocar no que ja existe. Se uma regra de negocio mudar, um arquivo de configuracao resolve.

"O custo de nao ter isso e invisivel, ate o dia que aparece como retrabalho, dado errado, cliente insatisfeito ou auditoria sem resposta."