How dataenergia/observatorio-pese-pr works
1. Repository role
- This is a frontend-only MVP for the *Observatório de Segurança Energética do Paraná (PESE-PR 2050)*.
- The application is a single-page React dashboard that presents energy-sector KPIs, drill-downs, raw indicators, and risk views. There is no visible backend service in this repo.
2. Core runtime and build stack
- The app runs on React 18 with Vite as the build tool/dev server.
- Styling is handled with Tailwind CSS v4 plus some component-specific CSS files.
- Charts are built with Recharts and icons with Lucide React.
- Deployment is configured for a static frontend host via vercel.json.
3. Main UI composition
- src/App.jsx acts as the top-level orchestrator and likely controls which major dashboard view is shown.
- The UI is organized into reusable components under src/components/, including:
- navigation/layout: Sidebar, Header
- overview and sector pages: VetoresView, SectorDashboard, Dashboard
- detail/analysis views: KPIDrillDown, RawData, RisksView, ProjecoesView
- reusable display units: KPICard, Sparkline, StatusBadge, RiskAlerts
- This is not a server-rendered architecture; it is a client-side view composition model.
4. Primary product slices
- The README defines four user-facing layers:
- Vetores Energéticos: entry screen with sector cards.
- Dashboard Setorial: sector-level comparisons and a geospatial placeholder.
- Dashboard de KPIs: 14 KPIs with automatic traffic-light status and drill-down.
- Dados Brutos (L1): paginated table of 67 indicators with filters and export.
- Gestão de Riscos: risk matrix and trigger alerts.
- These slices map directly to the major components in src/components/.
5. Data model and hierarchy
- The app is organized around a hierarchy: Onda → Eixo → KPI → Indicadores L1 → Riscos.
- There are three planning waves:
- 2025–2030
- 2031–2040
- 2041–2050
- The KPI layer contains thresholds for green/yellow/red status, and drill-downs expose 12 months of history.
- The raw indicator layer contains sectoral, municipal, and period-based records, with 67 indicators referenced in the README.
6. Where data comes from in the frontend
- The active in-app dataset is defined in src/data/mockData.js and related helpers such as src/data/categoryData.js.
- src/hooks/useCategoryData.js suggests there is a custom data-access layer for filtering or shaping category-specific data before rendering.
- src/data/aneel_pr_usinas.json and public/data/geo/* indicate support for geo/spatial display, even if the map is still a placeholder in the current UI.
7. Offline data assets and static distribution
- The repo includes a substantial curated dataset under data/ and mirrored deployable assets under public/data/.
- data/processed/ contains cleaned CSV outputs by domain:
- combustíveis líquidos
- gás/biometano
- setor elétrico
- transversais
- public/data/processed/ contains XLSX files for the same domains, likely intended for browser download or external consumption.
- This suggests a pipeline that transforms raw source data into structured analytical outputs for the frontend.
8. Geo data boundary
- The app already ships geospatial assets in public/data/geo/ and public/geo/municipios/PR.geojson.
- Files include transmission lines, substations, gas pipelines, roads, distributor boundaries, and Paraná municipalities.
- The README explicitly frames the map as Phase 2, so the current architecture includes data readiness for spatial visualization, but not a finished map subsystem.
9. Data-processing pipeline
- The scripts/ directory contains the transformation pipeline used to generate enriched datasets:
- process_consumo.cjs
- process_geracao_ons.cjs
- process_mmgd.cjs
- process_projecoes.cjs
- process_siga_centralizada.cjs
- gerar_dados_enriquecidos.cjs
- convert_to_xlsx.cjs
- gerar_documentacao.py
- These scripts are the boundary between source/raw data and the packaged files consumed by the app, but they are not part of the runtime UI.
10. Likely data flow
- External/raw datasets are processed by the scripts into CSV/XLSX/JSON and geospatial formats.
- Those outputs are then copied or mirrored into data/ and public/data/ for static serving.
- The React frontend reads from in-repo mock/static data and renders dashboards without an API call path.
11. State and interaction patterns
- Interaction is centered on dashboard filtering and drill-down rather than server communication.
- The UI likely manages local state for:
- selected sector/category
- selected wave (“onda”)
- KPI detail modal state
- table filters and pagination
- risk/status drill-down
- Header, Sidebar, and CategorySidebar/CategoryDashboard imply a layout with navigation-driven content swapping.
12. Documentation and product packaging
- public/docs/Produto_8_Documentacao_Tecnica_Plataforma_BI.docx shows this repo also carries formal project documentation.
- README.md acts as the main architecture and product spec, including the KPI/risk model and roadmap for map/API phases.
13. What is missing by design
- There is no evidence of a backend API, authentication layer, or database in this repository.
- The architecture is intentionally static and asset-driven, suitable for a BI-style prototype or offline-capable MVP.
- Future phases noted in the README are:
- a real geospatial map layer
- a real API-backed data source
14. How to diagram it
- The cleanest architecture diagram would show:
- Static source data and processing scripts on one side
- Packaged CSV/XLSX/GeoJSON/JSON assets in the middle
- React/Vite frontend views consuming those assets on the other side
- Within the frontend, separate the diagram into the main user surfaces: sector overview, KPI dashboard, raw data table, and risk management, all sharing the same underlying dataset and filter model.
Main entry points: App.jsx App shell · useCategoryData.js Category data hook · gerar_dados_enriquecidos.cjs Pipeline scripts · Dashboard.jsx KPI dashboard
Components 20
Static data
Curated datasets and packaged assets served directly to the frontend.
- Mock dataset · Primary in-app dataset used by the dashboard runtime.
src/data/mockData.js - Category model · Category and grouping definitions used by the UI.
src/data/categoryData.js - L1 source data · Monthly indicator dataset supporting the raw-data layer.
data/processed/indicadores_l1/indicadores_l1_mensal.csv - Sector datasets · Curated CSV outputs for electricity, gas/biomethane, fuels, and transversal domains.
data/processed/setor_eletrico/geracao_mensal.csv - Geo assets · GeoJSON boundary, infrastructure, and transport layers ready for future mapping.
public/data/geo/lt_transmissao.geojson
Processing pipeline
Scripts that transform raw sources into enriched CSV, XLSX, and GeoJSON outputs.
- Pipeline scripts · Data-processing and conversion scripts that build the packaged datasets.
scripts/gerar_dados_enriquecidos.cjs
Frontend app
React/Vite single-page dashboard and reusable UI components.
- App shell · Top-level client app orchestration and view switching.
src/App.jsx - Main layout · Shared header/sidebar/navigation structure for the dashboard.
src/components/Header.jsx - Category views · Sector and vector entry views that swap the main dashboard context.
src/components/VetoresView.jsx - Sector dashboard · Sector-level comparisons and spatial placeholder view.
src/components/SectorDashboard.jsx - KPI dashboard · KPI summary view with status thresholds and drill-down entry points.
src/components/Dashboard.jsx - KPI drill-down · Expanded KPI history and deeper indicator context.
src/components/KPIDrillDown.jsx - Raw data table · Paginated indicator table with filters and export-oriented interaction.
src/components/RawData.jsx - Risk view · Risk matrix and alert-oriented monitoring surface.
src/components/RisksView.jsx - Projection view · Planning-wave and forecast presentation for future horizons.
src/components/ProjecoesView.jsx - Reusable cards · Shared KPI cards, sparklines, status badges, and alert components.
src/components/KPICard.jsx - Category data hook · Client-side filtering and shaping of category-specific datasets.
src/hooks/useCategoryData.js - Map component · Current geospatial placeholder component using shipped geo assets.
src/components/CoroplethMap.jsx
Docs & deploy
Project documentation and static deployment configuration.
- Static deploy · Static hosting configuration for the frontend build.
vercel.json - Docs pack · Repository documentation and packaged technical deliverables.
README.md
Connections 27
- Pipeline scripts → L1 source data: builds · Transforms raw inputs into the monthly L1 indicator dataset.
- Pipeline scripts → Sector datasets: builds · Generates cleaned domain datasets for dashboard consumption.
- Pipeline scripts → Geo assets: packages · Produces or curates geospatial layers for static serving.
- Mock dataset → Category data hook: feeds · Primary dataset source for client-side shaping and filtering.
- Category model → Category data hook: feeds · Category definitions guide the filtering hook.
- Category data hook → Category views: drives · Supplies category-scoped content for vector entry screens.
- Category data hook → Sector dashboard: drives · Supplies sector view data slices.
- Category data hook → KPI dashboard: drives · Supplies KPI summaries and status groupings.
- Category data hook → Raw data table: drives · Supports table filters and indicator pagination.
- Category data hook → Risk view: drives · Provides risk-related categories and trigger context.
- Category data hook → Projection view: drives · Feeds projection and wave-based planning views.
- App shell → Main layout: composes · App shell uses shared layout and navigation.
- App shell → Category views: routes · Top-level view can open the vector overview.
- App shell → Sector dashboard: routes · Top-level view can open sector analytics.
- App shell → KPI dashboard: routes · Top-level view can open KPI dashboards.
- App shell → Raw data table: routes · Top-level view can open raw indicator tables.
- App shell → Risk view: routes · Top-level view can open risk management screens.
- App shell → Projection view: routes · Top-level view can open projection/planning screens.
- KPI dashboard → KPI drill-down: expands · KPI summary drills into detailed histories.
- KPI dashboard → Reusable cards: uses · Dashboard relies on reusable cards and badges.
- KPI drill-down → Reusable cards: uses · Drill-down uses shared sparkline/status components.
- Risk view → Reusable cards: uses · Risk alerts and badges are reused in risk views.
- Sector dashboard → Map component: placeholder · Sector dashboard can surface the future spatial layer.
- Map component → Geo assets: reads · Spatial UI is backed by shipped GeoJSON assets.
- Static deploy → App shell: deploys · Static host serves the Vite-built frontend.
- Docs pack → App shell: describes · README documents the product and architecture.
- Docs pack → Pipeline scripts: describes · Documentation covers the ETL and packaging pipeline.