🇧🇷 Português · 🇬🇧 English

💡 OpenLux

Plataforma aberta de gestão de iluminação pública

Inventário vivo, georreferenciado e versionado do parque de iluminação — para qualquer cidade. Mapa público, edição em campo, fotometria de instalação, análise espacial e auditoria completa. Código MIT; os dados pertencem a cada município.

Open platform for public lighting asset management — born in Niterói, Brazil, built for any city.

🌍 Visão do projeto · 🌐 Demo (Niterói) · 🏙️ Implante na sua cidade · 🐛 Reportar Bug

A instância de referência ao vivo: clusters do parque de Niterói coloridos por taxa de modernização LED — clique para abrir.

---

🌍 A plataforma

Quase toda cidade gerencia sua iluminação pública com planilhas, sistemas proprietários caros e dados mortos — um censo que envelhece no dia seguinte. O OpenLux propõe outro paradigma, detalhado no documento de visão:

• Dado vivo e versionado — campanhas de levantamento sucessivas; cada ponto sabe a idade e a proveniência do seu dado; nada é apagado, tudo é camada.
• Instalação, não só inventário — índices fotométricos (aproveitamento no piso, poluição luminosa) calculados a partir de atributos baratos coletados em campo.
• Aberto e expansível — cidade é configuração, não código: consórcios regionais multi-tenant ou instâncias soberanas, com federação de indicadores no horizonte.

🧪 Caso de estudo — parque urbano de referência

A plataforma é a generalização de um sistema em produção operando um parque urbano real, que serve de laboratório: cada recurso é validado com dados reais antes de virar plataforma. O marco está congelado e citável no DOI 10.5281/zenodo.21305310.

🔦 Pontos mapeados	🏘️ Bairros	✅ Modernizados LED	⚡ Potência instalada	📋 Histórico
42.765	52	39%	~5,8 MW	85.000+ registros

Outras implantações: ver o registro de cidades.

✨ Funcionalidades

🗺️ Mapa Inteligente Clustering dinâmico por zoom (grid geohash) 4 mapas-base (escuro, claro, ruas, satélite) Coroplético por bairro e grid de densidade 🔥 Heat maps: % LED, densidade e idade ✏️ Seleção por área (polígono): contagem, densidade, % LED e export só da região (PostGIS)	🎯 Filtros Avançados Bairro, tipo de lâmpada, potência, status Faixas de % LED e watts (min/max) 📅 Timeline por período de modernização Saúde do ponto (verde/amarelo/vermelho)
✏️ Gestão em Campo Cadastro de ativos direto no mapa Luminárias, postes, caixas, relés e braços Edição com fila de aprovação opcional 📸 Upload de foto com compressão automática	📊 Dados & Conformidade Exportação CSV, GeoJSON e PDF Catálogo de modelos com fotometria Tier 2 (lumens, lm/W, FP, THD, IK, DPS, arquivo .IES) Histórico completo de alterações por ponto Auditoria de intervenções

🔐 Perfis de Acesso

Papel	Visualizar	Criar/Editar pontos	Excluir	Administração
👁️ leitura	✅	—	—	—
✏️ editor	✅	✅	—	Modelos
🛡️ admin	✅	✅	✅	Usuários, branding, aprovações

O mapa é público (sem login). Escrita exige autenticação + papel — validado por RLS e por RPCs SECURITY DEFINER com verificação de papel no banco, nunca no cliente.

🏗️ Arquitetura

flowchart LR
    U(["👤 Usuário"]) --> SPA["🖥️ SPA<br/>index.html único<br/>Leaflet + JS vanilla"]

    subgraph Supabase ["☁️ Supabase (por cidade ou consórcio)"]
        DB[("🐘 PostgreSQL + PostGIS<br/>RPCs ip_* · RLS")]
        AUTH["🔑 Auth<br/>leitura · editor · admin"]
        STG["🗂️ Storage<br/>branding · fotos · .IES"]
    end

    SPA -- "RPC (PostgREST)" --> DB
    SPA --> AUTH
    SPA --> STG

    GH["📦 GitHub (main)"] -- "deploy automático" --> NF["🌐 Cloudflare Workers<br/>publica somente dist/"]
    NF --> SPA

Loading

Decisões de projeto: zero build step, zero framework — um único index.html autocontido com dependências via CDN. Toda a lógica de permissão vive no banco (RLS + RPCs). Simplicidade que uma prefeitura pequena opera e uma universidade audita.

📐 Fotometria de Instalação (Tier 3)

