# flynndoh/handful architecture

> Architecture diagram of the GitHub repository flynndoh/handful, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flynndoh/handful
- Repository: https://github.com/flynndoh/handful

## Overview

##### Main System Components

a) Input Layer:
- Sources module (`handful/sources/`) handling video input
- Support for MJPEG streams (`mjpeg.py`)
- Abstract base class for extensibility (`base.py`)

b) Processing Layer:
- Core processing module (`handful/core/`)
- Hand tracking functionality (`tracker.py`)
- Image processing pipeline (`processor.py`)
- Custom type definitions (`types.py`)

c) Output/Interface Layer:
- Web server interface (`handful/server/`)
- Flask-based web application (`app.py`)
- HTML template for visualization (`templates/index.html`)
- CLI interface (`handful/cli/`)

**[Video Input Sources] → [Processing Pipeline] → [Output Interfaces]**
- ↓                        ↓                        ↓
**MJPEG Stream          Hand Detection/Tracking    Web Interface**
- Pose Estimation            CLI Interface
- 3D Space Mapping           Servo Control

##### Key Relationships to Highlight

- Video stream input → Processing pipeline
- Processing pipeline → Web interface
- Processing pipeline → Servo control output
- Real-time feedback loop from processing to output

##### Technical Details

Key technical implementations:
- Flask web server component
- MJPEG stream handling
- Core processing pipeline stages
- Type system integration points

##### Architectural Patterns

Emphasize:
- Pipeline architecture pattern
- Plugin-based source system (based on base.py)
- MVC pattern in the web interface
- Service-based architecture for processing

Remember to:
- Clear labels for each component
- Real-time nature of the system
- Integration points with robotic hardware

This will create a comprehensive system design that accurately represents both the software architecture and the practical application of the system for robotic hand control.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Input
        VS[Video Sources]
        MS["MJPEG Stream"]:::source
        BS["Source Base Class"]:::source
    end

    subgraph Processing
        PP[Processing Pipeline]
        HT["Hand Tracker"]:::processor
        IP["Image Processor"]:::processor
        TD["Type Definitions"]:::processor
    end

    subgraph Output
        WS["Web Server"]:::output
        WT["Web Template"]:::output
        CLI["CLI Interface"]:::output
        SC[Servo Control]
    end

    subgraph Config
        CF["Configuration"]:::config
        EP["Entry Point"]:::config
    end

    subgraph Testing
        ST["Server Tests"]:::test
        SOT["Source Tests"]:::test
        TT["Tracker Tests"]:::test
    end

    VS --> MS
    VS --> BS
    MS --> PP
    BS --> PP
    
    PP --> HT
    PP --> IP
    PP --> TD
    
    HT --> WS
    IP --> WS
    IP --> CLI
    WS --> WT
    IP --> SC
    
    CF --> PP
    CF --> WS
    EP --> PP

    ST --> WS
    SOT --> MS
    SOT --> BS
    TT --> HT

    %% Click Events
    click MS "https://github.com/flynndoh/handful/blob/main/handful/sources/mjpeg.py"
    click BS "https://github.com/flynndoh/handful/blob/main/handful/sources/base.py"
    click HT "https://github.com/flynndoh/handful/blob/main/handful/core/tracker.py"
    click IP "https://github.com/flynndoh/handful/blob/main/handful/core/processor.py"
    click TD "https://github.com/flynndoh/handful/blob/main/handful/core/types.py"
    click WS "https://github.com/flynndoh/handful/blob/main/handful/server/app.py"
    click WT "https://github.com/flynndoh/handful/blob/main/handful/server/templates/index.html"
    click CLI "https://github.com/flynndoh/handful/blob/main/handful/cli/main.py"
    click CF "https://github.com/flynndoh/handful/blob/main/config.yaml"
    click EP "https://github.com/flynndoh/handful/blob/main/main.py"
    click ST "https://github.com/flynndoh/handful/blob/main/tests/test_server.py"
    click SOT "https://github.com/flynndoh/handful/blob/main/tests/test_sources.py"
    click TT "https://github.com/flynndoh/handful/blob/main/tests/test_tracker.py"

    %% Styles
    classDef source fill:#3498db
    classDef processor fill:#2ecc71
    classDef output fill:#e67e22
    classDef config fill:#9b59b6
    classDef test fill:#95a5a6

    %% Legend
    subgraph Legend
        L1[Source Components]:::source
        L2[Processing Components]:::processor
        L3[Output Components]:::output
        L4[Configuration]:::config
        L5[Testing]:::test
    end
```
