LumeGateway: High-Velocity Traffic Orchestrator

---

🇧🇷 Versão em Português

🏗️ Arquitetura Técnica e Visão de Sistema

O LumeGateway não é apenas um proxy; é um Orquestrador de Tráfego de Camada 7 projetado para ser o núcleo de sobrevivência de ecossistemas poliglotas. Ele foi concebido para resolver o problema crítico de Backpressure em arquiteturas distribuídas, atuando como um "amortecedor" inteligente entre o tráfego externo imprevisível e backends especializados (PHP, Java, Python). O Lume garante que cada microsserviço opere dentro de sua zona de eficiência, evitando degradação de performance por saturação de recursos.

🧠 Conceitos de Engenharia de Elite Aplicados

1. Traffic Shaping Determinístico (Token Bucket Algorithm):

   • Implementei o controle de vazão utilizando o algoritmo Token Bucket. Diferente do Window Counter simples, o Lume permite picos controlados de tráfego (bursts) enquanto mantém uma taxa média rigorosa por IP. Isso protege a infraestrutura contra ataques de força bruta e exaustão de conexões no nível da aplicação.

2. Resiliência Adaptativa com Circuit Breaker:

   • O Gateway opera uma máquina de estados finitos (Open, Closed, Half-Open) para cada serviço upstream. Ao detectar anomalias ou latências fora do SLA (ex: falha no Java-Engine), o Lume "abre o circuito" instantaneamente. Isso isola a falha, impede que threads do Gateway fiquem presas aguardando respostas mortas e permite que o sistema se recupere sem intervenção manual.

3. Runtime de Alta Concorrência e Zero-Blocking I/O:

   • Explorando o Scheduler preemptivo do Go, o Lume trata cada requisição como uma Goroutine leve. A arquitetura utiliza buffers e canais para garantir que o processamento de rede nunca bloqueie a execução principal, permitindo escala horizontal massiva com um footprint de memória insignificante se comparado a soluções baseadas em threads tradicionais.

4. Service Discovery e Health Probing Ativo:

   • O Gateway mantém um worker interno de monitoramento que executa sondagens de Liveness (o serviço está vivo?) e Readiness (o serviço está pronto para tráfego?). Ele lê dinamicamente o estado da rede Docker, atualizando as tabelas de roteamento em memória sem a necessidade de restart, garantindo disponibilidade 99.9%.

🏛️ Por que este projeto redefine meu perfil técnico?

Este projeto representa o ápice da minha transição de "desenvolvedor de apps" para Engenheiro de Sistemas. O fascínio reside em dominar a camada invisível onde a lógica de negócio encontra a física da rede. No LumeGateway, eu não gerencio dados; eu gerencio a entropia do sistema, garantindo ordem e performance em um ambiente onde tecnologias distintas (PHP, Java, Python, Rust) precisam coexistir em harmonia e alta velocidade.

---

🇺🇸 English Version

🏗️ Technical Architecture & System Vision

LumeGateway is more than a proxy; it is a Layer 7 Traffic Orchestrator designed to be the survival core of polyglot ecosystems. It was conceived to solve the critical Backpressure problem in distributed architectures, acting as an intelligent "buffer" between unpredictable external traffic and specialized backends (PHP, Java, Python). Lume ensures that every microservice operates within its efficiency zone, preventing performance degradation due to resource saturation.

🧠 Elite Engineering Concepts Applied

1. Deterministic Traffic Shaping (Token Bucket Algorithm):

   • Flow control is implemented via the Token Bucket algorithm. Unlike simple Window Counters, Lume allows for controlled bursts while maintaining a strict average rate per IP. This shields the infrastructure from brute-force attacks and application-level connection exhaustion.

2. Adaptive Resilience with Circuit Breakers:

   • The Gateway operates a finite state machine (Open, Closed, Half-Open) for each upstream service. Upon detecting anomalies or latencies outside the SLA (e.g., a Java-Engine failure), Lume "trips the circuit" instantly. This isolates the fault, prevents Gateway threads from hanging on dead responses, and allows the system to recover without manual intervention.

3. High-Concurrency Runtime & Zero-Blocking I/O:

   • Leveraging Go’s preemptive Scheduler, Lume handles every request as a lightweight Goroutine. The architecture utilizes buffers and channels to ensure network processing never blocks the main execution, allowing massive horizontal scaling with a negligible memory footprint compared to traditional thread-based solutions.

4. Active Service Discovery & Health Probing:

   • An internal background worker performs periodic Liveness and Readiness checks. It dynamically monitors the Docker network state, updating in-memory routing tables in real-time without requiring restarts, ensuring 99.9% availability.

🏛️ Why this project redefines my technical profile

This project represents the peak of my transition from "app developer" to Systems Engineer. The fascination lies in mastering the invisible layer where business logic meets network physics. In LumeGateway, I don't just manage data; I manage system entropy, ensuring order and peak performance in an environment where diverse technologies (PHP, Java, Python, Rust) must coexist in harmony and high speed.

---

🛠️ Arsenal Técnico / Technical Arsenal

Recurso / Feature	Tecnologia / Tech	Objetivo / Goal
Core Engine	Go (Golang)	Concorrência nativa e performance de baixo nível.
Containerization	Docker	Isolamento de serviços e portabilidade.
Flow Control	Token Bucket	Rate Limiting e proteção contra DoS.
Resilience	Circuit Breaker	Isolamento de falhas e prevenção de colapso em cascata.
Discovery	Health Probing	Roteamento dinâmico e auto-correção.

