# jenisdobariya/bullet-github architecture

> Architecture diagram of the GitHub repository jenisdobariya/bullet-github, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jenisdobariya/bullet-github
- Repository: https://github.com/jenisdobariya/bullet-github

## Overview

##### What this project is (type + purpose)
From the file tree, this is a small **Python web application** that serves an **HTML UI** (Jinja-style templates + static JS/CSS) and coordinates a “bullet time booth” workflow:
- `bullettimeBooth/templates/index.html` + `bullettimeBooth/static/*` strongly suggests a **Flask-like** (or similar) server-rendered web app.
- `bullettimeBooth/modules/videoCam.py`, `processBullettime.py`, `bullettimeArray.py` strongly suggest **camera capture + multi-camera orchestration + post-processing** (the “bullet time” effect).
- `bullettimeBooth.py` at the repo root is likely the **main entrypoint** that wires HTTP routes to these modules.

##### How to read the file structure as architecture
Use the tree as a map of deployable/runtime components and internal modules:

##### Runtime / deployable boundaries
- **Web server process (Python)**: likely started via `python bullettimeBooth.py`
- **Browser client**: loads `index.html`, `bullettimebooth.js`, `style.css`
- **Camera devices / OS camera interfaces**: accessed via `modules/videoCam.py` (likely OpenCV or similar)
- **Processing pipeline**: `modules/processBullettime.py`
- **Multi-camera coordination / array config**: `modules/bullettimeArray.py`
- (Potential) **file storage**: not visible in tree, but bullet-time output usually writes images/video to disk; check code paths for output directories and represent them explicitly if present.

##### Internal code organization (module-level)
- `bullettimeBooth/modules/videoCam.py`
Treat as “Camera Adapter / Driver Layer”.
- `bullettimeBooth/modules/bullettimeArray.py`
Treat as “Orchestrator / Topology / Synchronization”.
- `bullettimeBooth/modules/processBullettime.py`
Treat as “Processing / Rendering / Encoding”.

##### Web UI organization
- `templates/index.html`: server-rendered page (UI shell)
- `static/bullettimebooth.js`: client logic (button handlers, API calls, websocket polling, etc.)

##### Browser (User UI)
- Renders `index.html`
- Executes `bullettimebooth.js`
- Makes requests to backend endpoints (HTTP)

##### Python Web App (Entry + Routes)
- `bullettimeBooth.py` (Entry point / route definitions)
- Serves template + static assets

##### BulletTime Orchestrator (Module)
- `modules/bullettimeArray.py`
- Responsibilities to label: camera enumeration, grouping, trigger coordination, sequencing

##### Camera Interface Layer (Module)
- `modules/videoCam.py`
- Responsibilities to label: open camera stream, capture frame(s), manage camera lifecycle, error handling

##### BulletTime Processing Pipeline (Module)
- `modules/processBullettime.py`
- Responsibilities to label: frame alignment, interpolation, encoding, assembling frames into output video/gif/sequence

##### Output Storage (Filesystem)
- Even if not shown in the tree, this is very likely. Represent as “Local Disk” and annotate: “writes captured frames / processed video”
- If code reveals a specific folder (e.g., `outputs/`, `static/results/`), name it precisely.

##### External Dependencies (optional but useful at principal-engineer detail)
- “OpenCV / Camera drivers” (if `videoCam.py` uses cv2)
- “FFmpeg” (if processing spawns ffmpeg)

##### Browser → Python Web App
- “GET / (serves index.html)”, “GET static assets”