Do inventário ao modelo de engenharia. Além de registrar o que está instalado, a plataforma captura como e onde — transformando o cadastro em base para análise luminotécnica e objeto de artigo científico.

Cada luminária pode ser classificada por dois parâmetros de instalação, coletados em opções pré-definidas (sem digitação livre) e convertidos em índices exibidos no painel:

Parâmetro	Captura	Alimenta
📐 Ângulo de apontamento (0°–120°, nadir)	dropdown pré-classificado	Aproveitamento no piso · uplight
🧱 Material do piso (asfalto, concreto, água…)	dropdown com refletância ρ tabelada	Luminância percebida · luz refletida ao céu

A partir deles, três indicadores de primeira ordem são calculados e mostrados por ponto:

Indicador	Fórmula	Significado
Aproveitamento no piso	η = max(0, cos θ)	fração do fluxo útil no solo
Poluição luminosa	P = (1−η) + ρ·η·0,5	skyglow direto + refletido
Luminância relativa	L = η·ρ	o que o olho percebe

📖 Modelo completo, fórmulas, refletâncias e referências normativas (ABNT NBR 5101, CIE 144/150, IESNA BUG): docs/FIELD_REFERENCE_TIER3_PHOTOMETRY.md

🏙️ Implante na sua cidade

O OpenLux é feito para ser replicado: backend gratuito/baixo custo (Supabase), hospedagem estática, base de pontos importada de censo/KML ou cadastrada em campo. A implantação hoje é manual (~1 dia); o roadmap a leva a ~1 hora.

➡️ Guia: implante o OpenLux na sua cidade · registro de cidades · governança

🚀 Rodando localmente (instância de referência)

Pré-requisitos

• Qualquer servidor HTTP estático (ou só abrir o arquivo no navegador)
• Node.js 18+ apenas para rodar os testes

# 1. Clone o repositório
git clone https://github.com/DaniloSFValim/openlux.git
cd openlux

# 2. Sirva o index.html
npx http-server .
# → http://localhost:8080

💡 O app aponta para o Supabase de produção de Niterói via chave publishable (pública por design). Para um backend próprio, veja supabase/README.md e .env.example.

Rodando os testes

npm install
npx playwright test        # E2E (26 testes)

🧪 Qualidade & CI/CD

Workflow	O que faz	Quando roda
⚙️ CI	Validação de HTML e migrations	push / PR
🎭 E2E Tests	26 testes Playwright contra o deploy preview	PR
🔌 API Tests	9 requisições Newman/Postman contra os RPCs	PR
🔦 Lighthouse CI	Auditoria de performance	PR
🛡️ Security Scan	npm audit + análise estática	push / PR
💾 Backup	Dump diário do banco	cron 02:00 UTC

🗄️ Banco de Dados

O schema é versionado em supabase/migrations/ — leia o README de migrations antes de qualquer mudança: o banco de produção é a fonte de verdade e merge de PR não aplica migration.

Para subir o banco do zero, use o snapshot completo em supabase/schema.sql (não o diretório de migrations):

psql "$DATABASE_URL" -f supabase/schema.sql

📂 Estrutura do projeto

openlux/
├── index.html                  # 🎯 A aplicação inteira (SPA autocontida)
├── design-tokens.css           # Tokens de design (cores, espaçamento, z-index)
├── _headers                    # Headers HTTP: segurança + cache imutável
├── wrangler.jsonc              # Deploy: publica somente dist/ (assets.directory)
├── VISION.md                   # 🌍 Visão e roadmap da plataforma
├── GOVERNANCE.md               # Como o projeto decide
├── cities/                     # Registro público de implantações
├── supabase/
│   ├── schema.sql              # Snapshot completo: reconstrói o banco do zero
│   └── migrations/             # Schema versionado (espelho do banco) + README
├── tests/                      # E2E Playwright
├── scripts/                    # Backup & restore
├── docs/                       # Guias e referências (deploy, Tier 2/3, PI)
├── paper/                      # 📄 Artigo científico (PT/EN), dados e figuras
├── .github/workflows/          # 8 pipelines de CI/CD
├── ARCHITECTURE.md             # Arquitetura detalhada
├── DEPLOYMENT_GUIDE.md         # Guia de deploy passo a passo
├── TROUBLESHOOTING.md          # Soluções para problemas comuns
└── CHANGELOG.md                # Histórico de versões

🗺️ Roadmap

O roadmap completo, por fases, vive na visão. Resumo:

