FlowDX Platform Architecture
Blueprint técnico para entrega governada de workloads Cloud Native.
Projeto de Platform Engineering em evolução, focado em padronizar provisionamento, CI/CD e GitOps com Terraform, GitHub Actions, Kubernetes, Gateway API e Policy-as-Code.
## Contexto
A FlowDX Platform é um projeto autoral de Engenharia de Plataforma criado para demonstrar, de forma prática, automação de infraestrutura, CI/CD, GitOps, Kubernetes, governança e Developer Experience (DX).
A FlowDX não se propõe a ser uma IDP completa neste estágio. Ela implementa um subconjunto de capacidades comuns em plataformas internas, com foco em automação, governança e padronização da entrega de workloads Cloud Native.
A arquitetura foi desenhada a partir de práticas e aprendizados aplicados em projetos reais de infraestrutura e automação, mas o workload de referência do FlowDX será o flowdx-reference-api, uma API Python com FastAPI. Esse workload consumirá capacidades padronizadas do flowdx-platform e será entregue por GitOps a partir do flowdx-gitops em um cluster Kubernetes local com Kind.
## Estado Atual
O estado atual separa a fundação técnica já existente da arquitetura-alvo em evolução. O portfólio leandrodeobarbosa.dev continua sendo uma evidência real de AWS, Terraform e CI/CD operacionais, incluindo infraestrutura provisionada como código, pipelines automatizadas e práticas de governança. No entanto, ele não será utilizado como workload consumidor da FlowDX Platform. O workload de referência oficial do FlowDX passa a ser o flowdx-reference-api, uma API Python com FastAPI que consumirá capacidades padronizadas do flowdx-platform e será entregue por GitOps a partir do flowdx-gitops.
O que já existe hoje
## System Snapshot (v0)
Esse snapshot descreve a fundação atual, não a arquitetura final do FlowDX.
Infrastructure Foundation
AWS, Terraform, S3, CloudFront, Route 53, ACM e DynamoDB.
CI/CD Foundation
GitHub Actions, matrix-based environment validation e deployment automation.
Security Foundation
OIDC, least privilege e separated deployment responsibilities.
Governance Foundation
Remote state, state locking, drift detection e sanitized pipeline feedback.
## Diagrama de Contexto
A arquitetura-alvo do FlowDX segue um modelo multi-repositório. O flowdx-platform concentra contratos, reusable workflows, templates e políticas. O flowdx-reference-api representa o workload consumidor da plataforma. O GHCR armazena imagens versionadas e referenciadas por digest. O flowdx-gitops mantém o estado desejado observado pelo ArgoCD. O runtime local é um cluster Kind Kubernetes com NGINX Gateway Fabric, Kyverno, Prometheus e Grafana.
Esse desenho separa responsabilidades entre plataforma, workload, registry, GitOps e runtime Kubernetes.
## Destaques da Arquitetura
Contract-Driven Workflow
O flowdx.yaml atua como contrato declarativo entre workload e plataforma, evitando que cada aplicação recrie seu próprio fluxo de entrega.
Reusable Workflows
O flowdx-platform concentra workflows reutilizáveis para validação, build, publicação de imagem, validação de Helm e preparação de atualização GitOps.
FastAPI Reference Workload
O flowdx-reference-api usa FastAPI para expor endpoints operacionais e funcionais como /healthz, /readyz, /hello, /metadata, /platform/context e /error, permitindo validar probes, logs, roteamento e observabilidade.
Immutable Image Delivery
A pipeline publica imagens no GHCR com tags rastreáveis e evolui o GitOps para referências imutáveis por image digest, melhorando reprodutibilidade, auditoria e rollback.
GitOps Delivery
O flowdx-gitops mantém o estado desejado do cluster, com ArgoCD observando mudanças e sincronizando workloads.
Gateway API
O NGINX Gateway Fabric será usado para validar entrada de tráfego com Gateway API e HTTPRoute, separando responsabilidades entre plataforma e workload.
Policy-as-Code
Kyverno e validações automatizadas aplicam guardrails para manifests Kubernetes, imagens, labels, probes, recursos e políticas de ambiente.
Local Kubernetes Validation
Kind Kubernetes permite validar o fluxo Cloud Native localmente antes de uma eventual evolução para runtimes gerenciados.
## Container & Ops
A camada de operações do FlowDX será validada inicialmente em Kubernetes local com Kind. O objetivo é demonstrar um fluxo completo de entrega Cloud Native usando o flowdx-reference-api, uma API FastAPI containerizada, Docker image publicada no GHCR com image digest, Helm chart, ArgoCD, NGINX Gateway Fabric, Gateway API, políticas Kyverno, observabilidade básica com Prometheus e Grafana, além de logs estruturados em JSON.
## O que ainda falta construir
A próxima etapa é transformar a fundação já validada em um fluxo governado de plataforma, workload, registry, GitOps e runtime Kubernetes local.
## Visão de Evolução
A visão de evolução deixa de ser uma interface de geração de projetos e passa a ser um fluxo governado de CI/CD e GitOps, com contrato declarativo, imagem imutável e validações de plataforma antes do merge.
## Roadmap de Evolução
A evolução é incremental e orientada a entregas pequenas, verificáveis e demonstráveis.
Platform Foundation
Criar o flowdx-platform com contratos, reusable workflows, templates e primeiras regras de governança.
Reference API Workload
Criar o flowdx-reference-api com FastAPI, endpoints operacionais, logs estruturados, Dockerfile, Helm chart e flowdx.yaml.
Container Delivery
Buildar e publicar imagem no GHCR usando tags rastreáveis e resolver image digest para o GitOps.
GitOps Repository
Criar o flowdx-gitops com ArgoCD Applications, Helm values, image digest references e configuração do cluster.
Local Kubernetes Validation
Validar o fluxo em Kind com ArgoCD, flowdx-reference-api, Helm, Kyverno, Prometheus e Grafana.
Gateway API & Traffic Management
Adicionar NGINX Gateway Fabric, Gateway API e HTTPRoute para validar entrada de tráfego governada.
Governance & Policy-as-Code
Evoluir validações, required checks, approval gates, summaries sanitizados, políticas Kyverno e regras para imagens imutáveis.
Platform Maturity
Melhorar versionamento de contratos, versionamento de reusable workflows, estratégia de releases e documentação operacional.
## FlowDX Platform Modules
Repositório central de plataforma. Contém contratos, reusable workflows, templates e policies.
Workload de referência. Contém FastAPI, Dockerfile, Helm chart, structured logs e flowdx.yaml.
Fonte de verdade GitOps. Contém ArgoCD Applications, Helm values, Gateway API resources, image digest references e configuração do cluster.
Registry usado para armazenar imagens versionadas e referenciadas por digest.
## Princípios de Arquitetura
Platform capabilities over custom pipelines
Workloads devem consumir capacidades padronizadas da plataforma, não recriar pipelines do zero.
Declarative contracts
A intenção do workload deve ser expressa via contrato declarativo, como flowdx.yaml.
GitOps as runtime source of truth
O estado desejado do runtime Kubernetes deve estar versionado no flowdx-gitops.
Immutable delivery
Deploys devem evoluir para referências imutáveis por image digest, evitando dependência de tags mutáveis.
Gateway API as platform boundary
A entrada de tráfego deve ser modelada com Gateway API, separando responsabilidades entre plataforma e aplicação.
Policy-as-Code
Governança deve ser aplicada por validações automatizadas e políticas versionadas.
Incremental evolution
O projeto deve evoluir por fases pequenas, verificáveis e demonstráveis.
Security and auditability by default
Feedbacks de pipeline devem ser úteis, mas sanitizados. Plan, state, logs, artifacts e outputs devem ser tratados como potencialmente sensíveis.
## Por que esse projeto existe
A FlowDX Platform existe para demonstrar, de forma prática, como capacidades de plataforma podem padronizar entrega de workloads, governança, GitOps, automação e operação em ambientes Cloud Native.
O projeto combina uma fundação real já validada em AWS com uma arquitetura-alvo orientada a Kubernetes, reusable workflows, contratos declarativos, Gateway API, Policy-as-Code e observabilidade.
## Evidências Técnicas
As evidências técnicas ficam separadas entre o que já existe e as capacidades em evolução.