# mizly/wingman architecture

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

- Interactive diagram: https://gitdiagram.com/mizly/wingman
- Repository: https://github.com/mizly/wingman

## Overview

##### Major Components

a. Physical & Hardware Layer:
- Arduino Subsystem:
- Contains arduino_files (e.g., TFTLCDDisplay.ino and motorAndTextController.ino).
- Responsible for controlling display output on the LCD panel and motor functions for movement.

b. Core Python Application (Control & Orchestration):
- Main Controller:
- Modules like main.py and controller.py orchestrate the different functionalities.
- Acts as the central hub, coordinating all subsystems.

c. Vision/Facial Recognition Subsystem:
- Face Recognition:
- Files: facerec.py, cvcont.py, update_face.py, trackinginfo.py.
- Uses the faces/ directory and face_encodings.pkl for recognizing and updating facial data.

d. Natural Language Processing & Conversation:
- NLP Engine:
- Modules: cohere_nlp.py, gemini.py, basic_functionalities.py.
- Likely manages general prompting and conversation handling.

e. Text-to-Speech (TTS) Subsystem:
- TTS Engine:
- Provided by the tiktok_voice package (including tiktok_voice/src/text_to_speech.py, voice.py) and tts.py.
- Converts generated text responses into audio output, which is then possibly played via speakers.

f. Music & External Integrations:
- Music/Spotify Connectivity:
- Handled by music.py (and possibly additional integration in gemini.py) to manage streaming or playing music.

##### Relationships/Interactions

- The Main Controller (main.py) serves as the coordinator. It initiates commands and feeds input/output between subsystems.
- Facial recognition processes visual input (presumably captured externally) and sends recognition results to the central controller.
- NLP processes convert speech to text (speech-to-text not visible directly, though there is TTS and NLP code) and interprets commands; it might interact with both the music functionalities and display movements.
- The TTS subsystem converts text into audio, completing the interaction loop with the user.
- The Arduino subsystem receives commands (possibly via a serial or similar connection) from the Python controller to move the device and update the LCD display with emotions or text.
- Music integration and weather functionalities are triggered based on conversational inputs processed by NLP.

##### Architectural Patterns & Design Principles

- Modularity: Each major functionality (vision, NLP, TTS, hardware control) is separated into its own module or group of modules—a clear separation of concerns.
- Layered Structure: The design cleanly separates low-level hardware control (Arduino) from high-level software logic (Python modules).
- Extensibility: The use of external projects (e.g., TikTok Voice TTS and a face recognition library) indicates that the design accommodates integration with external libraries and services.

##### Technologies & Frameworks

- Arduino IDE/C++ for firmware controlling motors and LCD display.
- Python modules leveraging libraries for NLP and face recognition (referencing GitHub sources provided in the README).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Face Recognition Subsystem
    subgraph "Face Recognition Subsystem"
        FaceRec["facerec.py"]:::vision
        CVCont["cvcont.py"]:::vision
        UpdateFace["update_face.py"]:::vision
        TrackingInfo["trackinginfo.py"]:::vision
        FacesDir["faces/"]:::vision
        FaceEnc["face_encodings.pkl"]:::vision
    end

    %% Main Controller
    subgraph "Main Controller"
        MainPy["main.py"]:::core
        Controller["controller.py"]:::core
    end

    %% Arduino Subsystem
    subgraph "Arduino Subsystem"
        TFT["TFTLCDDisplay.ino"]:::hardware
        Motor["motorAndTextController.ino"]:::hardware
    end

    %% NLP Engine
    subgraph "NLP Engine"
        CohereNLP["cohere_nlp.py"]:::conversation
        Gemini["gemini.py"]:::conversation
        BasicFuncs["basic_functionalities.py"]:::conversation
    end

    %% TTS Engine
    subgraph "TTS Engine"
        TTSFile["tts.py"]:::conversation
        TikTokTTS["tiktok_voice/src/text_to_speech.py"]:::conversation
        TikTokVoice["tiktok_voice/src/voice.py"]:::conversation
        TTSConfig["tiktok_voice/data/config.json"]:::conversation
    end

    %% Music Integration
    subgraph "Music Integration"
        MusicFile["music.py"]:::music
    end

    %% External Services
    Speaker["Speaker"]:::external
    Spotify["Spotify"]:::external

    %% Connections
    FaceRec -->|"feeds"| MainPy
    CVCont -->|"feeds"| MainPy
    UpdateFace -->|"feeds"| MainPy
    TrackingInfo -->|"feeds"| MainPy

    MainPy -->|"commands"| TFT
    Controller -->|"commands"| Motor

    MainPy -->|"triggers"| CohereNLP
    Controller -->|"activates"| MusicFile

    CohereNLP -->|"converts"| TTSFile
    Gemini -->|"converts"| TTSFile
    BasicFuncs -->|"converts"| TTSFile

    CohereNLP -->|"triggers"| MusicFile
    Gemini -->|"triggers"| MusicFile
    BasicFuncs -->|"triggers"| MusicFile

    TTSFile -->|"outputs"| Speaker
    TikTokTTS -->|"outputs"| Speaker
    TikTokVoice -->|"outputs"| Speaker

    MusicFile -->|"streams"| Spotify

    %% Click Events for Arduino Subsystem
    click TFT "https://github.com/mizly/wingman/blob/main/arduino_files/TFTLCDDisplay.ino"
    click Motor "https://github.com/mizly/wingman/blob/main/arduino_files/motorAndTextController.ino"
    click FacesDir "https://github.com/mizly/wingman/tree/main/faces/"
    
    %% Click Events for Main Controller
    click MainPy "https://github.com/mizly/wingman/blob/main/main.py"
    click Controller "https://github.com/mizly/wingman/blob/main/controller.py"
    
    %% Click Events for Face Recognition Subsystem
    click FaceRec "https://github.com/mizly/wingman/blob/main/facerec.py"
    click CVCont "https://github.com/mizly/wingman/blob/main/cvcont.py"
    click UpdateFace "https://github.com/mizly/wingman/blob/main/update_face.py"
    click TrackingInfo "https://github.com/mizly/wingman/blob/main/trackinginfo.py"
    click FaceEnc "https://github.com/mizly/wingman/blob/main/face_encodings.pkl"
    
    %% Click Events for NLP Engine
    click CohereNLP "https://github.com/mizly/wingman/blob/main/cohere_nlp.py"
    click Gemini "https://github.com/mizly/wingman/blob/main/gemini.py"
    click BasicFuncs "https://github.com/mizly/wingman/blob/main/basic_functionalities.py"
    
    %% Click Events for TTS Engine
    click TTSFile "https://github.com/mizly/wingman/blob/main/tts.py"
    click TikTokTTS "https://github.com/mizly/wingman/blob/main/tiktok_voice/src/text_to_speech.py"
    click TikTokVoice "https://github.com/mizly/wingman/blob/main/tiktok_voice/src/voice.py"
    click TTSConfig "https://github.com/mizly/wingman/blob/main/tiktok_voice/data/config.json"
    
    %% Click Event for Music Integration
    click MusicFile "https://github.com/mizly/wingman/blob/main/music.py"

    %% Styles
    classDef hardware fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef core fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef vision fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef conversation fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef music fill:#e6ccff,stroke:#6600cc,stroke-width:2px;
    classDef external fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
```
