# s4nkalp/modus architecture

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

- Interactive diagram: https://gitdiagram.com/s4nkalp/modus
- Repository: https://github.com/s4nkalp/modus

## Overview

##### Project Type and Purpose
- From the README and file tree, the project is clearly a configuration/shell for Hyprland. It serves as a modular desktop environment with components such as bars, launchers, docks, notification popups, etc., all of which work together to create an interactive, customizable user interface.
- The README explicitly calls it “a modular and extensible shell for Hyprland” and further points out that it leverages Fabric.

##### File Structure
- Top-level files include configuration files (e.g., install.sh, main.py, config/ directory) and directories like assets, modules, services, and utils.
- The modules directory is organized into submodules for specific UI components such as “bar”, “launcher”, “dock”, “notification_popup”, and others. Each module typically contains its own components which imply encapsulated functionality.
- The services directory contains service files (e.g., brightness, network, screen_record) that likely run in the background to support UI functionalities.

##### Key Components
a. Core Configuration:
- Config Files: Graphically represent the configuration repository (config/*), showing themes, hypr configurations, and scripts.
- Installation: A reference to the install.sh and setup scripts to show deployment/installation flow.
b. Modules / UI Components:
- Bar Module: Contains various components (battery, system indicators, workspace, etc.) that form the top bar.
- Launcher Module: Contains sub-components (app launcher, Bluetooth, calendar, todo list, etc.) that are activated through the launcher interface.
- Dock and Other Modules: Including notification_popup, osd, and generic modules that are meant for specific functionalities.
c. Services:
- Background services (brightness, network, screen_record) that provide system-level events and interaction endpoints.
d. Assets/Styles:
- Assets: Visual resources (logos, wallpapers, theme files) which are consumed by UI modules.
- Styles: CSS files that define the styling of various visual components.

##### Mapping Relationships and Interactions
- Dependencies:
- The UI modules like the bar and launcher interact with services and external configuration scripts (e.g., hypridle, hyprlock).
- The assets and styles are referenced by both the configuration and the individual modules to render a consistent themed interface.
- Integration with external applications (as noted in the README’s dependency list) such as Fabric, Gnome-Bluetooth, and utility applications like cliphist, brightnessctl, etc.

##### Architectural Patterns and Design Principles
- The design pattern is modular, wherein each functionality (bar, launcher, notification, etc.) is encapsulated into its own directory and code base.
- There’s a clear separation of concerns: configuration and assets are separated from the logic in modules and services.
- The loosely coupled design (using plugins/components architecture) permits extensibility and customizability, which should be visually demonstrated by showing inter-module communication via APIs or event notification patterns.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Initialization
    subgraph "Layer 1: Initialization"
        B["Installation Script (install.sh)"]:::app
    end

    %% Layer 2: Core Application
    subgraph "Layer 2: Core Application"
        I["Fabric (Framework)"]:::external
        J["External Dependencies (Hyprland,GTK,etc.)"]:::external
        A["Main Application (main.py)"]:::app
    end

    %% Layer 3: Configuration
    subgraph "Layer 3: Configuration"
        C["Core Configuration (config/)"]:::config
    end

    %% Layer 4: UI Modules
    subgraph "Layer 4: UI Modules"
        D1["Bar Module (modules/bar)"]:::mod
        D2["Launcher Module (modules/launcher)"]:::mod
        D3["Dock Module (modules/dock.py)"]:::mod
        D4["Notification Popup Module (modules/notification_popup.py)"]:::mod
        D5["OSD Module (modules/osd.py)"]:::mod
    end

    %% Layer 5: Supporting Components
    subgraph "Layer 5: Supporting Components"
        E["Services (services/)"]:::serv
        F["Assets (assets/)"]:::assets
        G["Styles (styles/)"]:::assets
        H["Utilities (utils/)"]:::util
    end

    %% Connections between layers
    B --> A
    I --> A
    J --> A
    A --> C
    A --> D1
    A --> D2
    A --> D3
    A --> D4
    A --> D5
    A --> E
    C --> D1
    C --> D2
    C --> D3
    C --> D4
    C --> D5
    E --> D1
    E --> D2
    E --> D3
    E --> D4
    E --> D5
    F --> D1
    F --> D2
    F --> D3
    F --> D4
    F --> D5
    G --> D1
    G --> D2
    G --> D3
    G --> D4
    G --> D5
    H --> D1
    H --> D2
    H --> D3
    H --> D4
    H --> D5

    %% Click Events
    click A "https://github.com/s4nkalp/modus/blob/main/main.py"
    click B "https://github.com/s4nkalp/modus/blob/main/install.sh"
    click C "https://github.com/s4nkalp/modus/tree/main/config/"
    click D1 "https://github.com/s4nkalp/modus/tree/main/modules/bar/"
    click D2 "https://github.com/s4nkalp/modus/tree/main/modules/launcher/"
    click D3 "https://github.com/s4nkalp/modus/blob/main/modules/dock.py"
    click D4 "https://github.com/s4nkalp/modus/blob/main/modules/notification_popup.py"
    click D5 "https://github.com/s4nkalp/modus/blob/main/modules/osd.py"
    click E "https://github.com/s4nkalp/modus/tree/main/services/"
    click F "https://github.com/s4nkalp/modus/tree/main/assets/"
    click G "https://github.com/s4nkalp/modus/tree/main/styles/"
    click H "https://github.com/s4nkalp/modus/tree/main/utils/"

    %% Styles
    classDef app fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef config fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef mod fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef serv fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef assets fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef util fill:#FFDEAD,stroke:#333,stroke-width:2px;
    classDef external fill:#EEE8AA,stroke:#333,stroke-width:2px;
```
