Financial Agent - Arquitetura Completa do Sistema
Este documento descreve a arquitetura completa do Financial Agent, uma plataforma SaaS multi-tenant para análise financeira automatizada com IA, construída com Clean Architecture, DDD, FastAPI, Next.js 14, PostgreSQL e agentes de IA via LangGraph e múltiplos LLMs.
1.Visão Geral da Solução
O Financial Agent é uma solução corporativa que automatiza a interpretação de Demonstrativos de Resultado (DRE), gera insights estratégicos, elabora projeções e identifica riscos financeiros usando modelos de linguagem avançados.
Principais componentes:
- Backend: FastAPI + Clean Architecture + DDD
- Frontend: Next.js 14 + React 18
- Banco de Dados: PostgreSQL com políticas de Row-Level Security (RLS)
- IA: LangGraph + OpenAI/Groq/Anthropic
- Multi-tenancy corporativo
- Autenticação JWT + RBAC
- Containerização com Docker
2.Arquitetura do Backend
2.1 Clean Architecture
A arquitetura segue quatro camadas claras:
External Layer → Interface Adapters → Application Layer → Domain Layer
2.2 Destaques Técnicos
- Separação completa entre domínio e infraestrutura
- Repositórios e Unit of Work para transações
- Casos de uso totalmente desacoplados
- Entidades de domínio independentes de tecnologia
2.3 Padrões Utilizados
| Padrão | Local |
|---|---|
| Repository | /infrastructure/repositories |
| Unit of Work | /infrastructure/database/unit_of_work.py |
| Strategy (LLMs) | /infrastructure/llm/providers |
| Factory | /api/dependencies |
| Facade | /application/services |
3.Multi-Tenancy com Isolamento de Alto Nível
O sistema utiliza Shared Database + Shared Schema com Row-Level Security, garantindo segurança corporativa e escalabilidade linear.
Camadas de defesa:
- Middleware extrai tenant do JWT
- Application Layer define
current_tenant - Banco aplica RLS e impede vazamento entre organizações
4.Sistema de Autenticação e RBAC
Autenticação
- JWT Access + Refresh Tokens
- bcrypt para hashing
- Tokens manipulados com segurança
Autorização
Cinco papéis principais:
- Master Admin
- Owner
- Admin
- Analyst
- Viewer
Com matriz de permissões granular.
5.Arquitetura de IA com LangGraph
Agentes
- DRE Analyzer
- Financial Advisor
- Comparison Agent
Fluxo do Agente
- Carrega DRE
- Limpa e padroniza dados
- Extrai insights via LLM
- Gera projeções
- Calcula métricas determinísticas
- Retorna recomendações
Provedores LLM
- OpenAI (GPT-4o)
- Groq (Llama 3)
- Anthropic (Claude)
Com fallback automático.
6.Arquitetura do Frontend
Tecnologias
- Next.js 14 (App Router)
- React 18
- Zustand, React Query
- Zod + React Hook Form
- Shadcn-UI
- Recharts + Framer Motion
Áreas Principais
- Landing pública
- Autenticação
- Dashboard completo
- Empresas, DREs, Análises
- Organização e permissões
7.Modelo de Dados
Entidades principais:
- organizations
- users
- memberships
- companies
- dres
- financial_analyses
- audit_logs
- invitations
Modelagem orientada ao domínio financeiro, com normalização adequada.
8.Deployment e Infraestrutura
Stack de Deploy
- Docker Compose
- PostgreSQL 16
- Redis (planejado)
- Variáveis .env isoladas
Preparado para:
- autoscale
- pipelines CI/CD
- monitoramento e APM
9.Segurança
Implementado
- RLS
- JWT
- RBAC
- Pydantic Validation
- Logs estruturados
- Middleware de tenant
Recomendado
- Rate limiting
- OpenTelemetry
- 2FA
- Cache distribuído
10.Conclusão
A arquitetura do Financial Agent representa um sistema:
- moderno
- escalável
- seguro
- aderente a padrões corporativos
- preparado para operar como SaaS financeiro
Com Clean Architecture, multi-tenancy avançado, agentes de IA orquestrados e um frontend profissional, a plataforma demonstra maturidade técnica acima da média do mercado.
OBS: Ainda em construção, em breve compartilho o link para testes.
