# roryclear/clearcam architecture

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

- Interactive diagram: https://gitdiagram.com/roryclear/clearcam
- Repository: https://github.com/roryclear/clearcam

## Overview

##### Project type and purpose
- clearcam is a multi-platform AI-powered security camera solution.
- It includes:
- A Python-based NVR/inference server (clearcam.py, aes.py, experimental modules, yolox) that ingests RTSP streams, runs object detection (YOLOv8 via tinygrad), encrypts video/events, and serves a web UI on localhost:8080.
- Native mobile clients on iOS (Objective-C/Swift UI controllers under ios/clearcam) and Android (Kotlin/Jetpack Compose under android/clearcam/app) for device configuration, viewing live feeds, browsing events, and entering a premium UserID.
- A cloud relay/notification service (implied by “receive streams and notifications” for premium users).

##### File structure
- Top-level Python scripts and requirements.txt drive the NVR server: clearcam.py (entrypoint), aes.py (encryption), yolox/tracker and experimental/… (CV/inference).
- android/clearcam: full Android Studio project with Jetpack Compose UI, build scripts, Google services config.
- ios/clearcam.xcodeproj & ios/clearcam: Xcode project with view controllers, Storyboards, asset catalogs, Python-based Yolo integration, secret management, file server.

##### README for additional insights
- The system must support local NVR + inference and optional premium streaming/notifications via cloud.
- The tech stack: ffmpeg, tinygrad, numpy, OpenCV, SciPy, lap, cython_bbox for inference; Android/Kotlin, iOS/Obj-C/Swift UI.
- Web UI on port 8080, mobile UI clients, end-to-end encryption.

a. Main components
- External RTSP Cameras (IP cameras or old iPhones streaming RTSP)
- Local NVR & Inference Server
– Ingestion (ffmpeg processes)
– Inference Engine (YOLOv8 via tinygrad, yolox/tracker modules)
– Encryption Module (aes.py)
– Storage (local disk for clips/events)
– Web Server/API (serves browser UI, HTTP endpoints on 8080)
- Cloud Relay & Notification Service (premium)
– User Authentication (UserID)
– Encrypted Stream Relay
– Push Notification Gateway
- Client UIs
– Web Browser (React/Vue or simple HTML served by Python)
– Mobile Apps
- iOS (ViewControllers, SceneDelegate…)
- Android (Jetpack Compose screens)

b. Relationships and interactions
1. Cameras → RTSP Ingestion → Inference Engine → Event Detection
2. Inference Engine → Storage of clips/events → Encryption → Local disk
3. Web Browser ⇄ Python Web Server (HTTP/WebSocket) for live view & events
4. Mobile App ⇄ Local or Cloud API for live view & playback
5. Local Server → Cloud Relay (encrypted push of selected streams/events) → Mobile push notifications

c. Architectural patterns & design principles
- Layered architecture:
- Device Layer (RTSP cameras)
- Processing Layer (ingestion, inference, encryption, storage)
- Presentation Layer (web UI, mobile clients)
- Cloud Integration Layer (relay & notifications)
- Modular CV pipeline: separation of ingestion, detection, and tracking (yolox modules)
- End-to-end encryption: cryptographic module isolating data at rest/in-transit
- Micro-frontend style: independent mobile clients and web front end

