# curtismuntz/witness architecture

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

- Interactive diagram: https://gitdiagram.com/curtismuntz/witness
- Repository: https://github.com/curtismuntz/witness

## Overview

##### Project type and purpose
- This is an API-callable webcam project (“Witness”) that provides a networked service for controlling webcams (start/stop recording, calibrate, timelapse, tracking, etc.) and retrieving video data.
- It is written in C++ (server & drivers), Rust (client), uses Protocol Buffers for the API, and is packaged via Bazel + Docker for x86 and ARM devices.
- Use case: robotics testing environments where you want automated, unbiased video capture across multiple physically distributed camera “witnesses.”

##### File structure
- Top-level:
– deploy, docker, docker-compose.yml → container orchestration and multi-arch Docker images
– witness/
- witness/server → monolithic C++ server binary, subdivided into modules (webcam actions, vision, file operations, time, converters)
- witness/drivers → low-level camera wrappers (e.g., amcrest)
- witness/client → Rust CLI bindings + endpoint scripts for calling the server via gRPC/HTTP
- witness/api → .proto definitions of the service interface
– tools, third_party → build rules, external libs, Bazel config
- CI/CD: .github/actions, .github/workflows, ci/, BUILD.bazel, WORKSPACE

##### README for additional insights
- The API is Protobuf/gRPC style (see .proto files)
- The server exposes a gRPC HTTP endpoint listening for commands, writes files to a configured media directory
- Clients invoke the service locally or over network; orchestration via Docker or balena is supported

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        RustCLI["Rust CLI Client"]:::network
        PythonScripts["Python Endpoint Scripts"]:::network
    end

    %% API Layer
    subgraph "API Layer"
        ProtoAPI["Protocol Buffers / API Definitions"]:::network
        GRPCService["gRPC Service (C++ Server)"]:::network
    end

    %% Application Layer
    subgraph "Application Layer"
        Converter["Converter Module"]:::app
        ActionModule["Action Module"]:::app
        VisionModule["Vision Module"]:::app
        DriverModule["Driver Module"]:::app
        WebcamAbstraction["Webcam Abstraction"]:::app
        FileOps["File Operations Module"]:::app
        TimeModule["Time Module"]:::app
    end

    %% Persistence
    FS["Local File System (media_dir)"]:::external

    %% Deployment & Build
    subgraph "Deployment & Build"
        Bazel["Bazel Build System"]:::infra
        Docker["Docker Deployment"]:::infra
        CICD["CI/CD Workflows"]:::infra
    end

    %% External Hardware
    Cameras["Physical Cameras"]:::external

    %% Connections
    RustCLI -->|gRPC Call| GRPCService
    PythonScripts -->|gRPC Call| GRPCService
    ProtoAPI -->|Defines API| GRPCService

    GRPCService -->|Convert Requests| Converter
    Converter -->|Dispatch| ActionModule

    ActionModule -->|Use Vision| VisionModule
    ActionModule -->|Use Driver| DriverModule
    ActionModule -->|Use Time| TimeModule
    ActionModule -->|Write Data| FileOps

    DriverModule -->|Control| Cameras
    FileOps -->|Store Files| FS

    CICD -->|Triggers Build| Bazel
    Bazel -->|Builds Images| Docker

    %% Click Events
    click RustCLI "https://github.com/curtismuntz/witness/blob/master/witness/client/client.rs"
    click PythonScripts "https://github.com/curtismuntz/witness/tree/master/witness/client/endpoint_scripts"
    click ProtoAPI "https://github.com/curtismuntz/witness/blob/master/witness/api/*.proto"
    click GRPCService "https://github.com/curtismuntz/witness/blob/master/witness/server/main.cpp"
    click Converter "https://github.com/curtismuntz/witness/blob/master/witness/server/converters/converters.cpp"
    click ActionModule "https://github.com/curtismuntz/witness/tree/master/witness/server/webcam/actions/"
    click VisionModule "https://github.com/curtismuntz/witness/tree/master/witness/server/vision/"
    click DriverModule "https://github.com/curtismuntz/witness/blob/master/witness/drivers/amcrest.cpp"
    click WebcamAbstraction "https://github.com/curtismuntz/witness/blob/master/witness/server/webcam/webcam.cpp"
    click FileOps "https://github.com/curtismuntz/witness/blob/master/witness/server/file_operations/file_operations.cpp"
    click TimeModule "https://github.com/curtismuntz/witness/blob/master/witness/server/time/time.cpp"
    click Bazel "https://github.com/curtismuntz/witness/blob/master/BUILD.bazel"
    click Docker "https://github.com/curtismuntz/witness/tree/master/docker/"
    click CICD "https://github.com/curtismuntz/witness/tree/master/.github/workflows/"

    %% Styles
    classDef network fill:#ade8f4,stroke:#03396c,color:#03396c
    classDef app fill:#b2f2bb,stroke:#2f9e44,color:#2f9e44
    classDef infra fill:#ffd8a8,stroke:#e67700,color:#e67700
    classDef external fill:#dee2e6,stroke:#495057,color:#495057
```
