# ayushpageni/smart-capture architecture

> Architecture diagram of the GitHub repository ayushpageni/smart-capture, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ayushpageni/smart-capture
- Repository: https://github.com/ayushpageni/smart-capture

## Overview

1. **Overall shape**
   - This repository is a **single-file desktop application**: `app.py` is the only runtime source file, with `requirements.txt` defining the Python dependencies.
   - The architecture is therefore **monolithic but modular by responsibility**: UI, camera source handling, frame capture, and file saving all live in one executable entrypoint.

2. **Primary runtime**
   - The app is a **cross-platform Python 3.8+ GUI** tool.
   - It appears to use a desktop GUI stack such as **Tkinter** for controls and dialogs, and image/video libraries such as **OpenCV** and possibly **PIL/Pillow** for preview and saving.

3. **Main user-facing boundary**
   - The UI is the central orchestration layer.
   - Users choose one of three capture sources: **USB camera**, **IP camera stream**, or **screen/window capture**.
   - The UI also exposes the capture lifecycle: **Connect → Preview → Capture → Save**, plus save-folder selection.

4. **Source acquisition subsystem**
   - The app abstracts three input paths:
     - **USB webcams**: local device enumeration and connection.
     - **IP cameras**: network stream input via MJPEG/H.264 URL.
     - **Screen/window capture**: desktop screenshot or window-region capture.
   - These are distinct input backends but feed the same downstream frame-processing path.

5. **Live preview flow**
   - After connection, frames are read continuously and rendered in the GUI as a live preview.
   - The README says this runs in a **background thread**, which is important because the GUI must stay responsive while streaming.
   - This means the preview loop is separated from the main event loop, with frames passed back into the UI for display.

6. **Capture and freeze behavior**
   - The **Capture** action snapshots the currently displayed frame and freezes it for review.
   - The README mentions a **flash animation effect**, so capture includes a UI feedback step in addition to the raw frame grab.
   - This capture state is separate from ongoing preview, which suggests the app stores the latest frame in memory for later save/export.

7. **Persistence / export subsystem**
   - Saved images are written to the local filesystem, defaulting to a `Captured_Images/` directory.
   - The user can override the destination folder through the GUI.
   - Filenames are optional; if omitted, the app uses a timestamp-based naming scheme.

8. **Platform-specific screen-capture boundary**
   - Screen/window capture is the most platform-dependent part of the architecture.
   - The README indicates:
     - **Windows**: `pygetwindow`, `pyautogui`
     - **macOS**: Quartz / `pyobjc`
     - **Linux**: mostly full-screen capture, with limited window capture support
   - This is a clear conditional subsystem with fallback behavior when optional dependencies are absent.

9. **Device and stream configuration**
   - USB camera mode includes **auto-detection of available devices**, which implies a discovery step before connection.
   - IP camera mode relies on a **user-provided stream URL**, making the network endpoint an external dependency rather than discovered hardware.
   - These two modes differ in discovery but converge on the same frame acquisition interface.

10. **Operational dependencies**
   - The application depends on a small set of runtime libraries listed in `requirements.txt`, plus optional extras for richer screen capture.
   - The presence of OS-specific packages means the repo is designed for **local desktop execution**, not deployment as a server or web service.

11. **Key architectural flow**
   - The end-to-end data path is:
     - **User input in GUI** → **source selection / connection** → **continuous frame acquisition** → **preview rendering** → **capture to memory** → **save to disk**
   - The main architectural separation is between **interactive control**, **frame sourcing**, and **file output**.

12. **What to draw in an architecture diagram**
   - Show `app.py` as the central application boundary.
   - Inside it, depict three inbound source branches: **USB camera**, **IP stream**, and **screen/window capture**.
   - Route them into a shared **frame preview/capture pipeline**, then into a **filesystem output path**.
   - Add the GUI event loop and the background streaming thread as distinct runtime components, since responsiveness depends on that split.

