# tashifkhan/solarhelper architecture

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

- Interactive diagram: https://gitdiagram.com/tashifkhan/solarhelper
- Repository: https://github.com/tashifkhan/solarhelper

## Overview

##### Project Type and Purpose
- This is a full-stack Solar Helper application combining:
- A React/Vite frontend (TypeScript) delivering an interactive UI (calculator, chat, recommendations, community).
- A Python backend (FastAPI-style routers + Streamlit entrypoint + WSGI) that exposes REST endpoints for chat, power‐prediction, recommendations and web scraping.
- A separate weather-analysis ML training pipeline (LSTM models for monthly/yearly weather forecasts) used offline to produce model artifacts.
- Local file-based “data stores” (CSV/Excel context files, pre-trained ML model pickles and LSTM H5 models).
- External dependencies: OpenAI (LLM), public web sources (via Scrapy).

##### File-Structure Analysis
- Top level: `.gitignore`, `LICENSE`, `README.md`, plus three directories:
- backend/ – server code, routers, services, models, context, prediction_models, Streamlit/WSGI entrypoints.
- frontend/ – React/Vite app with `src/components`, `src/pages`, public assets, config files, Vercel deployment config.
- weather analysis/ – data + scripts for training LSTM weather models.
- backend/services contains business logic (chat_service, power_pipeline, recommendation_service, scrape_service).
- backend/routers routes map HTTP endpoints to service calls.
- backend/prediction_models holds pickled ML artifacts for power prediction; weather models live under weather analysis/models.
- Configuration: `pyproject.toml`, `bun.lock`, `package.json`, type configs for TS.

##### README Insights
- README only provides the project title “SolarHelper.” Detailed architecture isn’t specified there, so structure must be inferred from code layout.

