Arquitetura de Dados e Sistemas de Alta Performance

1. Visão Geral

O SIAV é uma solução de auditoria de dados em larga escala que integra técnicas de Data Engineering com IA Generativa. O sistema automatiza a identificação de anomalias em gastos públicos, processando milhões de registros de viagens com foco em performance e precisão semântica.

2. Arquitetura do Software (Clean Architecture)

O projeto segue princípios de Domain-Driven Design (DDD) para garantir manutenibilidade e separação de interesses:

• app/core: Gestão de configurações globais, logging estruturado e ciclo de vida da aplicação (startup/settings).
• app/domain: Contém a lógica de negócio central (audit.py), independente de frameworks ou ferramentas externas.
• app/infrastructure: Camada de baixo nível que gerencia o motor de dados (data_engine.py), integrações com LLM (groq_client.py) e geração de vetores (embedding.py).
• app/services: Orquestra a comunicação entre a infraestrutura e o domínio, realizando o processamento das auditorias.
• app/routers & app/schemas: API baseada em contratos rigorosos para comunicação com o frontend e validação de dados.

3. Stack Tecnológica & Engenharia de Dados

• Linguagem Core: Python 3.13 (foco em performance e concorrência).
• Data Engine: Processamento vetorial e tratamento de datasets massivos (+1M registros).
• IA e RAG: Embeddings para busca de similaridade e detecção de padrões não óbvios; LLMs via Groq para análise qualitativa de justificativas de viagem com ultra-baixa latência.
• Frontend Reativo: SPA (Single Page Application) em Vanilla JS com arquitetura de estado inspirada em Redux (store/reducer), garantindo fluidez no dashboard.

4. Diferenciais de Implementação

• Lazy Evaluation: Otimização de memória no tratamento de dados para evitar gargalos em hardware limitado.
• Segurança e Logs: Middleware de auditoria para rastreabilidade de todas as ações realizadas no sistema.
• Modularidade: Substituição facilitada de componentes de infraestrutura sem afetar a lógica de negócio.

5. Estrutura de Diretórios

├── app/                # BACKEND (Python 3.13)
│   ├── core/           # Configurações, Middlewares e Startup
│   ├── domain/         # Lógica de Negócio e Regras de Auditoria
│   ├── infrastructure/ # Data Engine, Embeddings e Groq (LLM)
│   ├── services/       # Orquestração e Regras de Serviço
│   └── routers/        # Definição de Rotas e Endpoints API
│
└── static/             # FRONTEND (Vanilla JS SPA)
    ├── store/          # Gerenciamento de Estado (Store, Reducer, Actions)
    ├── controllers/    # Lógica de Interação (Event Listeners e Fluxo)
    ├── ui/             # Renderização de Componentes Dinâmicos
    ├── services/       # Cliente de Consumo da API (Fetch/Axios)
    └── domain/         # Definições de Modelos e Entidades do Front

1. Visão Geral

Dashboard analítico de alta performance desenvolvido para converter dados abertos governamentais em inteligência estratégica. O foco está na visualização de tendências, análise de órgãos e perfil de viajantes para otimização de recursos.

2. Arquitetura da Solução

O sistema foi construído com foco em modularidade e velocidade de resposta:

• main_app.py: Ponto de entrada e orquestração do layout principal.
• pages/: Estrutura de navegação multi-página, separando contextos de Auditoria, Análise de Órgãos e Perfil de Viajantes.
• src/ (Engine):
• connector.py: Abstração da camada de dados, garantindo conectividade eficiente com os datasets de viagens.
• discovery.py & profiling.py: Algoritmos de descoberta de dados e análise estatística para geração automática de perfis de gastos.

3. Stack Tecnológica & Engenharia

• Frontend/App Framework: Python (Streamlit) para entrega de interfaces interativas e responsivas.
• Data Processing: Utilização de bibliotecas de alto desempenho (como Polars ou Pandas) para processamento em memória de grandes volumes de dados abertos.
• UI/UX: Componentização customizada (ui.py) para manter a identidade visual e facilitar a manutenção dos elementos gráficos.

4. Diferenciais Técnicos

• Multi-Page Architecture: Organização lógica que permite análises profundas sem sobrecarregar a interface do usuário.
• Data Discovery: Processo automatizado de identificação de padrões e outliers diretamente na ingestão dos dados.
• Performance: Cache de dados e otimização de consultas para garantir transições fluidas entre os dashboards.

5. Estrutura de Diretórios

├── main_app.py         # Orquestrador do App
├── pages/              # Módulos de Visões Estratégicas
├── src/
│   ├── connector.py    # Camada de Acesso aos Dados
│   ├── discovery.py    # Lógica de Mineração de Insights
│   └── profiling.py    # Estatísticas e Perfilamento
└── data/               # Armazenamento de Datasets (Dados Abertos)

1. Visão Geral

Motor de ETL e processamento de dados projetado para suportar o ecossistema GOVBR. O engine gerencia desde a ingestão de dados brutos até a criação de cubos analíticos e vetorização para IA, utilizando uma arquitetura escalável e resiliente.

2. Arquitetura de Dados (Medallion & Pipelines)

O processamento é dividido em camadas lógicas para garantir a qualidade do dado:

• Camada Bronze (csv_to_parquet.py): Ingestão e conversão de formatos brutos para Parquet (otimização de storage e leitura).
• Camada Silver (silver/): Limpeza, padronização de colunas e enriquecimento. Inclui tratamento de passagens, trechos e pagamentos.
• Camada Gold (gold/): Dados agregados e prontos para consumo, seguindo regras de negócio para auditoria e BI.

3. Módulos de Inteligência e Auditoria

O grande diferencial desta engine é a preparação de dados para IA:

• Módulo RAG (audit/rag/): Pipeline de extração de features, geração de vetores e treinamento de IA para identificação de anomalias semânticas.
• Cubo de Auditoria (audit/bi/): Geração de agregados complexos (Rankings, KPIs e Detalhe de Alvos) para alimentar dashboards de alta performance.
• Supabase Integration: Sincronização automatizada de vetores e metadados com o Supabase (Vector Store).

4. Stack Tecnológica

• Linguagem Core: Python 3.13.
• Performance: Processamento otimizado com foco em Lazy Evaluation e paralelismo (Rust/Polars via pipelines).
• Cloud & Storage: Sincronização via Google Drive API (shared/drive_client.py) e exportação para Parquet.
• Qualidade: Contratos de schema rigorosos (check_gold_schema_contract.py) e logs detalhados de cada etapa do processo.

5. Estrutura de Diretórios

├── src/govbr_etl/
│   ├── core/           # Camadas Medallion (Bronze, Silver, Gold)
│   ├── modules/
│   │   ├── audit/      # RAG, BI (Cubos) e IA Training
│   │   └── pipeline/   # Padronização e Limpeza
│   ├── shared/         # Clientes de API (Drive, Supabase) e Utils
│   └── tools/          # Validação de Contratos de Dados e Amostragem
├── logs/               # Rastreabilidade total do pipeline
└── temp/               # Landing Zone organizada por Ano/Camada