##### Camera Interface Layer → Camera Devices
- Camera hardware as separate nodes (Camera #1..#N) if bullet-time depends on multiple viewpoints.

##### Orchestrator → Processing Pipeline
- If processing is async/background, label that: “enqueue job” / “spawn worker thread/process”

##### Python Web App → Output Storage
- Or: “expose download endpoint for produced artifact”

##### Browser ← Python Web App
- If websockets/SSE are used (not visible here), represent as bidirectional channel.

##### Architectural patterns to call out explicitly (based on the structure)
Even without README details, the structure strongly implies:

- **Thin HTTP layer + domain modules**: `bullettimeBooth.py` as integration layer; domain logic in `modules/*`.
- **Adapter pattern for cameras**: `videoCam.py` is a hardware/driver adapter.
- **Pipeline / batch processing**: `processBullettime.py` likely transforms a set of frames into an artifact.
- **Orchestration layer**: `bullettimeArray.py` coordinates multiple cameras and sequences.

##### Clear labels for each component
Use names tied to files:
- “Python Web App (`bullettimeBooth.py`)”
- “Camera Adapter (`modules/videoCam.py`)”
- “Orchestrator (`modules/bullettimeArray.py`)”
- “Processor (`modules/processBullettime.py`)”
- “Web UI (`templates/index.html`, `static/bullettimebooth.js`)”

Bad: “calls”
Good: “POST /capture (start session)”, “trigger capture (N cameras)”, “write artifact (mp4/gif/frames)”

##### To make it maximally accurate with minimal extra effort
- From `bullettimeBooth.py`: route list, how modules are invoked, whether processing is sync/async, where files are written.
- From `videoCam.py`: whether cameras are local USB, IP cams, or files; whether OpenCV/ffmpeg is used.
- From `processBullettime.py`: main processing stages and outputs.
- From `bullettimeArray.py`: how camera count/topology is modeled and how synchronization works.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Plane 1: UI / Control
    %% =========================
    subgraph "User Device"
        U["User"]:::user
        B["Browser (User UI)"]:::client

        subgraph "Web UI Assets"
            T["Template: index.html"]:::client
            JS["Client Logic: bullettimebooth.js"]:::client
            CSS["Styles: style.css"]:::client
        end

        U -->|"clicks Capture/Process/Download"| B
        B -->|"GET / (render template)"| T
        B -->|"GET /static/* (JS/CSS)"| JS
        B -->|"GET /static/* (CSS)"| CSS
    end

    %% =========================
    %% Backend Host Boundary
    %% =========================
    subgraph "Backend Host (Python Web Server + Hardware Control)"
        APP["Python Web App (Entry + Routes)"]:::backend

        subgraph "Domain Modules (in-process)"
            MODPKG["modules package (__init__)"]:::backend

            ORCH["BulletTime Orchestrator (Adapter/Orchestration)"]:::backend
            CAM["Camera Interface Layer (Adapter/Driver)"]:::backend
            PROC["BulletTime Processing Pipeline (Pipeline/Batch)"]:::backend
        end

        FS[("Output Storage (Local Filesystem)")]:::storage

        subgraph "External Dependencies"
            CV["OpenCV / Camera Drivers (optional)"]:::external
            FFM["FFmpeg / Encoder (optional)"]:::external
        end
    end

    %% =========================
    %% Plane 2: Capture (Hardware)
    %% =========================
    subgraph "Capture Plane (Hardware)"
        CAM1["Camera Device #1"]:::hardware
        CAMN["Camera Device #N"]:::hardware
    end

    %% =========================
    %% Interactions / Data Flows
    %% =========================
    B -->|"HTTP: start_capture / status / fetch_result"| APP
    APP -->|"serve HTML + static assets"| B

    APP -->|"invoke capture session"| ORCH
    MODPKG -->|"exports/namespace"| ORCH
    MODPKG -->|"exports/namespace"| CAM
    MODPKG -->|"exports/namespace"| PROC

    ORCH -->|"enumerate + coordinate (1..N cameras)"| CAM
    CAM -->|"OS camera API / streams"| CAM1
    CAM -->|"OS camera API / streams"| CAMN

    ORCH -->|"pass frames/streams for processing"| PROC
    PROC -->|"write artifacts (frames/video/gif)"| FS
    APP -->|"read/serve result files"| FS
    APP -->|"status updates + result URL"| B

    CAM -->|"uses (if available)"| CV
    PROC -->|"encodes via (if available)"| FFM

    %% =========================
    %% Optional sequence inset (vertical)
    %% =========================
    subgraph "Capture Session (High-Level Sequence)"
        S1["1) User clicks Capture"]:::note
        S2["2) Backend starts session"]:::note
        S3["3) Orchestrator triggers N cameras"]:::note
        S4["4) Frames collected + processed"]:::note
        S5["5) Result saved + link returned"]:::note
        S1 --> S2 --> S3 --> S4 --> S5
    end

    B -.->|"drives"| S1
    APP -.->|"coordinates"| S2
    ORCH -.->|"controls"| S3
    PROC -.->|"produces"| S4
    FS -.->|"stores"| S5

    %% =========================
    %% Click Events (mapped paths)
    %% =========================
    click APP "https://github.com/jenisdobariya/bullet-github/blob/main/bullettimeBooth.py"
    click T "https://github.com/jenisdobariya/bullet-github/blob/main/bullettimeBooth/templates/index.html"
    click JS "https://github.com/jenisdobariya/bullet-github/blob/main/bullettimeBooth/static/bullettimebooth.js"
    click CSS "https://github.com/jenisdobariya/bullet-github/blob/main/bullettimeBooth/static/style.css"
    click ORCH "https://github.com/jenisdobariya/bullet-github/blob/main/bullettimeBooth/modules/bullettimeArray.py"
    click CAM "https://github.com/jenisdobariya/bullet-github/blob/main/bullettimeBooth/modules/videoCam.py"
    click PROC "https://github.com/jenisdobariya/bullet-github/blob/main/bullettimeBooth/modules/processBullettime.py"
    click MODPKG "https://github.com/jenisdobariya/bullet-github/blob/main/bullettimeBooth/modules/__init__.py"

    %% =========================
    %% Styles
    %% =========================
    classDef user fill:#E8F1FF,stroke:#2B6CB0,stroke-width:1px,color:#0B2545
    classDef client fill:#D6ECFF,stroke:#1E5AA8,stroke-width:1px,color:#0B2545
    classDef backend fill:#DFF7E6,stroke:#1F7A3A,stroke-width:1px,color:#0B3D1C
    classDef storage fill:#F1E1FF,stroke:#6B2FB9,stroke-width:1px,color:#2B0B45
    classDef hardware fill:#FFE6C7,stroke:#B45309,stroke-width:1px,color:#4A2A00
    classDef external fill:#FFF2CC,stroke:#B08900,stroke-width:1px,color:#4A3B00
    classDef note fill:#F7FAFC,stroke:#718096,stroke-width:1px,color:#1A202C,stroke-dasharray: 3 3
```
