# staros-projects/sunscan-backend architecture

> Architecture diagram of the GitHub repository staros-projects/sunscan-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/staros-projects/sunscan-backend
- Repository: https://github.com/staros-projects/sunscan-backend

## Overview

##### Project Type & Purpose
– Full-stack, embedded application (“Sunscan”) that runs on a Raspberry Pi.
– Backend: FastAPI+Uvicorn Python service for device control, image capture/processing, and file-based data management.
– Frontend: React (Vite) SPA served as static assets, providing a browser interface on smartphones/tablets.
– Deployment: pi-gen-sunscan scripts to build a custom Pi OS image; GitHub Actions for CI.

##### File Structure
Top-level:
- app/ – FastAPI application modules:
– main.py (FastAPI app entrypoint)
– camera.py & camera_controller.py (hardware abstraction for camera)
– process.py, Inti_* and hydrogen/helium modules (image-processing pipeline)
– storage.py + app/storage/ (file system persistence: scans, snapshots, tmp)
– config.py, start.sh/stop.sh, requirements.txt
- webapp/ – React/Vite frontend source (src/) and build (dist/)
- pi-gen-sunscan/ – layers & scripts to generate Raspberry Pi OS image with the app preinstalled
- .github/workflows – CI pipeline (build-image.yml)
- package_backend.py – helper to package the backend for pi-gen

##### Extract README Insights
– Backend is a FastAPI service launched via `uvicorn app.main:app`.
– No external DB: uses file-based storage under app/storage.
– Configuration via config.py.
– CI builds images; mobile app is separate.

##### Components & Interactions
a. Main Components
– Client Devices (smartphone/tablet browsers)
– Web Frontend (React SPA)
– API Layer (FastAPI + Uvicorn)
– Business Logic & Image-Processing Modules (camera_controller, process, Inti_*, helium, dedistor, stonyhurst, etc.)
– Storage Layer (Local File System: scans, snapshots, temp)
– Hardware (Raspberry Pi + IMX477 Camera module)
– CI/CD (GitHub Actions) & Deployment Automation (pi-gen-sunscan)

b. Relationships & Data Flows
1. Client → HTTP GET/POST → Frontend
2. Frontend → REST/WebSocket → API Layer
3. API Layer → calls → Business Logic modules
4. Business Logic → controls → Camera Hardware (via camera_controller)
5. Camera Data → raw images → Image-Processing modules → processed images
6. Processed images & metadata → File System Storage
7. Storage → served by → API → → Frontend/UI
8. CI/CD → builds → Docker/OS image → pushed to registry → deployed on Pi

c. Architectural Patterns
– Layered architecture: Presentation → API → Service/Processing → Hardware → Storage
– Modular image-processing pipeline (separate modules for distortion correction, coordinate mapping, line detection)
– Hardware abstraction layer for the camera
– OS image builder (pi-gen) decoupled from application logic

