# aarushchaudhary/the-pathfinder architecture

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

- Interactive diagram: https://gitdiagram.com/aarushchaudhary/the-pathfinder
- Repository: https://github.com/aarushchaudhary/the-pathfinder

## Overview

##### Project Type and Purpose
- The project is a hardware-software integrated robot (rover) that uses a Raspberry Pi 3 as its central controller.
- Its purpose is to offer a low-cost, open-source alternative for automation, featuring multiple control modalities (voice commands, face tracking, controller-based input) along with motor and servo controls.
- The project leverages Python for interfacing with hardware components (motor driver, servos, camera) and for implementing control algorithms (voice recognition, facial tracking, wake word detection).

##### Analyzing the File Structure
- The main logic is contained within the “Main” directory. The files indicate different control functions:
- voice_control_main.py: Implements voice command front-end for driving the rover.
- face_tracking_main_control.py and face_tracking_nopan_main_control.py: Provide face tracking functionalities with and without pan control.
- face_tracking_pantilt.py: Likely handles the pan/tilt mechanism for camera movement.
- game_car.py: Handles control using an Xbox-compatible controller.
- voice_detection_main.py and wakeword_main.py: Are used for voice activation and a wakeword-based control mode.
- centre_servo.py: A utility likely used to return the servos to a default (centered) position.
- The README expands on hardware connections (motor driver pins, servo PWM, camera, etc.), dependencies, and the physical wiring required.

##### Key Components
a. Hardware Components:
- Raspberry Pi 3 Model B (central computing unit).
- L298N motor driver (handles movement/motor control).
- Motor units (geared BO motors for movement).
- Servo motors (for pan and tilt movements).
- Camera (original Raspberry Pi camera or alternative USB webcam).
- Battery pack (power supply, 12V).
- Additional peripherals like the Bluetooth speaker module.

b. Software/Control Components:
- The various Python modules grouped under “Main” to handle different control modes:
- Voice command system (voice_control_main, voice_detection_main, wakeword_main).
- Face tracking system (face_tracking_main_control, face_tracking_nopan_main_control, face_tracking_pantilt).
- Game controller interface (game_car).
- Utility functions (centre_servo).

##### Relationships and Interactions
- Microphone (for voice detection / wake word).
- USB camera (for visual face tracking).
- Xbox controller (for game car input).
- The motor driver controlling wheel motors.
- Servo controller (the pan/tilt module) managing camera orientation.
- A separate path showing power and GPIO connections (as detailed in the README) between the Raspberry Pi and peripheral hardware (e.g., motor driver, servos).

##### Architectural Patterns and Design Principles
- Modular Design: Each “main” Python file encapsulates a specific control mechanism, highlighting separation of concerns.
- Hardware Abstraction: The Python code abstracts underlying hardware details (via libraries and GPIO interfaces).
- Integration with external libraries: Show dependencies on libraries such as mediapipe (for face detection) and SpeechRecognition/pyttsx3 (for voice commands).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input Devices
    subgraph "User Input Devices"
        MIC("Microphone"):::external
        USB("USB Camera"):::external
        CONTROLLER("Xbox Controller"):::external
    end

    %% Processing Modules (Python Scripts)
    subgraph "Processing Modules (Python Scripts)"
        subgraph "Voice Command System"
            VC("Voice Control"):::software
            VD("Voice Detection"):::software
            WW("Wakeword Detection"):::software
        end
        subgraph "Face Tracking System"
            FT("Face Tracking (Main)"):::software
            FTNP("Face Tracking (NoPan)"):::software
            FTP("Face Tracking Pantilt"):::software
        end
        GC("Game Controller Interface"):::software
        SC("Servo Utility"):::software
        DOC("Documentation & Configurations"):::documentation
        MEDIA("Media & Diagrams"):::documentation
    end

    %% Central Controller & Hardware
    subgraph "Central Controller & Hardware"
        RPI("Raspberry Pi 3 Model B"):::hardware
        MD("Motor Driver (L298N)"):::hardware
        MOTORS("Motors (GearedBO)"):::hardware
        SERVOS("Servo Motors (Pan/Tilt)"):::hardware
        CAM("Camera Module"):::hardware
        BATTERY("Battery Pack(12V)"):::hardware
        BLUETOOTH("Bluetooth Speaker Module"):::hardware
    end

    %% Connections from User Input to Processing Modules
    MIC -->|"feeds"| VC
    MIC -->|"feeds"| VD
    MIC -->|"feeds"| WW
    USB -->|"captures"| FT
    USB -->|"captures"| FTNP
    USB -->|"captures"| FTP
    CONTROLLER -->|"controls"| GC

    %% Processing Modules run on Raspberry Pi
    VC -->|"executesOn"| RPI
    VD -->|"executesOn"| RPI
    WW -->|"executesOn"| RPI
    FT -->|"executesOn"| RPI
    FTNP -->|"executesOn"| RPI
    FTP -->|"executesOn"| RPI
    GC -->|"executesOn"| RPI
    SC -->|"runsOn"| RPI
    DOC -->|"provides"| RPI
    MEDIA -->|"references"| RPI

    %% Raspberry Pi controls Hardware
    RPI -->|"commands"| MD
    RPI -->|"controls"| SERVOS
    MD -->|"drives"| MOTORS
    SERVOS -->|"positions"| CAM
    RPI -->|"managesPower"| BATTERY
    RPI -->|"connectsTo"| BLUETOOTH

    %% Click Events for Component Mapping
    click VC "https://github.com/aarushchaudhary/the-pathfinder/blob/main/Main/voice_control_main.py"
    click VD "https://github.com/aarushchaudhary/the-pathfinder/blob/main/Main/voice_detection_main.py"
    click WW "https://github.com/aarushchaudhary/the-pathfinder/blob/main/Main/wakeword_main.py"
    click FT "https://github.com/aarushchaudhary/the-pathfinder/blob/main/Main/face_tracking_main_control.py"
    click FTNP "https://github.com/aarushchaudhary/the-pathfinder/blob/main/Main/face_tracking_nopan_main_control.py"
    click FTP "https://github.com/aarushchaudhary/the-pathfinder/blob/main/Main/face_tracking_pantilt.py"
    click GC "https://github.com/aarushchaudhary/the-pathfinder/blob/main/Main/game_car.py"
    click SC "https://github.com/aarushchaudhary/the-pathfinder/blob/main/Main/centre_servo.py"
    click MEDIA "https://github.com/aarushchaudhary/the-pathfinder/tree/main/Media"
    click DOC "https://github.com/aarushchaudhary/the-pathfinder/blob/main/README.md"

    %% Styles
    classDef external fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef software fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef hardware fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef documentation fill:#FFB6C1,stroke:#333,stroke-width:2px;
```
