# altermundi/sai-cam architecture

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

- Interactive diagram: https://gitdiagram.com/altermundi/sai-cam
- Repository: https://github.com/altermundi/sai-cam

## Overview

##### Project Type and Purpose
- This is an embedded “backend‐only” camera control and access system written in Python, designed to run on a Raspberry Pi (Debian Lite).
- It installs as system services (camera and network daemons), loads YAML‐based configuration, interfaces with the Pi Camera, and exposes a network endpoint or proxy for remote access.

##### File Structure Analysis
- Top‐level directories:
- config/ – holds camera‐proxy script and global config.yaml
- scripts/ – install.sh for one‐step deployment
- src/ – the Python service code (multiple versions/ examples)
- systemd/ – unit files (sai-cam.service, sai-network.service), logrotate config
- Other: requirements.txt (Python deps), README.md, LICENSE, .gitignore.

##### README Insights
- Confirms target platform (Raspberry Pi OS), installation steps via install.sh.

##### Main Components
a. Hardware & OS Layer
- Raspberry Pi device running Debian Lite.
- Pi Camera module connected via CSI port.
b. Service Layer
- camera_service.py (Python process): reads camera frames, applies any proxy logic (config/camera-proxy), serves frames or control API.
- sai-network.service: network‐up script or service that configures network interfaces (e.g., Wi-Fi, Ethernet).
- systemd: orchestrates camera_service and network service lifecycles.
- logrotate: rotates camera service logs (systemd/logrotate.conf).
c. Configuration
- config/config.yaml: runtime settings (resolution, port, authentication).
- camera-proxy script: helper/ wrapper invoked by camera_service.
d. External Clients
- Remote user or application connecting over HTTP/RTSP to camera proxy endpoint.

##### Relationships and Data Flow
- At boot → systemd starts sai-network.service → network interface up.
- systemd then starts sai-cam.service → Python camera_service loads config.yaml and camera-proxy.
- camera_service talks to Pi Camera hardware (via picamera or OpenCV).
- Frames/streams/data are exposed via a network endpoint (HTTP server or streaming port).
- Remote client connects → camera_service responds.
- Logs are written to disk → logrotate rotates them periodically.

##### Architectural Patterns & Design Principles
- Separation of concerns: network configuration vs camera control vs logging.
- Service orchestration with systemd.
- Config‐as‐data: YAML config drives behavior.
- Single‐responsibility scripts: install.sh, proxy helper, python service.

##### Technologies & Frameworks
- Python 3.x (requirements.txt) [e.g., picamera, Flask, PyYAML].
- systemd unit files.
- logrotate.
- Raspberry Pi OS (Debian Lite).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware"
        Pi["Raspberry Pi\n(Debian Lite)"]:::hardware
        Cam["Pi Camera\n(CSI Bus)"]:::hardware
    end

    %% OS & Service Manager Layer
    subgraph "OS & Service Manager"
        Systemd["systemd Service Manager"]:::os
    end

    %% Service Units
    subgraph "Systemd Units"
        NetUnit["sai-network.service"]:::service
        CamUnit["sai-cam.service"]:::service
    end

    %% Application Services and Code
    subgraph "Application Services"
        subgraph "Source Code (src)"
            CSMain["camera_service.py"]:::service
            CSNew["camera_service.new.py"]:::service
            CSOld["camera_service.old.py"]:::service
            CSEx["camera_service.py_example"]:::service
        end
        Proxy["camera-proxy"]:::config
        ConfigYAML["config.yaml"]:::config
        Req["requirements.txt"]:::file
        Logs["Service Logs"]:::file
        LR["logrotate.conf"]:::service
    end

    %% Deployment Script
    Install["install.sh"]:::script

    %% External Clients
    Client["Remote Client\n(HTTP/RTSP)"]:::external

    %% Boot and Deployment Flows
    Install -->|"deploys and configures"| Systemd
    Systemd -->|"boot sequence"| NetUnit
    Systemd -->|"boot sequence"| CamUnit

    %% Network Service
    NetUnit -->|"configures network interfaces"| Systemd

    %% Camera Service Unit
    CamUnit -->|"starts"| CSMain

    %% Config and Dependencies
    CSMain -->|"loads config"| ConfigYAML
    CSMain -->|"invokes helper"| Proxy
    CSMain -->|"uses dependencies"| Req

    %% Hardware Interaction
    CSMain -->|"CSI bus"| Cam
    CSMain -->|"runs on"| Pi

    %% Logging
    CSMain -->|"writes logs"| Logs
    Logs -->|"rotated by"| LR

    %% Client Interaction
    CSMain -->|"streams over HTTP/RTSP"| Client

    %% Click Events
    click CSMain "https://github.com/altermundi/sai-cam/blob/main/src/camera_service.py"
    click CSNew "https://github.com/altermundi/sai-cam/blob/main/src/camera_service.new.py"
    click CSOld "https://github.com/altermundi/sai-cam/blob/main/src/camera_service.old.py"
    click CSEx "https://github.com/altermundi/sai-cam/blob/main/src/camera_service.py_example"
    click NetUnit "https://github.com/altermundi/sai-cam/blob/main/systemd/sai-network.service"
    click CamUnit "https://github.com/altermundi/sai-cam/blob/main/systemd/sai-cam.service"
    click LR "https://github.com/altermundi/sai-cam/blob/main/systemd/logrotate.conf"
    click ConfigYAML "https://github.com/altermundi/sai-cam/blob/main/config/config.yaml"
    click Proxy "https://github.com/altermundi/sai-cam/tree/main/config/camera-proxy"
    click Install "https://github.com/altermundi/sai-cam/blob/main/scripts/install.sh"
    click Req "https://github.com/altermundi/sai-cam/blob/main/requirements.txt"

    %% Styles
    classDef hardware fill:#e0f7e9,stroke:#2e7d32,color:#1b5e20
    classDef os fill:#cce5ff,stroke:#1565c0,color:#0d47a1
    classDef service fill:#fff3bf,stroke:#f9a825,color:#bf360c
    classDef config fill:#fff8e1,stroke:#ffb300,color:#e65100
    classDef script fill:#e1bee7,stroke:#7b1fa2,color:#4a148c
    classDef external fill:#ffd8a8,stroke:#ef6c00,color:#e65100
    classDef file fill:#ececec,stroke:#9e9e9e,color:#424242
```
