# dataenergia/observatorio-pese-pr architecture

> Architecture diagram of the GitHub repository dataenergia/observatorio-pese-pr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dataenergia/observatorio-pese-pr
- Repository: https://github.com/dataenergia/observatorio-pese-pr

## Overview

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: [`src/App.jsx`](https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/App.jsx) (App shell), [`src/hooks/useCategoryData.js`](https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/hooks/useCategoryData.js) (Category data hook), [`scripts/gerar_dados_enriquecidos.cjs`](https://github.com/dataenergia/observatorio-pese-pr/blob/main/scripts/gerar_dados_enriquecidos.cjs) (Pipeline scripts), [`src/components/Dashboard.jsx`](https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/Dashboard.jsx) (KPI dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Static data"]
  node_n12["Mock dataset<br/>Frontend data<br/>[mockData.js]"]
  node_n13["Category model<br/>Frontend data<br/>[categoryData.js]"]
  node_n14["L1 source data<br/>Processed indicators"]
  node_n15["Sector datasets<br/>Processed domain data<br/>[geracao_mensal.csv]"]
  node_n16["Geo assets<br/>Spatial assets"]
end

subgraph group_g2["Processing pipeline"]
  node_n17["Pipeline scripts<br/>ETL scripts"]
end

subgraph group_g3["Frontend app"]
  node_n1["App shell<br/>React SPA entry<br/>[App.jsx]"]
  node_n2["Main layout<br/>Layout components<br/>[Header.jsx]"]
  node_n3["Category views<br/>Overview pages<br/>[VetoresView.jsx]"]
  node_n4["Sector dashboard<br/>Sector analytics"]
  node_n5["KPI dashboard<br/>KPI analytics<br/>[Dashboard.jsx]"]
  node_n6["KPI drill-down<br/>Detail analysis<br/>[KPIDrillDown.jsx]"]
  node_n7["Raw data table<br/>L1 indicators<br/>[RawData.jsx]"]
  node_n8["Risk view<br/>Risk management<br/>[RisksView.jsx]"]
  node_n9["Projection view<br/>Planning view<br/>[ProjecoesView.jsx]"]
  node_n10["Reusable cards<br/>UI widgets<br/>[KPICard.jsx]"]
  node_n11["Category data hook<br/>[useCategoryData.js]"]
  node_n20["Map component<br/>Spatial UI<br/>[CoroplethMap.jsx]"]
end

subgraph group_g4["Docs & deploy"]
  node_n18["Static deploy<br/>Vercel/static<br/>[vercel.json]"]
  node_n19["Docs pack<br/>Documentation<br/>[README.md]"]
end

node_n17 -->|"builds"| node_n14
node_n17 -->|"builds"| node_n15
node_n17 -->|"packages"| node_n16
node_n12 -->|"feeds"| node_n11
node_n13 -->|"feeds"| node_n11
node_n11 -->|"drives"| node_n3
node_n11 -->|"drives"| node_n4
node_n11 -->|"drives"| node_n5
node_n11 -->|"drives"| node_n7
node_n11 -->|"drives"| node_n8
node_n11 -->|"drives"| node_n9
node_n1 -->|"composes"| node_n2
node_n1 -->|"routes"| node_n3
node_n1 -->|"routes"| node_n4
node_n1 -->|"routes"| node_n5
node_n1 -->|"routes"| node_n7
node_n1 -->|"routes"| node_n8
node_n1 -->|"routes"| node_n9
node_n5 -->|"expands"| node_n6
node_n5 -->|"uses"| node_n10
node_n6 -->|"uses"| node_n10
node_n8 -->|"uses"| node_n10
node_n4 -.->|"placeholder"| node_n20
node_n20 -->|"reads"| node_n16
node_n18 -->|"deploys"| node_n1
node_n19 -.->|"describes"| node_n1
node_n19 -.->|"describes"| node_n17

click node_n1 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/App.jsx"
click node_n2 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/Header.jsx"
click node_n3 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/VetoresView.jsx"
click node_n4 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/SectorDashboard.jsx"
click node_n5 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/Dashboard.jsx"
click node_n6 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/KPIDrillDown.jsx"
click node_n7 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/RawData.jsx"
click node_n8 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/RisksView.jsx"
click node_n9 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/ProjecoesView.jsx"
click node_n10 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/KPICard.jsx"
click node_n11 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/hooks/useCategoryData.js"
click node_n12 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/data/mockData.js"
click node_n13 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/data/categoryData.js"
click node_n14 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/data/processed/indicadores_l1/indicadores_l1_mensal.csv"
click node_n15 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/data/processed/setor_eletrico/geracao_mensal.csv"
click node_n16 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/public/data/geo/lt_transmissao.geojson"
click node_n17 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/scripts/gerar_dados_enriquecidos.cjs"
click node_n18 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/vercel.json"
click node_n19 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/README.md"
click node_n20 "https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/CoroplethMap.jsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n12,node_n13,node_n14,node_n15,node_n16 toneBlue
class node_n17 toneAmber
class node_n1,node_n2,node_n3,node_n4,node_n5,node_n6,node_n7,node_n8,node_n9,node_n10,node_n11,node_n20 toneMint
class node_n18,node_n19 toneRose
```

## Components

### Static data

Curated datasets and packaged assets served directly to the frontend.

- [Mock dataset](https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/data/mockData.js): Frontend data · Primary in-app dataset used by the dashboard runtime. · `src/data/mockData.js`
- [Category model](https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/data/categoryData.js): Frontend data · Category and grouping definitions used by the UI. · `src/data/categoryData.js`
- [L1 source data](https://github.com/dataenergia/observatorio-pese-pr/blob/main/data/processed/indicadores_l1/indicadores_l1_mensal.csv): Processed indicators · Monthly indicator dataset supporting the raw-data layer. · `data/processed/indicadores_l1/indicadores_l1_mensal.csv`
- [Sector datasets](https://github.com/dataenergia/observatorio-pese-pr/blob/main/data/processed/setor_eletrico/geracao_mensal.csv): Processed domain data · Curated CSV outputs for electricity, gas/biomethane, fuels, and transversal domains. · `data/processed/setor_eletrico/geracao_mensal.csv`
- [Geo assets](https://github.com/dataenergia/observatorio-pese-pr/blob/main/public/data/geo/lt_transmissao.geojson): Spatial 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](https://github.com/dataenergia/observatorio-pese-pr/blob/main/scripts/gerar_dados_enriquecidos.cjs): ETL 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](https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/App.jsx): React SPA entry · Top-level client app orchestration and view switching. · `src/App.jsx`
- [Main layout](https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/Header.jsx): Layout components · Shared header/sidebar/navigation structure for the dashboard. · `src/components/Header.jsx`
- [Category views](https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/VetoresView.jsx): Overview pages · Sector and vector entry views that swap the main dashboard context. · `src/components/VetoresView.jsx`
- [Sector dashboard](https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/SectorDashboard.jsx): Sector analytics · Sector-level comparisons and spatial placeholder view. · `src/components/SectorDashboard.jsx`
- [KPI dashboard](https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/Dashboard.jsx): KPI analytics · KPI summary view with status thresholds and drill-down entry points. · `src/components/Dashboard.jsx`
- [KPI drill-down](https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/KPIDrillDown.jsx): Detail analysis · Expanded KPI history and deeper indicator context. · `src/components/KPIDrillDown.jsx`
- [Raw data table](https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/RawData.jsx): L1 indicators · Paginated indicator table with filters and export-oriented interaction. · `src/components/RawData.jsx`
- [Risk view](https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/RisksView.jsx): Risk management · Risk matrix and alert-oriented monitoring surface. · `src/components/RisksView.jsx`
- [Projection view](https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/ProjecoesView.jsx): Planning view · Planning-wave and forecast presentation for future horizons. · `src/components/ProjecoesView.jsx`
- [Reusable cards](https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/KPICard.jsx): UI widgets · Shared KPI cards, sparklines, status badges, and alert components. · `src/components/KPICard.jsx`
- [Category data hook](https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/hooks/useCategoryData.js): Data hook · Client-side filtering and shaping of category-specific datasets. · `src/hooks/useCategoryData.js`
- [Map component](https://github.com/dataenergia/observatorio-pese-pr/blob/main/src/components/CoroplethMap.jsx): Spatial UI · Current geospatial placeholder component using shipped geo assets. · `src/components/CoroplethMap.jsx`

### Docs & deploy

Project documentation and static deployment configuration.

- [Static deploy](https://github.com/dataenergia/observatorio-pese-pr/blob/main/vercel.json): Vercel/static · Static hosting configuration for the frontend build. · `vercel.json`
- [Docs pack](https://github.com/dataenergia/observatorio-pese-pr/blob/main/README.md): Documentation · Repository documentation and packaged technical deliverables. · `README.md`

## Connections

- 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.
