# portugol-devoteers/pcg-analyze-energy-costs architecture

> Architecture diagram of the GitHub repository portugol-devoteers/pcg-analyze-energy-costs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/portugol-devoteers/pcg-analyze-energy-costs
- Repository: https://github.com/portugol-devoteers/pcg-analyze-energy-costs

## Overview

##### Project Type and Purpose
- This is a full-stack web application.
- Front-end: React/TypeScript single-page app (SPA) for visualizing global energy consumption and running basic predictions.
- Back-end: Python/Flask REST API serving data and prediction endpoints.
- Data source: a CSV file of world energy consumption and minimal in-memory processing.

##### File Structure
Top-level split:
– public/ + src/ → React front-end
– server/ → Flask back-end
Key front-end subfolders:
- src/components → UI building blocks (Charts, Header, Footer, sections)
- src/pages & src/routes.tsx → route definitions for Home, About, PowerBi
- src/data & src/assets → static JSON and image assets
- src/i18n.ts & src/translations → localization
Back-end substructure:
- server/app/routes.py → HTTP endpoints
- server/app/services.py → business logic (data filtering, prediction)
- server/app/models.py → data schemas or structures
- server/app/utils.py → helper functions
- server/data/Consumo_Energia_Mundial.csv → raw data file
- server/run.py → app entry point

##### Extract Architectural Insights from README
- Front-end uses Node.js + npm, served on port 3000 by React Dev Server.
- Back-end uses Flask on a configurable port (e.g., 5000).
- There is no external database; the CSV file lives on the server.
- Communication is via REST calls from React to Flask.