Main entry points: [`app.py`](https://github.com/ayushpageni/smart-capture/blob/main/app.py) (app.py), [`requirements.txt`](https://github.com/ayushpageni/smart-capture/blob/main/requirements.txt) (requirements.txt)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["App runtime"]
  node_app_py["app.py<br/>desktop app<br/>[app.py]"]
  node_gui["Controls<br/>Tkinter GUI"]
  node_loop(("Event loop<br/>UI loop"))
  node_preview_thread(("Preview thread<br/>background worker"))
  node_frame_pipe{{"Frame pipeline<br/>shared flow"}}
  node_capture_action(("Capture<br/>snapshot action"))
  node_flash_fx(("Flash effect<br/>ui feedback"))
  node_source_select{{"Source select<br/>mode switch"}}
  node_requirements["requirements.txt<br/>dependencies<br/>[requirements.txt]"]
end

subgraph group_sources["Input sources"]
  node_usb_cam[("USB camera<br/>local device")]
  node_ip_stream[("IP stream<br/>network source")]
  node_screen_cap[("Screen capture<br/>desktop capture")]
  node_platform_adapters["Platform adapters<br/>OS-specific capture"]
end

subgraph group_output["Persistence"]
  node_save_dialog["Save folder<br/>file chooser"]
  node_snapshot["Captured frame<br/>in-memory image"]
  node_filesystem[("Image files<br/>disk output")]
end

node_app_py -->|"builds"| node_gui
node_app_py -->|"runs"| node_loop
node_app_py -->|"spawns"| node_preview_thread
node_gui -->|"chooses"| node_source_select
node_source_select -->|"routes to"| node_usb_cam
node_source_select -->|"routes to"| node_ip_stream
node_source_select -->|"routes to"| node_screen_cap
node_screen_cap -->|"uses"| node_platform_adapters
node_usb_cam -->|"feeds"| node_frame_pipe
node_ip_stream -->|"feeds"| node_frame_pipe
node_screen_cap -->|"feeds"| node_frame_pipe
node_preview_thread -->|"reads"| node_frame_pipe
node_frame_pipe -->|"renders"| node_gui
node_gui -->|"triggers"| node_capture_action
node_capture_action -->|"stores"| node_snapshot
node_capture_action -->|"animates"| node_flash_fx
node_gui -->|"selects"| node_save_dialog
node_snapshot -->|"writes"| node_filesystem
node_save_dialog -->|"targets"| node_filesystem
node_requirements -.->|"supports"| node_app_py

click node_app_py "https://github.com/ayushpageni/smart-capture/blob/main/app.py"
click node_requirements "https://github.com/ayushpageni/smart-capture/blob/main/requirements.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_py,node_gui,node_loop,node_preview_thread,node_frame_pipe,node_capture_action,node_flash_fx,node_source_select,node_requirements toneBlue
class node_usb_cam,node_ip_stream,node_screen_cap,node_platform_adapters toneAmber
class node_save_dialog,node_snapshot,node_filesystem toneMint
```

## Components

### App runtime

Single-file desktop application boundary and execution flow

- [app.py](https://github.com/ayushpageni/smart-capture/blob/main/app.py): desktop app · Single executable entrypoint containing UI, capture, preview, and save logic · `app.py`
- **Controls**: Tkinter GUI · Main window and user-facing capture controls
- **Event loop**: UI loop · Keeps the desktop interface responsive
- **Preview thread**: background worker · Continuously reads frames without blocking the UI
- **Frame pipeline**: shared flow · Common path for incoming frames before display or capture
- **Capture**: snapshot action · Freezes the current frame for review and export
- **Flash effect**: ui feedback · Visual feedback shown when a frame is captured
- **Source select**: mode switch · Chooses between camera, stream, and screen capture modes
- [requirements.txt](https://github.com/ayushpageni/smart-capture/blob/main/requirements.txt): dependencies · Runtime Python dependency list · `requirements.txt`

### Input sources

Alternative capture backends feeding the shared frame pipeline

- **USB camera**: local device · Auto-detected webcam input
- **IP stream**: network source · User-provided MJPEG or H.264 stream URL
- **Screen capture**: desktop capture · Full-screen or window-region capture backend
- **Platform adapters**: OS-specific capture · Windows, macOS, and Linux capture libraries with fallback behavior

### Persistence

Saving captured images to local storage

- **Save folder**: file chooser · Lets the user choose the destination directory
- **Captured frame**: in-memory image · Frozen frame held before export
- **Image files**: disk output · Saved captures written to Captured_Images or a chosen folder

## Connections

- app.py → Controls: builds · Creates the desktop interface
- app.py → Event loop: runs · Starts the main UI event loop
- app.py → Preview thread: spawns · Uses a background thread for live preview
- Controls → Source select: chooses · User selects a capture mode
- Source select → USB camera: routes to · USB webcam backend
- Source select → IP stream: routes to · Network stream backend
- Source select → Screen capture: routes to · Screen or window backend
- Screen capture → Platform adapters: uses · Platform-specific capture support
- USB camera → Frame pipeline: feeds · Camera frames enter the shared pipeline
- IP stream → Frame pipeline: feeds · Stream frames enter the shared pipeline
- Screen capture → Frame pipeline: feeds · Captured screen frames enter the shared pipeline
- Preview thread → Frame pipeline: reads · Pulls frames for live preview
- Frame pipeline → Controls: renders · Displays the current frame in the interface
- Controls → Capture: triggers · User freezes the current frame
- Capture → Captured frame: stores · Keeps the selected frame in memory
- Capture → Flash effect: animates · Shows capture feedback
- Controls → Save folder: selects · User chooses an output folder
- Captured frame → Image files: writes · Exports the frozen image to disk
- Save folder → Image files: targets · Sets the destination directory
- requirements.txt → app.py: supports · Declares the runtime libraries used by the app