Arquitetura e Segurança

Esta página descreve os aspectos internos de arquitetura, topologia de rede, segurança e ciclo de vida de arquivos mantidos pelo bdot CLI na máquina do desenvolvedor.

Topologia de Rede e Gateway (Traefik)

O bdot CLI orquestra 21 containers Docker divididos entre serviços essenciais de infraestrutura (PostgreSQL, Kafka, Redis, Keycloak) e módulos de negócio (Controller, Engine, Runners e Stats).

Todo o tráfego externo para a plataforma é unificado e roteado pelo proxy reverso Traefik.

                                    Internet / Host
                                           │
                                 :${HTTP_PORT} (padrão :81)
                                 :${HTTPS_PORT} (padrão :443)  TLS autoassinado
                                           ▼
                                    ┌──────────┐
                                    │  Traefik │ (Gateway / Proxy)
                                    └────┬─────┘
                                         │
                 ┌───────────────────────┼───────────────────────┐
                 │                       │                       │
           ┌─────▼─────┐           ┌─────▼─────┐           ┌─────▼─────┐
           │ Console UI│           │ Controller│           │   Stats   │
           │ & Web API │           │   APIs    │           │ (API /    │
           └─────┬─────┘           └─────┬─────┘           │Consumidor)│
                 │                       │                 └─────┬─────┘
                 │                 ┌─────┴─────┐                 │
                 │                 │Engine API │                 │
                 │                 │ & Runners │                 │
                 │                 └─────┬─────┘                 │
                 │                       │                       │
           ┌─────▼───────────────────────▼───────────────────────▼─────┐
           │                 Bancos, Caches e Broker                   │
           │  • PostgreSQL (bdot_apl, bdot_stats)                      │
           │  • Redis Caches (Gestão, Sessão, Identidade)              │
           │  • Kafka Event Broker                                     │
           └───────────────────────────────────────────────────────────┘

Fluxo de Comunicação dos Módulos

Engine API & Runners: Consomem mensagens do broker Kafka, operam sobre as instâncias de Redis (caches de gestão, sessão e identidade) e executam integrações via banco de dados e conectores externos.
Stats (Observabilidade): Composto pelos containers stats-api e stats-consumidor-main. Consome os eventos de telemetria trafegados no Kafka e persiste/consulta os dados de observabilidade diretamente na base dedicada do PostgreSQL (bdot_stats).
Controller: Gerencia APIs do console, UI e agendamento, orquestrando fluxos e integrando-se ao Keycloak (SSO), PostgreSQL (bdot_apl), Redis e Kafka.

Mapeamento de Portas Expostas no Host

Embora os microsserviços se comuniquem em rede interna isolada, algumas portas são mapeadas diretamente na máquina do desenvolvedor para facilidade de diagnóstico e integração local:

Serviço	Porta Host	Finalidade
Traefik (HTTP)	`:81` (configurável)	Roteamento HTTP principal
Traefik (HTTPS)	`:443` (configurável)	Roteamento seguro HTTPS (TLS autoassinado)

Gestão de Segredos e Estado

O bdot CLI foi projetado para evitar senhas hardcoded em arquivos de configuração ou repositórios.

~/.bdot/
├── .bdot_secrets/          # Chaves brutas geradas (Permissão 0644)
│   ├── bdot_db_admin_password
│   ├── bdot_db_apl_password
│   └── bdot_sso_admin_password
├── state.json              # Hashes SHA-256 e metadados de sincronização
└── .env                    # Variáveis operacionais de ambiente (BDOT_CFG_*)

Ciclo de Vida e Sincronização de Credenciais

Geração Inicial: Na primeira execução do bdot setup, a CLI gera senhas fortes de 32 caracteres via gerador criptográfico crypto/rand e as armazena no diretório .bdot_secrets/.
Injeção efêmera: Os arquivos de .bdot_secrets/ são montados como Docker Secrets diretamente dentro dos containers correspondentes (PostgreSQL, Keycloak, etc.).
Persistência em state.json: Para evitar armazenar senhas em texto puro nos arquivos de estado global, o arquivo state.json grava apenas os hashes SHA-256 das senhas.
Rotação e Auditoria: Ao executar bdot up, a CLI compara o hash das senhas atuais com os mantidos em state.json. Caso identifique alterações nas senhas, executa automaticamente rotinas de atualização (ALTER USER no PostgreSQL ou scripts de redefinição de credencial no Keycloak) para manter os serviços sincronizados.

Certificados TLS e Descoberta de Rede (mDNS)

Para garantir paridade com ambientes de produção com suporte a HTTPS e domínios locais flexíveis, a CLI gerencia certificados e publicação de rede local automaticamente.

Certificados Autoassinados

No primeiro bdot up, a CLI gera um certificado digital ECDSA P-256 (bdot.crt e bdot.key) com validade de 1 ano em ~/.bdot/certs/.
O certificado é auto-gerado com suporte a nomes alternativos (SANs) abrangendo: o hostname configurado (ex: bdot.local), wildcard *.bdot.local, localhost e o endereço IP da interface primária do computador.

Resolução de Nomes e mDNS por Sistema Operacional

Para permitir acesso local via https://bdot.local, a CLI adota diferentes estratégias baseadas no sistema operacional host:

macOS e Windows (WSL2): Utiliza o anúncio contínuo via protocolo ZeroConf / mDNS por meio do utilitário interno da CLI enquanto a aplicação estiver em execução (bdot up).
Linux: Além do anúncio mDNS em tempo de execução, você pode usar o comando sudo bdot update-hostname para registrar um arquivo de serviço permanente no daemon do Avahi (/etc/avahi/services/bdot.service) e gravar a entrada estática de fallback em /etc/hosts.