# abbiereid/star architecture

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

- Interactive diagram: https://gitdiagram.com/abbiereid/star
- Repository: https://github.com/abbiereid/star

## Overview

##### Project type and purpose
- Star is a Python-based, monolithic “home assistant” application that translates British Sign Language (ASL) gestures into speech and on-screen text. It targets non-verbal users (deaf community) by combining wake-word detection, gesture recognition, text-to-speech, and a simple UI.

##### File structure
- Top level
- main.py: application entry point / orchestrator
- dockerfile, setup.py, requirements.txt: containerization & packaging
- assets/: static images (logo)
- README.md
- models/
- assistant.py: high-level controller for models
- wake_word_model.py: hot-word detection
- sign_language_recognition.py / gesture_recognizer.task / model*.h5 / model6.keras: ASL ML models
- slr_utils/: preprocessing & landmark extraction, recognition logic
- utils/
- camera.py: video capture module
- observer.py: Observer pattern implementation for events
- ui.py: display & GUI management
- textTospeech.py: TTS engine wrapper
- weather.py: optional weather‐info service
- tests/: unit tests for main app and models

##### Key insights from README
- “Star is a home assistant for non-verbal people… focuses on BSL.”

1. Input Layer
- Camera Module (utils/camera.py)
- Wake-word Detector (models/wake_word_model.py)
2. Processing Layer
- Gesture Recognition Engine
– Preprocessor & Landmark Extractor (models/slr_utils)
– ML Model(s) (models/model.h5, model6.keras)
- Command/Intent Manager (models/assistant.py)
- Observer/Event Bus (utils/observer.py)
3. Output Layer
- Text-to-Speech Service (utils/textTospeech.py)
- UI Renderer (utils/ui.py)
- External Info Service (utils/weather.py)
4. Persistence & Config (if any)
- Local model files (models/*.h5)
- config (could be in setup.py or environment)
5. Orchestration
- main.py drives initialization, component wiring, event loop

1. Camera → Frame Buffer → Wake-word Detector → (on “wake” event) → Gesture Recognition
2. Frames → Preprocessor → ML Model → “recognized sign” event → Intent Manager
3. Intent Manager → Observer Bus → Subscribers:
- TTS Service → Audio Output
- Weather Service (optional) → UI
4. main.py wires services: instantiates modules, registers observers, enters processing loop

c. Architectural patterns & design principles:
- Observer Pattern: utils/observer.py decouples producers (recognizer, intent manager) from consumers (UI, TTS).
- Modular Separation: clear Input → Processing → Output layers.
- Single Responsibility: each utils/ and models/ module has one purpose.
- Dependency Injection: main.py passes module instances to one another.

d. Technologies & libraries:
- Python 3.x
- TensorFlow / Keras (models/*.h5, model6.keras)
- OpenCV (in utils/camera.py)
- Pyttsx3 or gTTS (in utils/textTospeech.py)
- Docker (dockerfile) for containerization
- pytest (tests/)

##### Final advice
- Be exhaustive: include every sub-module that plays a role in the runtime.
- Observer pattern explicitly: show Event Bus in the center with spokes to subscribers.
- Don’t overthink—map each top-level directory to a logical subsystem, show how they connect under main.py’s orchestration.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration
    A["Orchestrator\nmain.py"]:::orchestration

    %% Input Layer
    subgraph "Input Layer"
        direction TB
        CAM["Camera Module\nutils/camera.py"]:::input
        WAKE["Wake-word Detector\nmodels/wake_word_model.py"]:::input
    end

    %% Processing Layer
    subgraph "Processing Layer"
        direction TB
        subgraph "Gesture Recognition Engine"
            direction TB
            PREP["Preprocessor & Landmark Extractor\nmodels/slr_utils/ASLrecognition.py\nmodels/slr_utils/landmarker.py\nmodels/slr_utils/recognition.py"]:::process
            MODEL["ML Models\nmodels/model.h5\nmodels/model6.keras"]:::process
            SIGREC["Core Recognition Logic\nmodels/sign_language_recognition.py"]:::process
            TASK["Task Orchestrator\nmodels/gesture_recognizer.task"]:::process
        end
        ASSIST["Command/Intent Manager\nmodels/assistant.py"]:::process
        BUS["Observer/Event Bus\nutils/observer.py"]:::process
    end

    %% Output Layer
    subgraph "Output Layer"
        direction TB
        TTS["Text-to-Speech Service\nutils/textTospeech.py"]:::output
        UI["UI Renderer\nutils/ui.py"]:::output
        WEATHER["External Info Service\nutils/weather.py"]:::output
    end

    %% Persistence & Config
    subgraph "Persistence & Config"
        direction TB
        MODELS["Local Models Storage\nmodels/model.h5\nmodels/model6.keras"]:::persistence
        CONFIG["Packaging & Dependencies\nsetup.py\nrequirements.txt\ndockerfile"]:::persistence
    end

    %% Dependencies & flow
    A -->|initializes| CAM
    A -->|initializes| WAKE
    A -->|wires| ASSIST
    A -->|registers| BUS
    A -->|registers| TTS
    A -->|registers| UI
    A -->|registers| WEATHER

    CAM -->|video frames| WAKE
    WAKE -->|wake event| PREP
    PREP -->|processed frames| MODEL
    MODEL -->|predictions| SIGREC
    SIGREC -->|recognized sign| ASSIST
    ASSIST -->|intent event| BUS

    BUS -->|notify| TTS
    BUS -->|notify| UI
    BUS -->|notify| WEATHER

    MODELS -->|loaded by| MODEL
    CONFIG -->|containerizes| A

    %% Click Events
    click A "https://github.com/abbiereid/star/blob/main/main.py"
    click CAM "https://github.com/abbiereid/star/blob/main/utils/camera.py"
    click WAKE "https://github.com/abbiereid/star/blob/main/models/wake_word_model.py"
    click PREP "https://github.com/abbiereid/star/blob/main/models/slr_utils/ASLrecognition.py"
    click PREP "https://github.com/abbiereid/star/blob/main/models/slr_utils/landmarker.py"
    click PREP "https://github.com/abbiereid/star/blob/main/models/slr_utils/recognition.py"
    click MODEL "https://github.com/abbiereid/star/blob/main/models/model.h5"
    click MODEL "https://github.com/abbiereid/star/blob/main/models/model6.keras"
    click SIGREC "https://github.com/abbiereid/star/blob/main/models/sign_language_recognition.py"
    click TASK "https://github.com/abbiereid/star/blob/main/models/gesture_recognizer.task"
    click ASSIST "https://github.com/abbiereid/star/blob/main/models/assistant.py"
    click BUS "https://github.com/abbiereid/star/blob/main/utils/observer.py"
    click TTS "https://github.com/abbiereid/star/blob/main/utils/textTospeech.py"
    click UI "https://github.com/abbiereid/star/blob/main/utils/ui.py"
    click WEATHER "https://github.com/abbiereid/star/blob/main/utils/weather.py"
    click MODELS "https://github.com/abbiereid/star/blob/main/models/model.h5"
    click MODELS "https://github.com/abbiereid/star/blob/main/models/model6.keras"
    click CONFIG "https://github.com/abbiereid/star/blob/main/setup.py"
    click CONFIG "https://github.com/abbiereid/star/blob/main/requirements.txt"
    click CONFIG "https://github.com/abbiereid/star/tree/main/dockerfile"

    %% Styles
    classDef input fill:#E0F7FA,stroke:#006064,color:#00363a;
    classDef process fill:#FFF3E0,stroke:#E65100,color:#bf360c;
    classDef output fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20;
    classDef external fill:#ECEFF1,stroke:#455A64,color:#263238;
    classDef persistence fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C;
    classDef orchestration fill:#FFEBEE,stroke:#C62828,color:#B71C1C;
```
