# powerhouse-project/production architecture

> Architecture diagram of the GitHub repository powerhouse-project/production, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/powerhouse-project/production
- Repository: https://github.com/powerhouse-project/production

## Overview

##### Project type and purpose
- This is a full-stack home-energy management application (“PowerHouse”).
- Frontend: Next.js/React SPA with Tailwind & MUI for UI, Firebase for auth/config.
- Backend: FastAPI in Python exposing REST endpoints for devices, automations, energy metrics, groups, users.
- Database layer: JSON-based storage via Python modules (no external RDBMS).

##### File structure
- Top level:
- frontend/ — Next.js app with pages under src/app (dashboard, devices, energy, automations, groups, users, login)
- backend/ — FastAPI service, business logic modules (automations.py, devices_json.py, energy_json.py, groups.py, users.py), test suite
- database/ — data access layer modules (*_db.py), JSON files under database/users_db.json, automations_db.py, etc.
- CI/CD configs in .github/workflows for Node and Python.
- Patterns:
- Three tiers in backend: API (fastAPI.py), Business Logic (automations, devices, energy, groups, users), Data Access (database/*_db.py).
- Frontend follows Next.js app router conventions and componentization under ui/, layout.jsx.

##### Key insights from README
- CI/CD with GitHub Actions: node.yml (frontend), python.yml (backend).
- “npm run start” script runs both servers.
- No external SQL DB; the database folder runs update_database.py to seed JSON stores.

##### Main components
a. Frontend (Next.js/React)
b. Authentication service (Firebase Auth)
c. Backend API (FastAPI)
d. Business Logic modules (Automations, Devices, Energy, Groups, Users)
e. Data Access layer (database/*.py modules reading/writing JSON files)
f. Storage (JSON files under database/)
g. CI/CD pipelines (GitHub Actions)
h. PDF generation process (testPDF.py & Energy Report)

##### Relationships and interactions
- Frontend ←→ FastAPI: HTTP(S) REST calls for CRUD on devices, automations, energy data, groups, users.
- Frontend → Firebase Auth: user login/registration tokens.
- FastAPI → Business Logic: routes in fastAPI.py delegate to logic modules.
- Business Logic → Data Access: each module calls its corresponding *_db.py to read/write JSON.
- Data Access → Storage: updates JSON files under database/.
- CI/CD → builds/tests: Node workflow runs lint/tests for frontend; Python workflow runs pytest for backend.
- testPDF.py: FastAPI or a cron (not shown) can invoke PDF generator using data from Business Logic.

##### Architectural patterns & design principles
- 3-Tier architecture in backend: Presentation (API), Business Logic, Data Access.
- Component-based UI in frontend with layouts, pages, and shared UI library.
- Separation of concerns: clear boundaries between layers and folders.
- Configuration-as-code: JSON files for automations, energy tips, templates.

##### Relevant technologies
- Frontend: Next.js, React, Tailwind CSS, MUI, Firebase SDK.
- Backend: Python, FastAPI, uvicorn, pytest.
- Data: file-based JSON store, custom Python DB modules.
- CI/CD: GitHub Actions (node.yml, python.yml).

##### Essential elements
– Arrowheads showing request/response and data writes/reads.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        FN["Next.js Frontend\n(React, Tailwind, MUI)"]:::frontend
        FA["Firebase Auth"]:::external
    end

    %% Backend Service
    subgraph "Backend Service"
        API["FastAPI App\n(FastAPI, uvicorn)"]:::api

        subgraph "Business Logic"
            AL["Automations Logic"]:::logic
            DL["Devices Logic"]:::logic
            EL["Energy Logic"]:::logic
            GL["Groups Logic"]:::logic
            UL["Users Logic"]:::logic
        end

        subgraph "Data Access"
            ADB["Automations DB"]:::data
            DDB["Devices DB"]:::data
            DEDB["Daily Energy DB"]:::data
            MEDB["Monthly Energy DB"]:::data
            EGDB["Energy Goal DB"]:::data
            GDB["Groups DB"]:::data
            UDB["Users DB"]:::data
        end

        S["Storage: JSON Files"]:::storage
        UBS["DB Seeding Script\n(update_database.py)"]:::script
        PDF["PDF Generation\n(testPDF.py)"]:::script
    end

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines"
        NP["Node Workflow"]:::cicd
        PP["Python Workflow"]:::cicd
    end

    %% Relationships
    FN -->|"API Calls"| API
    FN -->|"Auth Tokens"| FA

    API -->|"uses"| AL
    API -->|"uses"| DL
    API -->|"uses"| EL
    API -->|"uses"| GL
    API -->|"uses"| UL

    AL -->|"read/write"| ADB
    DL -->|"read/write"| DDB
    EL -->|"read/write"| DEDB
    EL -->|"read/write"| MEDB
    EL -->|"read/write"| EGDB
    GL -->|"read/write"| GDB
    UL -->|"read/write"| UDB

    ADB -->|"persists"| S
    DDB -->|"persists"| S
    DEDB -->|"persists"| S
    MEDB -->|"persists"| S
    EGDB -->|"persists"| S
    GDB -->|"persists"| S
    UDB -->|"persists"| S

    UBS -->|"seeds"| S
    PDF -->|"generates"| S

    NP -->|"build/test"| FN
    PP -->|"build/test"| API

    %% Click Events
    click FN "https://github.com/powerhouse-project/production/tree/main/frontend/src/app"
    click FA "https://github.com/powerhouse-project/production/blob/main/frontend/src/app/firebase/config.js"
    click API "https://github.com/powerhouse-project/production/blob/main/backend/fastAPI.py"
    click AL "https://github.com/powerhouse-project/production/blob/main/backend/automations.py"
    click DL "https://github.com/powerhouse-project/production/blob/main/backend/devices_json.py"
    click EL "https://github.com/powerhouse-project/production/blob/main/backend/energy_json.py"
    click GL "https://github.com/powerhouse-project/production/blob/main/backend/groups.py"
    click UL "https://github.com/powerhouse-project/production/blob/main/backend/users.py"
    click ADB "https://github.com/powerhouse-project/production/blob/main/database/automations_db.py"
    click DDB "https://github.com/powerhouse-project/production/blob/main/database/devices_db.py"
    click DEDB "https://github.com/powerhouse-project/production/blob/main/database/daily_energy_db.py"
    click MEDB "https://github.com/powerhouse-project/production/blob/main/database/monthly_energy_db.py"
    click EGDB "https://github.com/powerhouse-project/production/blob/main/database/energy_goal_db.py"
    click GDB "https://github.com/powerhouse-project/production/blob/main/database/groups_db.py"
    click UDB "https://github.com/powerhouse-project/production/blob/main/database/users_db.py"
    click S "https://github.com/powerhouse-project/production/blob/main/database/users_db.json"
    click UBS "https://github.com/powerhouse-project/production/blob/main/database/update_database.py"
    click NP "https://github.com/powerhouse-project/production/blob/main/.github/workflows/node.yml"
    click PP "https://github.com/powerhouse-project/production/blob/main/.github/workflows/python.yml"
    click PDF "https://github.com/powerhouse-project/production/blob/main/backend/testPDF.py"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef api fill:#C8E6C9,stroke:#43A047,color:#1B5E20
    classDef logic fill:#A5D6A7,stroke:#388E3C,color:#1B5E20
    classDef data fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef storage fill:#FFCC80,stroke:#F57C00,color:#E65100
    classDef external fill:#CE93D8,stroke:#8E24AA,color:#4A148C
    classDef script fill:#B0BEC5,stroke:#546E7A,color:#263238
    classDef cicd fill:#CFD8DC,stroke:#78909C,color:#37474F
```