d. Key technologies & frameworks
- Python: ffmpeg CLI, tinygrad, numpy, OpenCV (cv2), SciPy, lap, cython_bbox
- YOLOv8 model variants (s, m, l, x)
- Android: Kotlin, Jetpack Compose, Google Services
- iOS: Objective-C, Swift UI, Storyboards, StoreKit
- Web: HTTP server on Flask/FastAPI (implied), WebSockets (optional)
- Encryption: AES in aes.py

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Device Layer
    subgraph "Device Layer"
        Cam["External RTSP Cameras"]:::device
    end

    %% Processing Layer
    subgraph "Processing Layer"
        FFmpeg["ffmpeg Ingestor"]:::processing
        subgraph "RTSP Pipelines"
            ClearcamRTSP["clearcam_rtsp.py"]:::processing
            RTSPYOLO["rtsp_yolov8.py"]:::processing
        end
        InferenceYOLO["YOLOv8 Inference Engine\n(via tinygrad)"]:::processing
        TrackerModules["Tracker Modules"]:::processing
        Encryption["Encryption Module\n(AES)"]:::processing
        Storage["Storage (Local Disk)"]:::processing
        WebServer["Python Web/API Server\n(Localhost:8080)"]:::processing
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        Browser["Web Browser Client"]:::presentation
        subgraph "Mobile Apps"
            iOS["iOS Mobile Client"]:::presentation
            Android["Android Mobile Client"]:::presentation
        end
    end

    %% Cloud Integration Layer
    subgraph "Cloud Integration Layer"
        AuthSvc["User Authentication"]:::cloud
        CloudRelay["Cloud Relay & Notification Service"]:::cloud
        Push["Push Notification Gateway"]:::cloud
    end

    %% Connections
    Cam -->|"RTSP Stream"| FFmpeg
    FFmpeg -->|"+ wrapper"| ClearcamRTSP
    ClearcamRTSP -->|"+ pipeline"| RTSPYOLO
    RTSPYOLO -->|"raw frames"| InferenceYOLO
    InferenceYOLO -->|"detections"| TrackerModules
    TrackerModules -->|"events & clips"| Storage
    Storage -->|"encrypt"| Encryption
    Encryption -->|"encrypted data"| Storage
    Storage -->|"serve media"| WebServer
    WebServer -->|HTTP/WebSocket| Browser
    WebServer -->|LAN API| iOS
    WebServer -->|LAN API| Android

    iOS -.->|login| AuthSvc
    Android -.->|login| AuthSvc
    WebServer -->|encrypted push| CloudRelay
    AuthSvc -->|auths users| CloudRelay
    CloudRelay -->|push events| Push
    Push -->|notifications| iOS
    Push -->|notifications| Android
    CloudRelay -->|stream relay| iOS
    CloudRelay -->|stream relay| Android

    %% Click Events
    click WebServer "https://github.com/roryclear/clearcam/blob/main/clearcam.py"
    click Encryption "https://github.com/roryclear/clearcam/blob/main/aes.py"
    click ClearcamRTSP "https://github.com/roryclear/clearcam/blob/main/experimental/clearcam_rtsp.py"
    click RTSPYOLO "https://github.com/roryclear/clearcam/blob/main/experimental/rtsp_yolov8.py"
    click InferenceYOLO "https://github.com/roryclear/clearcam/blob/main/experimental/yolov8.py"
    click TrackerModules "https://github.com/roryclear/clearcam/blob/main/experimental/bytetrack.py"
    click TrackerModules "https://github.com/roryclear/clearcam/tree/main/experimental/yolox/tracker/"
    click TrackerModules "https://github.com/roryclear/clearcam/tree/main/yolox/tracker/"
    click Android "https://github.com/roryclear/clearcam/tree/main/android/clearcam/app/src/main/java/com/rors/clearcam"
    click Android "https://github.com/roryclear/clearcam/blob/main/android/clearcam/app/build.gradle"
    click Android "https://github.com/roryclear/clearcam/blob/main/android/clearcam/settings.gradle"
    click iOS "https://github.com/roryclear/clearcam/blob/main/ios/clearcam.xcodeproj"
    click iOS "https://github.com/roryclear/clearcam/tree/main/ios/clearcam"

    %% Styles
    classDef device fill:#bbdefb,stroke:#1e88e5,color:#0d47a1,stroke-width:2px;
    classDef processing fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20,stroke-width:2px;
    classDef presentation fill:#ffe0b2,stroke:#ef6c00,color:#e65100,stroke-width:2px;
    classDef cloud fill:#e1bee7,stroke:#8e24aa,color:#4a148c,stroke-width:2px;
```
