# bevid11/cloudcamsnew architecture

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

- Interactive diagram: https://gitdiagram.com/bevid11/cloudcamsnew
- Repository: https://github.com/bevid11/cloudcamsnew

## Overview

##### Project type and purpose
- CloudCams is an embedded/full-stack “instrument control + image processing” system for astronomy cloud cameras.
- It bundles control logic (image capture, shutter control, exposure scheduling), image solving and plotting, and pushes data to storage and a web front end.

##### File structure
- Top level:
- Dockerfile, docker-compose.yml, GitLab CI (.gitlab-ci.yml) → container build & deploy
- src/ → Python scripts for automation (take_image, shutter_control, timeslapse, auto_brightness, etc.)
- solve/ & plot/ → C programs (solve-field.c, plot-constellations.c) for astrometric reduction and plotting
- astrometry-net-indexes/, astrometrynet_files/, data/ → static data (star catalogs, index files, ephemeris)
- Conceptual_design/ → design docs
- No frontend code here; the PHP web front end and NAS storage live on separate hosts.
- Build scripts and requirements.txt indicate use of Python 3, C, and standard Linux toolchain.

##### Key info from README
- You build a “cloudcams” Docker image.
- No mention of the website or NAS—those are external.
- Deployment is triggered by GitLab Runner in CI.

##### Main components and their interactions
a. CI/CD & Container Build
- GitLab Runner → executes .gitlab-ci.yml → runs Dockerfile → produces cloudcams:latest
b. Deployment Host (could be an on-prem server or cloud VM)
- Runs “cloudcams” container (via docker-compose or direct docker run)
c. CloudCams Container
- Automation service (Python scripts under src/)
- Image solver (solve-field) & plot generator (plot-constellations)
- Data directory mounts (astrometry-net-indexes, data/, astrometrynet_files)
- Network client to statserv for sunrise/sunset and status logging
- Network client to NAS storage for image/data upload
- Network client to Raspberry Pi for GPIO signals
d. Raspberry Pi (external hardware)
- Receives control signals from CloudCams container → toggles camera shutter hardware
- Captures raw images via camera sensor
e. Camera & Shutter (attached to Raspberry Pi)
f. External Services
- statserv (sunrise/sunset API + telemetry logging)
- NAS Storage (SMB/NFS share for raw/processed images and logs)
- PHP Web Front End (on separate Website Server) ← reads from NAS and/or statserv

##### Architectural patterns & design principles
- Modular containerized services: separate build & run phases in CI/CD
- Separation of concerns:
- Control logic (Python) vs. processing logic (C)
- Data storage externalized to NAS
- Presentation tier decoupled (PHP site on its own host)
- Use of standard protocols (HTTP/S for statserv, SMB/NFS for NAS, possibly MQTT/HTTP/gRPC for Pi control)
- Infrastructure as code: Dockerfile & docker-compose.yml

