How staros-projects/sunscan-backend works
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)