# psychoducktech/psychos architecture

> Architecture diagram of the GitHub repository psychoducktech/psychos, 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/psychoducktech/psychos
- Repository: https://github.com/psychoducktech/psychos

## Overview

##### Project's Type and Purpose
- PsychOS is firmware for a hardware device (a keyboard-like input platform) that leverages FreeRTOS. It includes features like matrix scanning, rotary encoder handling, display management, USB HID, Bluetooth (BLE) support, buzzer tones, clock functions, and RGB underglow.
- The README confirms that this firmware is tested on the ESP32-S3 and supports several hardware setups. This means the firmware must abstract hardware interactions while managing multiple real-time tasks.

##### File Structure
- The top-level “source” directory houses all the project code and contains subdirectories for include files and source files.
- The “source/src” directory holds the corresponding C/C++ source files. Notably, there are separate directories for tasks (BLEHandler, buzzer, clock, etc.) and utils. This separation hints at a modular design where each hardware function or feature is implemented as an independent task or utility.
- The presence of configuration files (e.g., platformio.ini) and GitHub workflows for building indicates build automation and CI integration.

##### Important Architectural Components
a. Core Firmware/RTOS Layer:
- The firmware runs on FreeRTOS, so include a “Task Manager” component that schedules and manages all independent tasks (e.g., matrix scanning, display updates, rotary encoder, USB HID communication).
b. Hardware Abstraction:
- Driver modules under “drivers” (multiplexer, rotary encoder) as the interface between physical hardware (buttons, encoder, display) and the higher-level tasks.
c. Feature Modules:
- Tasks for each major feature: BLE Handler, Display Handler, Command Processor, Host Communication Bridge, Knob Handler, Matrix Scan, RGB Handler, Serial Handler, WPM Counter, etc.
- A component for “Display & Fonts” (under display and fonts) that is responsible for rendering the user interface.
- “Utils” as supporting modules for benchmarking, initialization of BLE/matrix, EEPROM management (NVS), etc.
d. External and Configuration Elements:
- Build/CI pipeline (GitHub workflows, PlatformIO config) as a separate subsection for development integration.

##### Relationships and Interactions
- Matrix hardware (a multi-key matrix via scanning logic),
- Rotary encoder (for volume control with smooth increment/decrement and a press to mute),
- (using a dedicated display driver, with associated fonts and screen management),
- Buzzers and RGB LED components.
- “Host Communication Bridge” as interfacing with a PC via USB HID (and optionally BLE) to relay the keystrokes and settings.