---

🤝 Contributing / Contribuindo

Consulte o arquivo CONTRIBUTING.md para diretrizes de performance e submissão de código.

---

LumeGateway – High-Velocity Traffic Orchestrator

Orquestrador de Tráfego de Camada 7 com Compliance Automático (GDPR/LGPD)

---

🇧🇷 Versão em Português

🏗️ Arquitetura Técnica e Visão de Sistema

O LumeGateway não é apenas um proxy reverso; é um Orquestrador de Tráfego de Camada 7 projetado para ser o núcleo de sobrevivência de ecossistemas poliglotas. Ele resolve o crítico problema de Backpressure em arquiteturas distribuídas, atuando como um "amortecedor" inteligente entre o tráfego externo imprevisível e backends especializados (PHP, Java, Python, Rust). O Lume garante que cada microsserviço opere dentro de sua zona de eficiência, prevenindo degradação por saturação de recursos.

🧠 Conceitos de Engenharia Aplicados

• Traffic Shaping Determinístico (Token Bucket): Controle de vazão com picos controlados (bursts), mantendo taxa média rigorosa por IP. Protege contra ataques de força bruta e exaustão de conexões.
• Resiliência Adaptativa (Circuit Breaker): Máquina de estados finitos (Open, Closed, Half-Open) para cada upstream. Isola falhas automaticamente, evita threads presas e permite recuperação sem intervenção manual.
• Alta Concorrência com Zero-Blocking I/O: Goroutines leves, canais e buffers garantem que a rede nunca bloqueie a execução principal. Escala horizontal massiva com footprint de memória mínimo.
• Health Probing Ativo: Worker interno executa sondagens de Liveness e Readiness. Atualiza dinamicamente as tabelas de roteamento via Docker, mantendo 99.9% de disponibilidade sem restarts.

🔒 Compliance Proxy (LIMES) – Adequação Instantânea à LGPD/GDPR

O módulo LIMES inspeciona automaticamente as requisições e, ao detectar usuários da União Europeia (ou de qualquer país configurável), mascara dados pessoais sensíveis (CPF, e‑mail, telefone) antes que cheguem ao backend. A adequação é feita na borda, sem alterar uma linha de código dos sistemas legados.

✨ Como funciona

1. GeoIP: identifica o país de origem do IP real (suporte a X-Forwarded-For).
2. Inspeção: se o país estiver na lista do EEE, varre o corpo da requisição (JSON, formulários, etc.).
3. Mascaramento: substitui padrões como CPF e e‑mail por versões anônimas.
4. Encaminhamento seguro: o backend recebe os dados já em conformidade.

🧪 Exemplo prático

Requisição original enviada de um IP francês:

{
  "nome": "Jean",
  "cpf": "123.456.789-00",
  "email": "jean@exemplo.fr"
}

O backend recebe:

{
  "nome": "Jean",
  "cpf": "***.***.***-**",
  "email": "u****@exemplo.fr"
}

🧰 Tecnologias

• GeoIP2 (MaxMind / ip-api) – base gratuita ou comercial.
• Regex configurável para padrões locais.
• Middleware plugável – pode ser ativado/desativado por configuração.

💰 Monetização

Produto	Valor sugerido
Setup + instalação	R$ 5.000
Assinatura mensal (manutenção e atualizações)	R$ 1.500/mês

Público-alvo: E‑commerces, fintechs, ERPs com clientes na Europa.
Abordagem de venda: “Seu sistema viola GDPR? Posso resolver em 1 dia sem alterar seu código.”

🚀 Começando (Quick Start)

Pré-requisitos

• Go 1.21+
• Docker & Docker Compose
• Base GeoIP (ex: GeoLite2-Country.mmdb)

Execução local

git clone https://github.com/seu-org/lume-gateway.git
cd lume-gateway
# Coloque o arquivo GeoLite2-Country.mmdb em data/
docker-compose up -d

O gateway estará disponível em http://localhost:8080.

📂 Estrutura do Projeto

.
├── cmd/
│   └── lume/
│       └── main.go              # Entry point
├── internal/
│   ├── middleware/
│   │   ├── ratelimit/           # Token Bucket
│   │   ├── circuitbreaker/      # Circuit Breaker
│   │   └── compliance/          # LIMES
│   │       ├── geoip.go
│   │       ├── mask.go
│   │       ├── config.go
│   │       └── countries.go
│   └── proxy/                   # Lógica de proxy reverso
├── pkg/
│   └── geoip/                   # Wrapper genérico do GeoIP
│       └── geoip.go
├── configs/                     # Arquivos de configuração (thresholds, rotas)
├── data/                        # Bases GeoIP (.mmdb)
├── proto/                       # Definições gRPC (opcional)
├── docker-compose.yml
└── README.md

⚙️ Configuração do Compliance

Edite o arquivo configs/compliance.yaml:

compliance:
  enable: true
  eea_only: true
  custom_countries: ["UK", "CH"]
  patterns:
    - name: "CPF"
      regex: "\\d{3}\\.\\d{3}\\.\\d{3}-\\d{2}"
      replacement: "***.***.***-**"
    - name: "Email"
      regex: "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}"
      replacement_func: "maskEmail"

🤝 Contribuindo

Leia CONTRIBUTING.md para diretrizes de performance e submissão de código. Pull