# priyangshu139/photontroppers architecture

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

- Interactive diagram: https://gitdiagram.com/priyangshu139/photontroppers
- Repository: https://github.com/priyangshu139/photontroppers

## Overview

##### Project type and purpose
- This is a backend microservice written in Python using FastAPI (app/main.py + uvicorn).
- It provides REST endpoints to ingest data, train ML models, serve predictions, run shell commands, control a Raspberry Pi, and send Telegram notifications.
- It persists data in a database (app/database.py) and stores serialized scikit-learn models (.pkl) in app/models.

##### File structure
- Top‐level: README, .env, requirements.txt, test.py
- app/main.py – FastAPI app entrypoint; mounts routers
- app/routers/*.py – grouped endpoints by function:
- data_routes (data ingestion)
- train_routes (trigger training)
- predict_routes (model inference)
- getdata_routes (fetch stored data)
- shell_routes (execute shell commands)
- picron_routes (Raspberry Pi control)
- telegram_routes + telegram_notify_routes (Telegram bot integration)
- app/models/*.pkl – pre‐trained/scaler ML artifacts
- app/utils/trainer.py – encapsulates training workflow
- app/database.py – ORM/DB connection code

##### README insights
- Launches with `uvicorn app.main:app --reload`
- Exposes Swagger UI at `/docs`
- No frontend component—purely a service layer

- Labels: use controller/service names matching file names (e.g., PredictRouter)
- Blue rectangles: API/Routers
- Orange rectangles: Services (trainer, model loader)

##### Putting it all together
- Layer 1 (Top): Clients (HTTP, CLI, Telegram User, Raspberry Pi)
- Layer 2: FastAPI container with grouped Routers
- Layer 3: Service layer modules (Data, Train, Predict, Shell, PiControl, TelegramNotify)
- Layer 4 (Bottom): Persistence (Database + Model files) + External services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients"
        direction TB
        HTTP["HTTP Client"]:::external
        CLI["CLI/Shell Scripts"]:::external
        TelegramUser["Telegram User"]:::external
        PiClient["Raspberry Pi"]:::external
    end

    %% FastAPI Application Container
    subgraph "FastAPI App"
        direction TB
        Main["FastAPI App<br/>(app/main.py)"]:::api
        Schem["Schemas<br/>(app/schemas.py)"]:::api
        DBConn["DB Connection<br/>(app/database.py)"]:::api

        subgraph "Routers Layer"
            direction TB
            DataRouter["DataRouter<br/>(data_routes)"]:::api
            GetDataRouter["GetDataRouter<br/>(getdata_routes)"]:::api
            TrainRouter["TrainRouter<br/>(train_routes)"]:::api
            PredictRouter["PredictRouter<br/>(predict_routes)"]:::api
            ShellRouter["ShellRouter<br/>(shell_routes)"]:::api
            PiRouter["PiControlRouter<br/>(picron_routes)"]:::api
            TelegramRouter["TelegramCmdRouter<br/>(telegram_routes)"]:::api
            NotifyRouter["TelegramNotifyRouter<br/>(telegram_notify_routes)"]:::api
        end
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        DataService["Data Ingestion Service"]:::service
        TrainService["Training Service"]:::service
        TrainerUtil["Trainer Util<br/>(app/utils/trainer.py)"]:::service
        PredictService["Prediction Service"]:::service
        ShellService["Shell Execution Service"]:::service
        PiService["Pi Control Service"]:::service
        NotifyService["Telegram Notification Service"]:::service
    end

    %% Persistence & External
    subgraph "Persistence & External"
        direction TB
        DB["Database"]:::db
        Models["Model Store<br/>(app/models/*.pkl)"]:::db
        TelegramAPI["Telegram API"]:::external
        PiHardware["Raspberry Pi Hardware"]:::external
    end

    %% Client to API
    HTTP --> Main
    CLI --> Main
    TelegramUser --> Main
    PiClient --> Main

    %% API Routing
    Main --> DataRouter
    Main --> GetDataRouter
    Main --> TrainRouter
    Main --> PredictRouter
    Main --> ShellRouter
    Main --> PiRouter
    Main --> TelegramRouter
    Main --> NotifyRouter

    %% Routers to Schemas & DBConn
    DataRouter --> Schem
    GetDataRouter --> Schem
    TrainRouter --> Schem
    PredictRouter --> Schem
    ShellRouter --> Schem
    PiRouter --> Schem
    TelegramRouter --> Schem
    NotifyRouter --> Schem
    Main --> DBConn

    %% Routers to Services
    DataRouter --> DataService
    GetDataRouter --> DataService
    TrainRouter --> TrainService
    PredictRouter --> PredictService
    ShellRouter --> ShellService
    PiRouter --> PiService
    TelegramRouter --> NotifyService
    NotifyRouter --> NotifyService

    %% Service interactions
    TrainService --> TrainerUtil
    TrainerUtil --> DB
    TrainerUtil --> Models

    DataService --> DB
    PredictService --> Models
    ShellService --> DBConn
    PiService --> PiHardware
    NotifyService --> TelegramAPI

    %% DBConn to Database
    DBConn --> DB

    %% Click Events
    click Main "https://github.com/priyangshu139/photontroppers/blob/main/app/main.py"
    click DataRouter "https://github.com/priyangshu139/photontroppers/blob/main/app/routers/data_routes.py"
    click GetDataRouter "https://github.com/priyangshu139/photontroppers/blob/main/app/routers/getdata_routes.py"
    click TrainRouter "https://github.com/priyangshu139/photontroppers/blob/main/app/routers/train_routes.py"
    click TrainerUtil "https://github.com/priyangshu139/photontroppers/blob/main/app/utils/trainer.py"
    click PredictRouter "https://github.com/priyangshu139/photontroppers/blob/main/app/routers/predict_routes.py"
    click ShellRouter "https://github.com/priyangshu139/photontroppers/blob/main/app/routers/shell_routes.py"
    click PiRouter "https://github.com/priyangshu139/photontroppers/blob/main/app/routers/picron_routes.py"
    click TelegramRouter "https://github.com/priyangshu139/photontroppers/blob/main/app/routers/telegram_routes.py"
    click NotifyRouter "https://github.com/priyangshu139/photontroppers/blob/main/app/routers/telegram_notify_routes.py"
    click DBConn "https://github.com/priyangshu139/photontroppers/blob/main/app/database.py"
    click Schem "https://github.com/priyangshu139/photontroppers/blob/main/app/schemas.py"
    click Models "https://github.com/priyangshu139/photontroppers/blob/main/app/models/*.pkl"

    %% Styles
    classDef api fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef service fill:#ffe0b3,stroke:#ff9933,color:#000;
    classDef db fill:#d5f5e3,stroke:#28a745,color:#000;
    classDef external fill:#eeeeee,stroke:#999999,color:#000;
```