##### Special notes (per custom requirements)
- GitLab Runner step as part of the pipeline.
- Essential services: statserv, Raspberry Pi with its camera and shutter hardware, NAS, Website Server.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        direction TB
        GitlabRunner["GitLab Runner"]:::ci
        CiYml[".gitlab-ci.yml"]:::ci
        DockerfileNode["Dockerfile"]:::ci
        ComposeYml["docker-compose.yml"]:::ci
        Image["cloudcams:latest"]:::ci
        GitlabRunner -->|"executes"| CiYml
        CiYml -->|"uses"| DockerfileNode
        CiYml -->|"uses"| ComposeYml
        DockerfileNode -->|"builds"| Image
    end

    %% Deployment Host
    subgraph "Deployment Host" 
        direction TB
        Image -->|“deploy”| CloudCamsContainer
    end

    %% CloudCams Container Internals
    subgraph "CloudCams Container" 
        direction TB
        subgraph "Automation Service (Python)" 
            direction TB
            AutoProcess["automated_process.py"]:::container
            TakeImage["take_image.py"]:::container
            ShutterCtrl["shutter_control.py"]:::container
            TimeLapse["timeslapse.py"]:::container
            AutoBright["auto_brightness.py"]:::container
            AstrometryPy["astrometry.py"]:::container
            TempMatplot["tempmatplot.py"]:::container
        end
        subgraph "Astrometric Solver (C)" 
            direction TB
            Solver["solve-field.c"]:::container
        end
        subgraph "Constellation Plotter (C)" 
            direction TB
            Plotter["plot-constellations.c"]:::container
        end
        subgraph "Data Mounts" 
            direction TB
            Indexes["astrometry-net-indexes/"]:::container
            AstroFiles["astrometrynet_files/"]:::container
            StaticData["data/"]:::container
        end
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        StatServ["statserv (Sunrise/Sunset API\n& Telemetry)"]:::external
        NAS["NAS Storage (SMB/NFS)"]:::external
        subgraph "Website Server" 
            direction TB
            PHPFront["PHP Web Front End"]:::external
        end
    end

    %% Raspberry Pi Hardware
    subgraph "Raspberry Pi" 
        direction TB
        PiNode["Raspberry Pi"]:::hardware
        PiNode -->|"GPIO"| ShutterHW
        PiNode -->|"GPIO"| CameraHW
        subgraph "Hardware Devices"
            direction TB
            ShutterHW["Shutter"]:::hardware
            CameraHW["Camera"]:::hardware
        end
    end

    %% Connections
    CloudCamsContainer -->|"HTTP/S"| StatServ
    CloudCamsContainer -->|"SMB/NFS"| NAS
    CloudCamsContainer -->|"TCP/HTTP/GPIO"| PiNode
    PHPFront -->|"reads"| NAS

    %% Click Events
    click CiYml "https://github.com/bevid11/cloudcamsnew/blob/main/.gitlab-ci.yml"
    click DockerfileNode "https://github.com/bevid11/cloudcamsnew/tree/main/Dockerfile"
    click ComposeYml "https://github.com/bevid11/cloudcamsnew/blob/main/docker-compose.yml"
    click AutoProcess "https://github.com/bevid11/cloudcamsnew/blob/main/src/automated_process.py"
    click TakeImage "https://github.com/bevid11/cloudcamsnew/blob/main/src/take_image.py"
    click ShutterCtrl "https://github.com/bevid11/cloudcamsnew/blob/main/src/shutter_control.py"
    click TimeLapse "https://github.com/bevid11/cloudcamsnew/blob/main/src/timeslapse.py"
    click AutoBright "https://github.com/bevid11/cloudcamsnew/blob/main/src/auto_brightness.py"
    click AstrometryPy "https://github.com/bevid11/cloudcamsnew/blob/main/src/astrometry.py"
    click TempMatplot "https://github.com/bevid11/cloudcamsnew/blob/main/src/tempmatplot.py"
    click Solver "https://github.com/bevid11/cloudcamsnew/blob/main/solve/solve-field.c"
    click Plotter "https://github.com/bevid11/cloudcamsnew/blob/main/plot/plot-constellations.c"
    click Indexes "https://github.com/bevid11/cloudcamsnew/tree/main/astrometry-net-indexes/"
    click AstroFiles "https://github.com/bevid11/cloudcamsnew/tree/main/astrometrynet_files/"
    click StaticData "https://github.com/bevid11/cloudcamsnew/tree/main/data/"
    click Requirements "https://github.com/bevid11/cloudcamsnew/blob/main/requirements.txt"
    click ConceptDoc "https://github.com/bevid11/cloudcamsnew/blob/main/Conceptual_design/cloudcam_requirements_conceptual_design.md"

    %% Styles
    classDef ci fill:#AED6F1,stroke:#21618C,color:#1B4F72
    classDef container fill:#ABEBC6,stroke:#1D8348,color:#145A32
    classDef hardware fill:#F5CBA7,stroke:#D35400,color:#7E5109
    classDef external fill:#D2B4DE,stroke:#7D3C98,color:#512E5F
```
