Visão lógica da aplicação¶
Recomendado para leitura prévia
- Arquitetura de negócio — atores, blocos e contratos macro.
- Modelo de domínio — bounded contexts e agregados.
Objetivo arquitetural¶
Construir um pipeline Text-to-SQL reprodutível que consulte metadados por MCP antes da geração de SQL, com validação estrutural, execução controlada e rastreabilidade completa por corrida.
Camadas¶
| Camada | Responsabilidade |
|---|---|
| Edge/API | Recebe a pergunta, valida entrada e gera runId. |
| Application | Executa os casos de uso DiscoverMetadata, GenerateSql, ValidateAndExecute, RecordRun. |
| Domain | Aplica regras de aderência estrutural, orçamento de tool calls e critérios de rastreabilidade. |
| Infrastructure | Adapters para MCP, Atlas, Apache Calcite (parse HiveQL), banco PS (Hive) e persistência de evidências. |
| Observability | Trilhas JSONL, métricas essenciais e metadados de reprodutibilidade. |
Casos de uso principais¶
DiscoverMetadataUseCase: consulta tools MCP sob orçamento.GenerateSqlUseCase: pede ao LLM o SQL candidato com base no snapshot de metadados.ValidateAndExecuteUseCase: parse sintático via Apache Calcite (dialeto Hive), validação estrutural e execução controlada.RecordRunUseCase: consolida trilha JSONL e métricas.
Fluxo operacional (passo a passo)¶
- Pergunta em linguagem natural chega ao Edge.
- Descoberta dirigida de metadados por tools MCP.
- Geração de SQL ancorada no contexto recuperado.
- Validação sintática via Apache Calcite (dialeto Hive) e validação estrutural.
- Execução controlada no subconjunto PS (92 tabelas).
- Registro de trilha e cálculo de métricas.
Diagrama:
Fonte: Diagrama mestre — fluxo lógico
Zonas lógicas de rede¶
| Zona lógica | Componentes | Política |
|---|---|---|
NetPublic |
Entrada HTTP do orquestrador. | Único ponto de entrada externo. |
NetInternalApp |
Aplicação, MCP, adaptadores. | Tráfego privado, deny by default para fora. |
NetDataPlane |
Apache Atlas, banco PS no cluster. | Acessível apenas pelo validador/executor e pelo adaptador Atlas. |
NetObservability |
Armazenamento de evidências e métricas. | Escrita por runId, sem sobrescrita. |
Diagrama lógico:
Fonte: Diagrama de rede lógica. Para a tradução física para AWS, ver Visão AWS.
Padrões de engenharia¶
- Arquitetura hexagonal por contexto (
ports and adapters). - Contratos MCP versionados semanticamente.
- Timeouts e retry com backoff para integrações externas.
- Falhas classificadas em
syntax_error,structural_error,execution_error. - Servidor MCP nunca acessa o banco PS; apenas o validador/executor.
Recomendado para leitura posterior
Seguinte: Camadas MCP — mapeamento tool → porta → contrato → erro.