##### Defining Main Components & Interactions
a. Components:
1. Browser/Client – hosts React SPA
2. React Application – UI layer broken into Pages, Components, Data Layers
3. Flask API Server – exposes REST endpoints
4. Data Source – CSV file and any in-memory model
5. (Optional) Node.js & Python runtime environments
b. Relationships & Data Flow:
- User actions in Browser → React Router loads a Page → React Component
- React Component calls “fetch” or “axios” to Flask endpoint (e.g., /predict, /top10)
- Flask routes.py receives request → delegates to services.py → reads CSV → computes JSON → returns HTTP response
- React receives JSON → updates state → re-renders chart components
c. Architectural Patterns:
- Front-end: Component-based MVC-ish pattern with a service layer for API calls
- Back-end: Layered architecture (Routes → Services → Models/Utils)
- Separation of concerns between presentation (React) and data processing (Flask)
d. Key Technologies:
- Front-end: React, TypeScript, Tailwind CSS, i18next (for translations), Chart library
- Back-end: Python3, Flask, Pandas (likely used in services for CSV), virtualenv
- Build & Config: Webpack (implied via Create-React-App), postcss.config.js, tsconfig.json, package.json, requirements.txt

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External User
    User((User)):::external

    %% Client Side - React SPA
    subgraph "Client: React SPA" 
        direction TB
        Index["Entry Point\n(src/index.tsx)"]:::frontend
        Routes["React Router\n(src/routes.tsx)"]:::frontend
        subgraph "Pages" 
            direction TB
            HomePage["Home Page\n(src/pages/Home.tsx)"]:::frontend
            AboutPage["About Page\n(src/pages/About.tsx)"]:::frontend
            PowerBiPage["PowerBi Page\n(src/pages/PowerBi.tsx)"]:::frontend
        end
        subgraph "Layout Components"
            direction TB
            Layout["Layout Wrapper\n(src/components/Layout.tsx)"]:::frontend
            Header["Header\n(src/components/Header.tsx)"]:::frontend
            Footer["Footer\n(src/components/Footer.tsx)"]:::frontend
        end
        subgraph "Home Sections"
            direction TB
            PredictionSection["Prediction Section\n(src/components/Home/PredictionSection.tsx)"]:::frontend
            PredictionSelect["Prediction Select\n(src/components/Home/PredictionSelect.tsx)"]:::frontend
            Top10Renew["Top10 Renewable\n(src/components/Home/Top10RenewableSection.tsx)"]:::frontend
            Top10NonRenew["Top10 Non-Renewable\n(src/components/Home/Top10NonRenewableSection.tsx)"]:::frontend
        end
        subgraph "Charts"
            direction TB
            BarChart["Bar Chart\n(src/components/Charts/BarCh.tsx)"]:::frontend
            LineAreaChart["Line/Area Chart\n(src/components/Charts/LineArea.tsx)"]:::frontend
        end
        subgraph "Static Data & Assets"
            direction TB
            CountriesJSON["countries.json\n(src/data/countries.json)"]:::datastore
            EnergyTypesJSON["energy_types.json\n(src/data/energy_types.json)"]:::datastore
            Images["Images\n(src/assets/images/)"]:::datastore
        end
        subgraph "i18n & Translations"
            direction TB
            I18nSetup["i18n Setup\n(src/i18n.ts)"]:::frontend
            EnJSON["en.json\n(src/translations/en.json)"]:::datastore
            PtJSON["pt.json\n(src/translations/pt.json)"]:::datastore
        end
        subgraph "Interfaces"
            direction TB
            IPred["IPredictionData\n(src/interfaces/IPredictionData.ts)"]:::frontend
            ITop10["ITop10Data\n(src/interfaces/ITop10Data.ts)"]:::frontend
        end
        subgraph "Build & Config"
            direction TB
            Tailwind["tailwind.config.js"]:::frontend
            PostCSS["postcss.config.js"]:::frontend
            TSConfig["tsconfig.json"]:::frontend
            Manifest["manifest.json\n(public/manifest.json)"]:::frontend
            PackageJSON["package.json"]:::frontend
            PackageLock["package-lock.json"]:::frontend
        end
    end

    %% Server Side - Flask API
    subgraph "Server: Flask API" 
        direction TB
        Run["Entry Point\n(server/run.py)"]:::backend
        RoutesPy["HTTP Routes\n(server/app/routes.py)"]:::backend
        Services["Business Logic\n(server/app/services.py)"]:::backend
        Models["Data Models\n(server/app/models.py)"]:::backend
        Utils["Utility Helpers\n(server/app/utils.py)"]:::backend
        CSV["CSV Data Store\n(server/data/Consumo_Energia_Mundial.csv)"]:::datastore
        Requirements["requirements.txt"]:::backend
    end

    %% Runtimes
    subgraph "Runtimes & Environments"
        direction TB
        NodeJS[(Node.js)]:::external
        Python[(Python)]:::external
    end

    %% Connections - Client Flow
    User -->|"opens SPA"| Index
    Index -->|"initializes Router"| Routes
    Routes -->|"renders"| HomePage
    Routes -->|"renders"| AboutPage
    Routes -->|"renders"| PowerBiPage
    HomePage -->|"wraps"| Layout
    AboutPage -->|"wraps"| Layout
    PowerBiPage -->|"wraps"| Layout
    Layout --> Header
    Layout --> Footer
    HomePage --> PredictionSection
    HomePage --> Top10Renew
    HomePage --> Top10NonRenew
    PredictionSection --> PredictionSelect
    PredictionSection --> BarChart
    Top10Renew --> BarChart
    Top10NonRenew --> LineAreaChart
    PredictionSection -->|"fetch /api/predict\nHTTP/JSON"| RoutesPy
    Top10Renew -->|"fetch /api/top10?type=renewable\nHTTP/JSON"| RoutesPy
    Top10NonRenew -->|"fetch /api/top10?type=nonrenewable\nHTTP/JSON"| RoutesPy

    %% Data & Assets Access
    BarChart --> CountriesJSON
    BarChart --> EnergyTypesJSON
    LineAreaChart --> CountriesJSON
    LineAreaChart --> EnergyTypesJSON
    I18nSetup --> EnJSON
    I18nSetup --> PtJSON

    %% Server Flow
    Run --> RoutesPy
    RoutesPy --> Services
    Services --> Models
    Services --> Utils
    Services --> CSV
    RoutesPy -->|"returns JSON"| PredictionSection
    RoutesPy -->|"returns JSON"| Top10Renew
    RoutesPy -->|"returns JSON"| Top10NonRenew

    %% Runtime Bindings
    Index --> NodeJS
    Run --> Python

    %% Click Events
    click Index "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/index.tsx"
    click Routes "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/routes.tsx"
    click HomePage "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/pages/Home.tsx"
    click AboutPage "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/pages/About.tsx"
    click PowerBiPage "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/pages/PowerBi.tsx"
    click Layout "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/components/Layout.tsx"
    click Header "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/components/Header.tsx"
    click Footer "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/components/Footer.tsx"
    click PredictionSection "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/components/Home/PredictionSection.tsx"
    click PredictionSelect "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/components/Home/PredictionSelect.tsx"
    click Top10Renew "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/components/Home/Top10RenewableSection.tsx"
    click Top10NonRenew "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/components/Home/Top10NonRenewableSection.tsx"
    click BarChart "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/components/Charts/BarCh.tsx"
    click LineAreaChart "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/components/Charts/LineArea.tsx"
    click CountriesJSON "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/data/countries.json"
    click EnergyTypesJSON "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/data/energy_types.json"
    click Images "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/tree/main/src/assets/images/"
    click I18nSetup "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/i18n.ts"
    click EnJSON "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/translations/en.json"
    click PtJSON "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/translations/pt.json"
    click IPred "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/interfaces/IPredictionData.ts"
    click ITop10 "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/src/interfaces/ITop10Data.ts"
    click Tailwind "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/tailwind.config.js"
    click PostCSS "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/postcss.config.js"
    click TSConfig "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/tsconfig.json"
    click Manifest "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/public/manifest.json"
    click PackageJSON "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/package.json"
    click PackageLock "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/package-lock.json"
    click Run "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/server/run.py"
    click RoutesPy "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/server/app/routes.py"
    click Services "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/server/app/services.py"
    click Models "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/server/app/models.py"
    click Utils "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/server/app/utils.py"
    click CSV "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/server/data/Consumo_Energia_Mundial.csv"
    click Requirements "https://github.com/portugol-devoteers/pcg-analyze-energy-costs/blob/main/server/requirements.txt"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef backend fill:#DFFFE0,stroke:#28A745,color:#28A745
    classDef datastore fill:#F0F0F0,stroke:#888888,color:#555555
    classDef external fill:#FFF4E5,stroke:#FB8C00,color:#FB8C00
```
