# martamateu/smart-tco-calculator architecture

> Architecture diagram of the GitHub repository martamateu/smart-tco-calculator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/martamateu/smart-tco-calculator
- Repository: https://github.com/martamateu/smart-tco-calculator

## Overview

##### Project type and purpose
- This is a full-stack “Smart TCO Calculator” for semiconductor materials:
- Frontend: React + TypeScript app (Vite) hosted on GitHub Pages
- Backend: FastAPI service in Python, containerized (Docker) and deployed to Google Cloud Run
- Purpose: Real-time and static data aggregation, TCO calculations, ML model inference, AI/RAG explanations

##### File structure
- Top-level dirs:
- backend/ → FastAPI code, data sources, ML models, services, routers, utilities, deployment scripts
- components/, contexts/, locales/, services/ → React UI components, i18n, API client
- data/ → static markdown, PDF assets for citations/docs
- config files: Dockerfile, app.yaml, .github/workflows/deploy.yml, tsconfig.json, vite.config.ts, package.json
- Patterns:
- Backend follows layered architecture: routers (API endpoints) → services (business logic) → data_access → data/models
- Data pipeline automated via Cloud Scheduler + scheduler-triggered admin endpoints
- ML inference via a trained Random Forest (tco_random_forest.pkl)
- RAG knowledge base loader + retriever

##### Key architecture points from README
- Cloud Run hosts FastAPI, reads from Cloud Storage (GCS) bucket for cache & static data
- Cloud Scheduler jobs trigger price/material refresh endpoints
- Frontend fetches from backend’s public API (/api/materials, /api/regions, /api/predict, etc.)
- CI/CD: GitHub Actions deploys React app to GH Pages, backend deployed via gcloud
- External systems: ENTSO-E API, EIA API, Materials Project API, Google Gemini AI

