Ir para o conteúdo

Arquitetura do Sistema

O Onboarding Hub atua como uma camada intermediária de validação de dados e reconciliação cadastral. O sistema está dividido em módulos funcionais que se comunicam de forma fracamente acoplada.

Visão Geral de Arquitetura

O fluxo geral dos componentes está representado no diagrama de blocos abaixo:

graph LR
    root[onboarding-hub]

    root --> airflow[airflow/ - Orquestração]
    airflow --> config[config/ - Conexões]
    airflow --> dags[dags/ - Fluxo ETL]
    airflow --> plugins[plugins/ - Custom Hooks]

    root --> contracts[contracts/ - Avro & JSON Schema]

    root --> dq[data_quality/ - Validadores Soda]
    dq --> checks[checks/ - Regras de Qualidade]

    root --> infra[infra/ - Compose Locais]
    root --> scripts[scripts/ - Massa & Exportação]

    root --> sql[sql/ - DDLs de Banco]
    sql --> oracle[oracle/ - DDL Oracle 19c+]

    root --> src[src/onboarding_hub/ - App Core]
    src --> db[db/ - Engines de Conexão]
    src --> msg[messaging/ - Produtor/Consumidor Kafka]
    src --> models[models/ - Modelagem Pydantic]
    src --> synth[synthetic/ - Gerador de Dados]

    root --> tests[tests/ - Pytest]

Estrutura do Projeto

  • src/onboarding_hub/: O core do projeto Python. Contém a lógica de conexão com banco de dados, produtores e consumidores de mensagens Kafka, modelos de dados Pydantic e o gerador de dados sintéticos.
  • airflow/: Orquestrador responsável pelo agendamento e fluxos de extração, transformação e carga (ETL).
  • contracts/: Guarda os esquemas de transporte agnósticos de tecnologia (JSON Schema e Apache Avro) gerados a partir do modelo de domínio Python.
  • data_quality/: Configurações de scans e validações do Soda Core para garantir a conformidade dos payloads inseridos no banco.
  • infra/: Arquivos de infraestrutura modular em Docker Compose (Postgres, Kafka, Airflow).
  • sql/: DDLs de banco para setup de tabelas e esquemas.
  • tests/: Suíte de testes unitários executados via Pytest.

Qualidade de Código (Três Camadas)

O projeto adota três checagens complementares para garantir conformidade técnica antes de qualquer código ir para produção:

  1. Claude Code / IDE Hooks (.claude/settings.json): Formatação automática e feedbacks de tipagem rápidos no loop do desenvolvedor.
  2. Git pre-commit hooks: Gate local impedindo que códigos mal formatados, com erros graves de digitação, ou credenciais expostas sejam commitados (gitleaks, ruff).
  3. CI (GitHub Actions): Validação definitiva no servidor remoto executando a suíte de testes de forma limpa.