##### Additional Details
- How initialization modules in “utils” help set up BLE and matrix scanning—this supports the overall system initialization phase.
- To represent the layering: Hardware Interfaces → Drivers → RTOS Task Manager → Application Logic (features) → External Communication.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        ESP["ESP32-S3 Hardware"]:::hardware
    end

    %% Driver Modules
    subgraph "Driver Modules"
        RE["Rotary Encoder Driver"]:::driver
        MP["Multiplexer Driver"]:::driver
    end

    %% RTOS Layer
    subgraph "RTOS Layer"
        TM["Task Manager (FreeRTOS)"]:::rtos
    end

    %% Application Tasks
    subgraph "Application Tasks"
        MS["Matrix Scan Task"]:::task
        BLE["BLE Handler Task"]:::task
        DPH["Display Handler Task & Fonts"]:::task
        CP["Command Processor Task"]:::task
        HCB["Host Communication Bridge Task"]:::task
        KN["Knob Handler Task"]:::task
        BZ["Buzzer Task"]:::task
        CT["Clock Task"]:::task
        RGB["RGB Handler Task"]:::task
        SH["Serial Handler Task"]:::task
        WPM["WPM Counter Task"]:::task
    end

    %% Utilities
    subgraph "Utilities"
        UT["Utilities & Initialization"]:::util
    end

    %% External / CI
    subgraph "External / CI"
        EXT["External Communication (USB_HID/BLE)"]:::external
        CI["Build/CI Pipeline"]:::external
    end

    %% Connections
    ESP --> RE
    ESP --> MP
    RE --> TM
    MP --> TM
    TM --> MS
    TM --> BLE
    TM --> DPH
    TM --> CP
    TM --> HCB
    TM --> KN
    TM --> BZ
    TM --> CT
    TM --> RGB
    TM --> SH
    TM --> WPM
    UT --> TM
    HCB --> EXT
    CI --> TM

    %% Styles
    classDef hardware fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef driver fill:#d6eaf8,stroke:#1f618d,stroke-width:2px;
    classDef rtos fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef task fill:#fadbd8,stroke:#c0392b,stroke-width:2px;
    classDef util fill:#f5cba7,stroke:#e67e22,stroke-width:2px;
    classDef external fill:#ebdef0,stroke:#8e44ad,stroke-width:2px;

    %% Click Events
    click TM "https://github.com/psychoducktech/psychos/blob/main/source/src/main.cpp"
    click TM "https://github.com/psychoducktech/psychos/blob/main/source/include/tasks.h"
    
    click MS "https://github.com/psychoducktech/psychos/blob/main/source/include/tasks/matrixScan.h"
    click MS "https://github.com/psychoducktech/psychos/blob/main/source/src/tasks/matrixScan.cpp"
    
    click RE "https://github.com/psychoducktech/psychos/blob/main/source/include/drivers/rotaryEncoder/KY-040.h"
    
    click MP "https://github.com/psychoducktech/psychos/blob/main/source/include/drivers/multiplexer/CD74HC4067.h"
    
    click BLE "https://github.com/psychoducktech/psychos/blob/main/source/include/tasks/BLEHandler.h"
    click BLE "https://github.com/psychoducktech/psychos/blob/main/source/src/tasks/BLEHandler.cpp"
    
    click DPH "https://github.com/psychoducktech/psychos/blob/main/source/include/tasks/displayHandler.h"
    click DPH "https://github.com/psychoducktech/psychos/blob/main/source/src/tasks/displayHandler.cpp"
    click DPH "https://github.com/psychoducktech/psychos/blob/main/source/include/display/displayContent.h"
    click DPH "https://github.com/psychoducktech/psychos/blob/main/source/include/display/icons.h"
    click DPH "https://github.com/psychoducktech/psychos/blob/main/source/include/display/screens.h"
    click DPH "https://github.com/psychoducktech/psychos/blob/main/source/include/fonts/DucklonMusk_3_520pt7b.h"
    click DPH "https://github.com/psychoducktech/psychos/blob/main/source/include/fonts/FreeMonoBold12pt7b.h"
    
    click CP "https://github.com/psychoducktech/psychos/blob/main/source/include/tasks/commandProcessor.h"
    click CP "https://github.com/psychoducktech/psychos/blob/main/source/src/tasks/commandProcessor.cpp"
    
    click HCB "https://github.com/psychoducktech/psychos/blob/main/source/include/tasks/hostCommunicationBridge.h"
    click HCB "https://github.com/psychoducktech/psychos/blob/main/source/src/tasks/hostCommunicationBridge.cpp"
    
    click KN "https://github.com/psychoducktech/psychos/blob/main/source/include/tasks/knobHandler.h"
    click KN "https://github.com/psychoducktech/psychos/blob/main/source/src/tasks/knobHandler.cpp"
    
    click BZ "https://github.com/psychoducktech/psychos/blob/main/source/include/tasks/buzzer.h"
    click BZ "https://github.com/psychoducktech/psychos/blob/main/source/src/tasks/buzzer.cpp"
    
    click CT "https://github.com/psychoducktech/psychos/blob/main/source/include/tasks/clock.h"
    click CT "https://github.com/psychoducktech/psychos/blob/main/source/src/tasks/clock.cpp"
    
    click RGB "https://github.com/psychoducktech/psychos/blob/main/source/include/tasks/rgbHandler.h"
    click RGB "https://github.com/psychoducktech/psychos/blob/main/source/src/tasks/rgbHandler.cpp"
    
    click SH "https://github.com/psychoducktech/psychos/blob/main/source/include/tasks/serialHandler.h"
    click SH "https://github.com/psychoducktech/psychos/blob/main/source/src/tasks/serialHandler.cpp"
    
    click WPM "https://github.com/psychoducktech/psychos/blob/main/source/include/tasks/wpmCounter.h"
    click WPM "https://github.com/psychoducktech/psychos/blob/main/source/src/tasks/wpmCounter.cpp"
    
    click UT "https://github.com/psychoducktech/psychos/blob/main/source/include/utils/initializeBLE.h"
    click UT "https://github.com/psychoducktech/psychos/blob/main/source/include/utils/initializeMatrix.h"
    click UT "https://github.com/psychoducktech/psychos/blob/main/source/include/utils/benchmark.h"
    click UT "https://github.com/psychoducktech/psychos/blob/main/source/include/utils/nvs.h"
    click UT "https://github.com/psychoducktech/psychos/blob/main/source/src/utils/initializeBLE.cpp"
    click UT "https://github.com/psychoducktech/psychos/blob/main/source/src/utils/initializeMatrix.cpp"
    click UT "https://github.com/psychoducktech/psychos/blob/main/source/src/utils/benchmark.cpp"
    click UT "https://github.com/psychoducktech/psychos/blob/main/source/src/utils/eeprom_manager.cpp"
    click UT "https://github.com/psychoducktech/psychos/blob/main/source/src/utils/nvs.cpp"
    
    click CI "https://github.com/psychoducktech/psychos/blob/main/.github/workflows/build.yml"
    click CI "https://github.com/psychoducktech/psychos/blob/main/source/platformio.ini"
```
