How powerhouse-project/production works
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.