• Fase −1 · Laboratório — sistema de Niterói completo em produção (v1.3.0, DOI)
• Fase 0 · Identidade — visão, governança, registro de cidades (OpenLux)
• Fase 1 · Desacoplar — cidade vira configuração (config/cities/ + bloco CITY)
• Fase 2 · Recenseamento — campanhas versionadas, estado herdado/verificado, filtro de campo no mapa
• Fase 3 · Multi-cidade — RLS por município, onboarding "nova cidade em 1 hora"
• Fase 4 · Região — painel agregado multi-cidade, PWA offline para campo
• Fase 5 · Comunidade — federação de instâncias, datasets abertos

Veja as issues abertas para a lista completa.

🤝 Contribuindo

Contribuições são bem-vindas! Leia a governança, o guia de contribuição e o código de conduta. Em resumo:

1. Faça um fork e crie sua branch: git checkout -b feature/minha-feature
2. Commit seguindo Conventional Commits: feat: adicionar X
3. Abra um PR — os templates de bug e feature ajudam a padronizar

Vulnerabilidades de segurança: siga a política de segurança — não abra issue pública.

📚 Documentação

Documento	Conteúdo
VISION.md	🌍 A visão da plataforma: tese, modelo de expansão, fases
GOVERNANCE.md	Como o projeto decide; como cidades aderem
docs/DEPLOY_YOUR_CITY.md	🏙️ Implante o OpenLux na sua cidade
cities/README.md	Registro público de implantações
ARCHITECTURE.md	Diagramas, fluxos e modelo de dados
DEPLOYMENT_GUIDE.md	Deploy do zero (Cloudflare + Supabase)
TROUBLESHOOTING.md	FAQ e diagnóstico de problemas
docs/FIELD_REFERENCE_TIER2.md	Campos de fotometria e conformidade do modelo (Tier 2)
docs/FIELD_REFERENCE_TIER3_PHOTOMETRY.md	📐 Fotometria de instalação: ângulo, material do piso e índices de poluição luminosa (Tier 3)
paper/	📄 Rascunho de artigo científico (PT + EN), dados e figuras reprodutíveis
docs/INTELLECTUAL_PROPERTY.md	🔒 Propriedade intelectual: DOI Zenodo, registro INPI, como citar
CHANGELOG.md	Histórico de versões

📝 Como citar

Autor: Danilo Valim — ORCID 0009-0009-7250-6151 · DOI: 10.5281/zenodo.21305310

Se você usar este software ou o método de índices fotométricos, cite:

Valim, D. (2026). Iluminação LED Niterói — sistema georreferenciado de gestão do parque de iluminação pública com índices fotométricos de instalação (v1.3.0) [Software]. Zenodo. https://doi.org/10.5281/zenodo.21305310

O GitHub também gera a citação a partir do CITATION.cff (botão "Cite this repository", com o iD do ORCID e o DOI). O marco v1.3.0 (Niterói) permanece o registro citável até o release v2.0.0 da plataforma.

⚠️ Limitações Conhecidas

Limitação	Contexto	Roadmap
Implantação manual	Setup leva ~1 dia (leitura de dados, schema, config)	Fase 3: onboarding guiado (~1 hora)
Single-tenant por projeto	Cada cidade = projeto Supabase separado	Fase 3: multi-tenant com RLS
Export max 4.000 pontos	Limite por performance/memória no PDF	Chunk export ou server-side rendering (Fase 4)
Sem offline para campo	Edições perdem-se se desconectar	Fase 4: PWA com queue offline + sync
Fotometria .IES sem visualizador	.IES uploadado mas não parseado	Fase 3.1: parser + curvas polares interativas
Sem imagens em ponto	Campo foto comentado; apenas modelo tem .IES	Fase 4: galeria por ponto + compressão automática
API interna apenas	RPC functions não têm versionamento público	Fase 5: API externa com SLA
Sem notificações em tempo real	Edições de outros usuários require refresh	Futuro: WebSocket + Supabase realtime

Nota: Limitações são por design (MVP mindset) e roadmapped. Antes de reportar como bug, verificar esta tabela.

📄 Licença

Código sob licença MIT — veja LICENSE. Os dados de cada implantação pertencem ao respectivo município (governança).

---

OpenLux · concebido e mantido por Danilo Valim

Nascido em Niterói/RJ · feito para qualquer cidade

Feito com 💛 para iluminar melhor — com menos poluição luminosa

⭐ Se este projeto te ajudou, deixe uma estrela!