a. Main Components
- Frontend UI (React/Vite)
- API Gateway (FastAPI server / Streamlit entrypoint)
- Service Layer (chat_service, power_prediction_service, recommendation_service, scrape_service)
- Model Store (pickle files / LSTM H5s)
- Context Data Store (CSV / Excel files)
- External Services:
– OpenAI (LLM)
– Public web sources (scraped via Scrapy)
- Training Pipeline (weather_analysis scripts & model trainer)
b. Relationships and Data Flows
1. User interacts with Frontend → HTTP calls to API Gateway.
2. API Gateway → routes request to appropriate service.
3. Service Layer →
– Loads context data (CSV / subsidy info)
– Loads prediction model artifacts → performs inference pipeline.
– Or invokes chat_service → llm_service → OpenAI API → returns LLM response.
– Or runs scrape_service → Scrapy spiders → external web data.
4. Service response → API Gateway → JSON → Frontend.
5. Offline: Training Pipeline reads historical weather data → trains LSTM models → writes to weather_analysis/models → artifacts may feed into backend’s prediction_models.
c. Architectural Patterns and Design Principles
- Clear separation of concerns: routers (API layer) vs. services (business logic) vs. models (data representations).
- File-based datastore for context and model artifacts (no external DB).
- Modular ML pipeline: preprocess → inference → postprocess.
- Extensible scraping and recommendation engines.
- Frontend ↔ Backend decoupling via REST API.
d. Key Technologies and Frameworks
- Frontend: React, Vite, TypeScript, ESLint, Vercel for hosting.
- Backend: Python, FastAPI (implied), Streamlit, Uvicorn/WSGI.
- ML: scikit-learn (pickle), TensorFlow/Keras (LSTM H5).
- Scraping: Scrapy.
- LLM integration: OpenAI API.
- Data processing: pandas reading CSV/Excel.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["React/Vite Frontend"]:::frontend
    end

    %% API Gateway & Routers
    subgraph "API Gateway"
        FASTAPI["FastAPI Server"]:::api
        WSGI["WSGI Interface"]:::api
        STREAM["Streamlit App"]:::api
    end
    subgraph "Routers"
        ChatRouter["Chat Router"]:::api
        PowerRouter["Power Router"]:::api
        RecommendationRouter["Recommendation Router"]:::api
        ScrapeRouter["Scrape Router"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        ChatService["Chat Service"]:::service
        LLMService["LLM Service"]:::service
        PowerPipeline["Power Inference Pipeline"]:::service
        PowerService["Power Prediction Service"]:::service
        RecommendationService["Recommendation Service"]:::service
        ScrapeService["Scrape Service"]:::service
    end

    %% Data Stores
    subgraph "Data Stores"
        ContextStore["Context Data Store"]:::datastore
        ModelStore["Model Store"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
        WebSources["Public Web Sources"]:::external
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        Trainer["LSTM Training Script"]:::training
        CompatGen["Compatibility Generator"]:::training
    end

    subgraph "Trained Models"
        WeatherModels["Weather Models Store"]:::datastore
    end

    %% Connections
    UI -->|Uses API| FASTAPI
    UI -->|Uses API| WSGI
    UI -->|Uses API| STREAM

    FASTAPI -->|routes to| ChatRouter
    FASTAPI -->|routes to| PowerRouter
    FASTAPI -->|routes to| RecommendationRouter
    FASTAPI -->|routes to| ScrapeRouter
    WSGI -->|routes to| ChatRouter
    STREAM -->|routes to| ChatRouter

    ChatRouter -->|calls| ChatService
    ChatService -->|uses| LLMService
    LLMService -->|calls| OpenAI
    PowerRouter -->|calls| PowerService
    PowerService -->|runs| PowerPipeline
    PowerPipeline -->|loads model| ModelStore
    PowerPipeline -->|loads context| ContextStore
    RecommendationRouter -->|calls| RecommendationService
    RecommendationService -->|loads context| ContextStore
    ScrapeRouter -->|calls| ScrapeService
    ScrapeService -->|scrapes| WebSources

    Trainer -->|writes artifacts| WeatherModels
    WeatherModels -->|provides models to| ModelStore
    CompatGen -->|ensures compatibility| WeatherModels

    %% Click Events
    click UI "https://github.com/tashifkhan/solarhelper/tree/main/frontend/"
    click FASTAPI "https://github.com/tashifkhan/solarhelper/blob/main/backend/server.py"
    click WSGI "https://github.com/tashifkhan/solarhelper/blob/main/backend/wsgi.py"
    click STREAM "https://github.com/tashifkhan/solarhelper/blob/main/backend/streamlit.py"
    click ChatRouter "https://github.com/tashifkhan/solarhelper/blob/main/backend/routers/chat.py"
    click PowerRouter "https://github.com/tashifkhan/solarhelper/blob/main/backend/routers/power_prediction.py"
    click RecommendationRouter "https://github.com/tashifkhan/solarhelper/blob/main/backend/routers/recommendation.py"
    click ScrapeRouter "https://github.com/tashifkhan/solarhelper/blob/main/backend/routers/scrape.py"
    click ChatService "https://github.com/tashifkhan/solarhelper/blob/main/backend/services/chat_service.py"
    click LLMService "https://github.com/tashifkhan/solarhelper/blob/main/backend/services/llm_service.py"
    click PowerPipeline "https://github.com/tashifkhan/solarhelper/blob/main/backend/services/power_pipeline.py"
    click PowerService "https://github.com/tashifkhan/solarhelper/blob/main/backend/services/power_prediction_service.py"
    click RecommendationService "https://github.com/tashifkhan/solarhelper/blob/main/backend/services/recommendation_service.py"
    click ScrapeService "https://github.com/tashifkhan/solarhelper/blob/main/backend/services/scrape_service.py"
    click ContextStore "https://github.com/tashifkhan/solarhelper/tree/main/backend/context/"
    click ModelStore "https://github.com/tashifkhan/solarhelper/tree/main/backend/prediction_models/"
    click Trainer "https://github.com/tashifkhan/solarhelper/blob/main/weather analysis/train_lstm_model.py"
    click CompatGen "https://github.com/tashifkhan/solarhelper/blob/main/weather analysis/generate_compatible_model.py"
    click WeatherModels "https://github.com/tashifkhan/solarhelper/tree/main/weather analysis/models/"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#0288D1,color:#000
    classDef api fill:#E8F5E9,stroke:#2E7D32,color:#000
    classDef service fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef datastore fill:#FFE0B2,stroke:#FB8C00,color:#000
    classDef external fill:#FFCDD2,stroke:#C62828,color:#000
    classDef training fill:#E1BEE7,stroke:#8E24AA,color:#000
```
