Arquitetura (modelo C4)

Visão em três níveis do sistema em produção e da arquitetura-alvo (Aquila 3.0).

Nível 1 · Contexto

Quem usa o Aquila e com quais sistemas externos ele conversa.

Nível 2 · Contêineres

Executados no Google Cloud (us-central1), com Cloud Run, Cloud SQL, Cloud Storage e KMS.

Contêiner	Tecnologia	Responsabilidade
Web App	React, Vite, Tailwind	Telas da carteira, módulos e agente
API Backend	Node.js, Express, SQL parametrizado	Autorização, regras de negócio, conciliação, cofre, Open Finance
Agente de IA	Python, DeepAgent/LangGraph, Gemini	Perguntas, investigação somente leitura e memória por empresa
Workers	Node.js/Python	OCR, extração, indexação para busca
PostgreSQL	Cloud SQL 15	Dados de negócio, eventos de uso e trilhas de auditoria
Cofre	Cloud Storage + Cloud KMS	Arquivos originais criptografados e versionados

Entrega contínua: a branch dev publica em homologação e main publica em produção, via Cloud Build. Cada PR roda typecheck, testes e build.

Nível 3 · Componentes da API

Decisões de projeto que sustentam a confiabilidade:

• Dinheiro em centavos inteiros (Money): nenhuma soma de valores em ponto flutuante.
• Datas de competência como objeto próprio, sem parsing ad hoc de datas brasileiras.
• Tabelas de auditoria somente inclusão: correções viram novos registros.
• Suítes de conciliação com dados reais, rodadas antes de qualquer mudança no núcleo.

Arquitetura-alvo · Aquila 3.0 (em especificação)

Proposta em especificação desde 01/10/2026. Ainda não está em produção.

Camada	Proposta
Estrutura	Monólito modular Python + frontend React, um pacote para API, MCP, workers e agendador
Agentes	Especialistas (jurídico, financeiro, RH, regulatório) com citação literal do documento original e revisão humana
Dados	PostgreSQL + pgvector; eventos de domínio e projeções
Assíncrono	Celery + Redis + Beat
Identidade	Login gerenciado; capacidades decididas pelo backend por projeto
Implantação	Docker Compose com TLS e armazenamento S3-compatível