Arquitetura Serverless

O sistema utiliza uma arquitetura serverless na AWS, composta por funções Lambda, API Gateway, EventBridge, RDS PostgreSQL e SQS.

Componentes Principais

Integrações Externas

• Salesforce API: Busca de casos e informações de clientes
• Elfa Services API: Busca de pedidos, boletos e notas fiscais
• OpenAI API: Classificação de casos e geração de conteúdo de email
• AWS SES: Envio de emails transacionais

VPC e Segurança

O Lambda está configurado para executar dentro de uma VPC para acesso seguro ao RDS PostgreSQL. Security Groups e Subnets são configurados para garantir isolamento e segurança.

Core Framework

Serverless Framework

Banco de Dados

Integrações e APIs

Observabilidade

Estrutura de Diretórios

elfa-ai-mail-service/
├── src/
│   ├── app.module.ts              # Módulo principal da aplicação
│   ├── main.ts                    # Entry point para desenvolvimento local
│   ├── lambda.ts                  # Handler Lambda para API Gateway
│   ├── cron-handler.ts            # Handler Lambda para EventBridge
│   ├── modules/
│   │   └── process-message/       # Módulo de processamento de mensagens
│   │       ├── controllers/       # Controllers REST
│   │       ├── services/          # Lógica de negócio
│   │       └── process.module.ts
│   └── shared/
│       ├── database/              # Configuração e repositórios do banco
│       │   ├── schema.ts          # Schema Drizzle ORM
│       │   ├── repositories/      # Repositórios de dados
│       │   └── handlers/          # Handlers de log
│       └── providers/             # Provedores de serviços externos
│           ├── sales-force/       # Integração Salesforce
│           ├── elfa-services/    # Integração Elfa Services
│           ├── open-ai/           # Integração OpenAI
│           └── mailer/            # Configuração de email
├── test/                          # Testes end-to-end
├── scripts/                       # Scripts auxiliares
├── serverless.yml                 # Configuração Serverless Framework
├── drizzle.config.ts              # Configuração Drizzle ORM
├── package.json                   # Dependências e scripts
└── tsconfig.json                  # Configuração TypeScript

Módulos Principais

Schema do Banco de Dados

Gerenciamento de Credenciais

• Variáveis de Ambiente: Todas as credenciais são gerenciadas via variáveis de ambiente, nunca commitadas no código
• AWS Secrets Manager: Recomendado para produção (pode ser implementado)
• Rotacao de Credenciais: Implementar rotacao periodica de credenciais de APIs externas

VPC e Network Security

• VPC Configuration: Lambda executando dentro de VPC para acesso seguro ao RDS
• Security Groups: Configurados para permitir apenas trafego necessario
• Subnets: Isolamento de rede em subnets privadas
• Principio do Menor Privilegio: Aplicado em todas as configuracoes de rede

IAM e Permissões

• Principio do Menor Privilegio: Permissoes IAM especificas apenas para recursos necessarios
• Permissoes Granulares:
  • SQS: SendMessage, ReceiveMessage, DeleteMessage, GetQueueUrl
  • RDS: Acesso apenas ao banco especifico do projeto
• Sem Permissoes Administrativas: Nenhuma permissao de administrador concedida

API Gateway Security

• CORS: Configurado adequadamente para permitir apenas origens autorizadas
• Autenticacao: Considerar implementacao de autenticacao JWT se necessario
• Rate Limiting: Considerar implementacao de rate limiting para protecao contra abuso

Dados Sensiveis

• PDFs em Base64: Armazenados no banco de dados, considerar encriptacao se necessario
• Logs: Nenhum dado sensivel (senhas, tokens) deve ser logado
• Transmissao: Todas as comunicacoes via HTTPS/TLS

AWS X-Ray

Tracing distribuido habilitado no Lambda para rastrear latencia de cada componente e identificar gargalos no processamento.

• Rastreamento de todas as chamadas de API externas
• Medicao de tempo de execucao de cada etapa
• Identificacao de dependencias e integracoes

CloudWatch Logs

Logs centralizados com retencao de 30 dias configurada. Todos os logs sao estruturados para facil analise.

• Logs de execucao do Lambda
• Logs de erros e excecoes
• Logs de processamento de casos
• Logs de envio de emails

Logs Customizados no Banco

Tabela logs no banco de dados para auditoria detalhada, incluindo metricas de tempo, erros e metadados de cada processamento.

• totalResponseTime: Tempo total de processamento
• metadata: Informacoes contextuais do processamento
• errors: Array de erros (se houver)
• sendingId: Relacao com o envio processado

Metricas Importantes

Alertas Recomendados

Dashboards Recomendados

• Dashboard de Performance: Latencia, throughput e tempo de resposta
• Dashboard de Erros: Taxa de erro por tipo e tendencias
• Dashboard de Integracoes: Status e latencia de APIs externas
• Dashboard de Negocio: Casos processados, emails enviados, taxa de sucesso