##### Final recommendations
- Be detailed: break out major routers (e.g., /api/predict, /api/explain, /api/admin) or group by feature
- Asynchronous flows (scheduler, background ML training, data extraction scripts)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Browser["User Browser"]:::external
        GitHubPages["GitHub Pages (Static Host)"]:::frontend
        Browser -->|loads assets| GitHubPages
        GitHubPages -->|serves| Browser
        Browser -->|HTTPS API requests| FastAPIService
    end

    %% CI/CD Pipeline
    subgraph "CI/CD"
        direction TB
        GHActions["GitHub Actions"]:::cicd
        GHActions -->|deploy frontend| GitHubPages
        GHActions -->|deploy backend| CloudRun
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        CloudRun["Google Cloud Run\nFastAPI Service"]:::backend
        FastAPIService((FastAPI Service)):::backend
        CloudRun --> FastAPIService

        subgraph "API Routers" 
            direction TB
            MaterialsRouter["/api/materials"]:::backend
            RegionsRouter["/api/regions"]:::backend
            TCORouter["/api/predict"]:::backend
            ExplainRouter["/api/explain"]:::backend
            ChatRouter["/api/chat"]:::backend
            AdminRouter["/api/admin"]:::backend
        end

        subgraph "Business Logic Services"
            direction TB
            DataAccess["data_access"]:::backend
            MLEngine["ml_engine"]:::backend
            ChatService["chat_service"]:::backend
        end

        subgraph "RAG Knowledge Layer"
            direction TB
            Loader["loader"]:::backend
            Retriever["retriever"]:::backend
            RAGEngine["rag_engine"]:::backend
        end

        subgraph "Data Models & Artifacts"
            direction TB
            Entities["entities & schemas"]:::backend
            MLModel["tco_random_forest.pkl/json"]:::backend
        end

        MaterialsRouter -->|calls| DataAccess
        RegionsRouter -->|calls| DataAccess
        TCORouter -->|calls| MLEngine
        ExplainRouter -->|calls| RAGEngine
        ChatRouter -->|calls| ChatService
        AdminRouter -->|triggers refresh| DataAccess

        MLEngine --> MLModel
        ChatService --> RAGEngine
        RAGEngine --> Loader
        RAGEngine --> Retriever
        DataAccess -->|CRUD| GCSBucket

        FastAPIService --> MaterialsRouter
        FastAPIService --> RegionsRouter
        FastAPIService --> TCORouter
        FastAPIService --> ExplainRouter
        FastAPIService --> ChatRouter
        FastAPIService --> AdminRouter
    end

    %% Data & Infrastructure
    subgraph "Data & Infrastructure"
        direction TB
        GCSBucket["GCS Bucket (Cache & Static Data)"]:::database
        CloudScheduler["Cloud Scheduler"]:::infra
    end

    CloudScheduler -.->|POST /api/admin/refresh| AdminRouter
    FastAPIService -->|read/write| GCSBucket

    %% External Systems
    subgraph "External Systems"
        direction TB
        ENTSO["ENTSO-E API"]:::external
        EIA["EIA API"]:::external
        MaterialsProj["Materials Project API"]:::external
        GeminiAI["Google Gemini AI"]:::external
    end

    DataAccess --> ENTSO
    DataAccess --> EIA
    DataAccess --> MaterialsProj
    RAGEngine --> GeminiAI

    %% Click Events
    click App_tsx "https://github.com/martamateu/smart-tco-calculator/blob/main/App.tsx"
    click index_tsx "https://github.com/martamateu/smart-tco-calculator/blob/main/index.tsx"
    click index_html "https://github.com/martamateu/smart-tco-calculator/blob/main/index.html"
    click vite_config "https://github.com/martamateu/smart-tco-calculator/blob/main/vite.config.ts"
    click package_json "https://github.com/martamateu/smart-tco-calculator/blob/main/package.json"
    click tsconfig_json "https://github.com/martamateu/smart-tco-calculator/blob/main/tsconfig.json"
    click components_dir "https://github.com/martamateu/smart-tco-calculator/tree/main/components/"
    click language_context "https://github.com/martamateu/smart-tco-calculator/blob/main/contexts/LanguageContext.tsx"
    click locales_dir "https://github.com/martamateu/smart-tco-calculator/tree/main/locales/"
    click api_service "https://github.com/martamateu/smart-tco-calculator/blob/main/services/api.ts"
    click main_py "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/main.py"
    click dockerfile "https://github.com/martamateu/smart-tco-calculator/tree/main/backend/Dockerfile"
    click app_yaml "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/app.yaml"
    click deploy_sh "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/deploy.sh"
    click materials_router "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/routers/materials.py"
    click regions_router "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/routers/regions.py"
    click tco_router "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/routers/tco.py"
    click admin_router "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/routers/admin.py"
    click ml_viz_router "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/routers/ml_visualization.py"
    click rag_viz_router "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/routers/rag_visualization.py"
    click scenarios_router "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/routers/scenarios.py"
    click data_access "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/services/data_access.py"
    click ml_engine "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/services/ml_engine.py"
    click chat_service "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/services/chat_service.py"
    click entities_schemas "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/models/entities.py"
    click schemas "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/models/schemas.py"
    click ml_pkl "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/models/tco_random_forest.pkl"
    click ml_json "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/models/tco_random_forest.json"
    click data_docs "https://github.com/martamateu/smart-tco-calculator/tree/main/backend/data/"
    click cache_files "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/data/cache/energy_prices_live.json"
    click loader "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/data_knowledge_layer/loader.py"
    click retriever "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/data_knowledge_layer/retriever.py"
    click rag_engine_file "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/data_knowledge_layer/rag_engine.py"
    click extract_eu "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/scripts/extract_eu_wholesale_energy_data.py"
    click extract_global "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/scripts/extract_global_electricity_prices.py"
    click extract_usa "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/scripts/extract_usa_electricity_prices.py"
    click scheduler_setup "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/setup_materials_scheduler.sh"
    click cache_utils "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/utils/cache.py"
    click gcs_cache "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/utils/gcs_cache.py"
    click fetch_eia "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/utils/fetch_eia_prices.py"
    click fetch_energy "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/utils/fetch_energy_prices.py"
    click fetch_materials "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/utils/fetch_materials_project.py"
    click data_audit "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/utils/data_audit.py"
    click logger "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/utils/logger.py"
    click mock_explanation "https://github.com/martamateu/smart-tco-calculator/blob/main/backend/utils/mock_explanation.py"
    click workflow "https://github.com/martamateu/smart-tco-calculator/blob/main/ .github/workflows/deploy.yml"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:1px
    classDef backend fill:#90ee90,stroke:#000,stroke-width:1px
    classDef database fill:#ffe4b5,stroke:#000,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef cicd fill:#ffdead,stroke:#000,stroke-width:1px
    classDef infra fill:#fafad2,stroke:#000,stroke-width:1px
```