d. Key Technologies & Frameworks
– Python 3.9+, FastAPI, Uvicorn
– React, Vite, JSX, CSS (frontend)
– Raspberry Pi OS, pi-gen
– GitHub Actions (CI)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client & Presentation
    subgraph "Client & Presentation"
        Client["Smartphone/Tablet Browser"]:::external
        subgraph "Frontend"
            FE_src["Source (webapp/src/)"]:::frontend
            FE_dist["Build (webapp/dist/)"]:::frontend
        end
    end

    %% Backend on Raspberry Pi
    subgraph "Backend (Raspberry Pi)"
        subgraph "API Layer"
            API["FastAPI/Uvicorn (main.py)"]:::api
        end

        subgraph "Controller Layer"
            CamCtrl["Camera Controller (camera_controller.py)"]:::service
            CamHW["Camera Abstraction (camera.py)"]:::service
        end

        subgraph "Processing Layer"
            Process["Core Process (process.py)"]:::logic
            Dedistor["Dedistortion Module (dedistor.py)"]:::logic
            Stonyhurst["Stonyhurst Mapping (stonyhurst.py)"]:::logic
            Helium["Helium Module (helium.py)"]:::logic
            IntiFunc["Inti Functions (Inti_functions.py)"]:::logic
            IntiRecon["Inti Recon (Inti_recon.py)"]:::logic
            IntiSerRecon["Inti Serial Recon (Inti_ser_recon.py)"]:::logic
            LocateLines["Line Locator (locate_lines.py)"]:::logic
            JSolex["JSolex (jsolex.py)"]:::logic
        end

        subgraph "Storage Layer"
            StorageMain["Storage API (storage.py)"]:::storage
            subgraph "File System"
                Scans["scans/"]:::storage
                Snapshots["snapshots/"]:::storage
                Tmp["tmp/"]:::storage
            end
        end

        subgraph "Config & Startup"
            ConfigFile["Configuration (config.py)"]:::service
            StartScript["Startup Script (start.sh)"]:::service
            StopScript["Shutdown Script (stop.sh)"]:::service
        end
    end

    %% Hardware
    subgraph "Hardware"
        Pi["Raspberry Pi"]:::hardware
        Camera["IMX477 Camera Module"]:::hardware
    end

    %% Deployment & CI/CD
    subgraph "Deployment & CI/CD"
        CI["GitHub Actions CI (build-image.yml)"]:::deploy
        PiGen["pi-gen-sunscan"]:::deploy
        subgraph "pi-gen Layers"
            P00["00-install/"]:::deploy
            P02["02-copy-app/"]:::deploy
            P03["03-inti/"]:::deploy
            P04["04-system/"]:::deploy
            Prerun["prerun.sh"]:::deploy
        end
        Package["Backend Packager (package_backend.py)"]:::deploy
    end

    %% Connections
    FE_src -->|"build"| FE_dist
    FE_dist -->|"serve static"| Client
    Client -->|"HTTP GET/POST"| API
    API -->|"invoke"| CamCtrl
    API -->|"invoke"| Process
    API -->|"serve files"| StorageMain
    CamCtrl -->|"hardware API"| CamHW
    CamHW -->|"capture image"| Process
    Process -->|"process raw data"| Dedistor
    Process -->|"process raw data"| Stonyhurst
    Process -->|"process raw data"| Helium
    Process -->|"process raw data"| IntiFunc
    Process -->|"process raw data"| IntiRecon
    Process -->|"process raw data"| IntiSerRecon
    Process -->|"process raw data"| LocateLines
    Process -->|"process raw data"| JSolex
    Dedistor -->|"output"| StorageMain
    Stonyhurst -->|"output"| StorageMain
    Helium -->|"output"| StorageMain
    IntiFunc -->|"output"| StorageMain
    IntiRecon -->|"output"| StorageMain
    IntiSerRecon -->|"output"| StorageMain
    LocateLines -->|"output"| StorageMain
    JSolex -->|"output"| StorageMain
    StorageMain -->|"files in"| Scans
    StorageMain -->|"files in"| Snapshots
    StorageMain -->|"files in"| Tmp
    ConfigFile -->|"configures"| API
    StartScript -->|"starts"| API
    StopScript -->|"stops"| API
    API -->|"runs on"| Pi
    Pi -->|"connects to"| Camera
    CI -->|"triggers"| PiGen
    Package -->|"used by"| PiGen
    PiGen -->|"builds image"| Pi

    %% Click Events
    click FE_src "https://github.com/staros-projects/sunscan-backend/tree/main/webapp/src/"
    click FE_dist "https://github.com/staros-projects/sunscan-backend/tree/main/webapp/dist/"
    click API "https://github.com/staros-projects/sunscan-backend/blob/main/app/main.py"
    click CamCtrl "https://github.com/staros-projects/sunscan-backend/blob/main/app/camera_controller.py"
    click CamHW "https://github.com/staros-projects/sunscan-backend/blob/main/app/camera.py"
    click Process "https://github.com/staros-projects/sunscan-backend/blob/main/app/process.py"
    click Dedistor "https://github.com/staros-projects/sunscan-backend/blob/main/app/dedistor.py"
    click Stonyhurst "https://github.com/staros-projects/sunscan-backend/blob/main/app/stonyhurst.py"
    click Helium "https://github.com/staros-projects/sunscan-backend/blob/main/app/helium.py"
    click IntiFunc "https://github.com/staros-projects/sunscan-backend/blob/main/app/Inti_functions.py"
    click IntiRecon "https://github.com/staros-projects/sunscan-backend/blob/main/app/Inti_recon.py"
    click IntiSerRecon "https://github.com/staros-projects/sunscan-backend/blob/main/app/Inti_ser_recon.py"
    click LocateLines "https://github.com/staros-projects/sunscan-backend/blob/main/app/locate_lines.py"
    click JSolex "https://github.com/staros-projects/sunscan-backend/blob/main/app/jsolex.py"
    click StorageMain "https://github.com/staros-projects/sunscan-backend/blob/main/app/storage.py"
    click Scans "https://github.com/staros-projects/sunscan-backend/tree/main/app/storage/scans/"
    click Snapshots "https://github.com/staros-projects/sunscan-backend/tree/main/app/storage/snapshots/"
    click Tmp "https://github.com/staros-projects/sunscan-backend/tree/main/app/storage/tmp/"
    click ConfigFile "https://github.com/staros-projects/sunscan-backend/blob/main/app/config.py"
    click StartScript "https://github.com/staros-projects/sunscan-backend/blob/main/app/start.sh"
    click StopScript "https://github.com/staros-projects/sunscan-backend/blob/main/app/stop.sh"
    click CI "https://github.com/staros-projects/sunscan-backend/blob/main/.github/workflows/build-image.yml"
    click PiGen "https://github.com/staros-projects/sunscan-backend/tree/main/pi-gen-sunscan/"
    click P00 "https://github.com/staros-projects/sunscan-backend/tree/main/pi-gen-sunscan/00-install/"
    click P02 "https://github.com/staros-projects/sunscan-backend/tree/main/pi-gen-sunscan/02-copy-app/"
    click P03 "https://github.com/staros-projects/sunscan-backend/tree/main/pi-gen-sunscan/03-inti/"
    click P04 "https://github.com/staros-projects/sunscan-backend/tree/main/pi-gen-sunscan/04-system/"
    click Prerun "https://github.com/staros-projects/sunscan-backend/blob/main/pi-gen-sunscan/prerun.sh"
    click Package "https://github.com/staros-projects/sunscan-backend/blob/main/package_backend.py"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#42A5F5,color:#0D47A1;
    classDef api fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1;
    classDef service fill:#C8E6C9,stroke:#43A047,color:#1B5E20;
    classDef logic fill:#FFF9C4,stroke:#FDD835,color:#F57F17;
    classDef storage fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef hardware fill:#E8F5E9,stroke:#66BB6A,color:#2E7D32;
    classDef external fill:#F3E5F5,stroke:#AB47BC,color:#4A148C;
    classDef deploy fill:#FFE0B2,stroke:#FB8C00,color:#E65100;
```
