# beginnercoder52/magicmirror architecture

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

- Interactive diagram: https://gitdiagram.com/beginnercoder52/magicmirror
- Repository: https://github.com/beginnercoder52/magicmirror

## Overview

##### Project Type and Overall Purpose
- Recognize that this is a full‐stack desktop application, wrapped in Electron, that leverages a modular plugin system.
- The system core orchestrates modules (found under the “modules” directory) along with client and server functionalities, while configuration and assets (like styles, fonts, images, and translations) support both the display and functionality.

##### Main Components
a. Core Application:
– The “js” folder contains core JavaScript files (e.g., app.js, server.js, module.js) that initialize and manage the overall functionality, logging, and module operations.
– The “config” folder holds configuration files (and templates) necessary to set up different behaviors.

b. Modular Plugins:
– The “modules” directory groups several modules (e.g., MMM-Face-Reco-DNN, MMM-ImageSlideshow, MMM-voice, and many “default” modules such as clock, weather, calendar, etc.) that extend the main application’s functionality.
– Each module typically has its own substructure for its assets (styles, templates, translations) and node helpers that interface with the core.

c. UI/Client Side:
– The “clientonly” folder (with its index.js) and related assets (within “css”, “images”, “fonts”) represent the front-end aspects of the smart mirror display.
– The “index.html” in the root hints the entry point for the UI rendering.

d. Server Side Processes:
– Files present in “serveronly” and several server-related scripts in the “js” folder indicate the backend processes or inter-module communication channels.
– There are also testing directories (“tests”, “tests/e2e”, “tests/unit”) that help validate both server and client modules.

e. Electron Wrapper:
– Although Electron-specific code can be found within the “js/electron.js” file and others, it is key to note that Electron encapsulates the application, effectively serving as both the desktop window and the underlying platform.

f. Support and Configuration Assets:
– Translation files (in “translations”) support locale-based UI.
– Build and formatting configurations (.editorconfig, .prettierconfig.*, eslint, etc.) ensure code quality and consistency.
– Dockerfile and other deployment items hint at potential container-based development/deployment.

##### Relationships and Data Flow
- The core application (JavaScript files under “js” and configuration) acts as the central orchestrator that loads and communicates with each module.
- The Electron wrapper encapsulates both the front-end (UI rendering) and parts of the backend processes.
- The client-side and server-side parts communicate through defined interfaces (API calls, node helpers) to exchange data such as module data, logging, and user interactions.
- Assets like CSS, images, and translations directly feed into the UI, enhancing styling and localization.

##### Key Architectural Patterns and Technologies
- A modular (plugin) architecture where each module works as an independent component, promoted by clear separation between core logic and module extensions.
- Client-server separation even though it’s encapsulated in an Electron environment.
- Utilization of Node.js for backend processes alongside front-end client scripts running under Electron.
- Testing is layered (unit, integration, and end-to-end) to ensure module quality and system stability.

##### Final Detailing
– Emphasize the modular design by drawing more detailed sub-views for the modules directory, especially for important modules like MMM-Face-Reco-DNN, MMM-ImageSlideshow, and MMM-voice.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Electron Wrapper
    subgraph "Electron Wrapper"
        E["Electron Wrapper (js/electron.js)"]:::electron
    end

    %% Core Controller & Config
    subgraph "Core Controller & Config"
        %% Core JS Files
        subgraph "Core JS Files"
            C1["app.js"]:::core
            C2["module.js"]:::core
            C3["server.js"]:::core
            C4["loader.js"]:::core
            C5["logger.js"]:::core
        end
        %% Configuration Files
        subgraph "Configuration Files"
            CF1["config.js"]:::config
            CF2["config.js.sample"]:::config
        end
    end

    %% Modules
    subgraph "Modules"
        M1["MMM-Face-Reco-DNN"]:::module
        M2["MMM-ImageSlideshow"]:::module
        M3["MMM-voice"]:::module
        M4["Default Modules"]:::module
    end

    %% UI / Client Side
    subgraph "UI / Client Side"
        U1["index.html"]:::ui
        U2["clientonly/index.js"]:::ui
        U3["css/main.css"]:::ui
        U4["css/custom.css.sample"]:::ui
        U5["UI Assets (images, fonts)"]:::ui
    end

    %% Server Side Processes
    subgraph "Server Side Processes"
        S1["serveronly/index.js"]:::server
        S2["server_functions.js"]:::server
        S3["node_helper.js"]:::server
    end

    %% Support & Assets
    subgraph "Support & Assets"
        A1["Translations (translations)"]:::assets
        subgraph "Build/Deployment Configs"
            B1["dockerfile"]:::assets
            B2[".editorconfig"]:::assets
            B3[".prettierignore"]:::assets
            B4["eslint.config.mjs"]:::assets
            B5["prettier.config.mjs"]:::assets
        end
    end

    %% High-level Relationships
    E -->|"initiate"| C1
    E -->|"present_UI"| U1
    E -->|"start_server"| S1

    C2 -->|"load_module"| M1
    C1 -->|"configuration"| CF1

    M1 -->|"update_UI"| U1
    M1 -->|"signal_server"| S1

    U2 -->|"render"| U1
    U1 <-->|"API_calls"| S1

    S3 <-->|"helper_calls"| C3

    A1 -->|"localize"| U1

    %% Style definitions
    classDef electron fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef core fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef config fill:#ccffff,stroke:#333,stroke-width:2px;
    classDef module fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef ui fill:#ffebcc,stroke:#333,stroke-width:2px;
    classDef server fill:#e0ccff,stroke:#333,stroke-width:2px;
    classDef assets fill:#d9ead3,stroke:#333,stroke-width:2px;

    %% Click Events for Core Application
    click C1 "https://github.com/beginnercoder52/magicmirror/blob/main/js/app.js"
    click C2 "https://github.com/beginnercoder52/magicmirror/blob/main/js/module.js"
    click C3 "https://github.com/beginnercoder52/magicmirror/blob/main/js/server.js"
    click C4 "https://github.com/beginnercoder52/magicmirror/blob/main/js/loader.js"
    click C5 "https://github.com/beginnercoder52/magicmirror/blob/main/js/logger.js"
    click CF1 "https://github.com/beginnercoder52/magicmirror/blob/main/config/config.js"
    click CF2 "https://github.com/beginnercoder52/magicmirror/blob/main/config/config.js.sample"

    %% Click Events for Modular Plugins
    click M1 "https://github.com/beginnercoder52/magicmirror/tree/main/modules/MMM-Face-Reco-DNN"
    click M2 "https://github.com/beginnercoder52/magicmirror/tree/main/modules/MMM-ImageSlideshow"
    click M3 "https://github.com/beginnercoder52/magicmirror/tree/main/modules/MMM-voice"
    click M4 "https://github.com/beginnercoder52/magicmirror/tree/main/modules/default"

    %% Click Events for UI / Client Side
    click U1 "https://github.com/beginnercoder52/magicmirror/blob/main/index.html"
    click U2 "https://github.com/beginnercoder52/magicmirror/blob/main/clientonly/index.js"
    click U3 "https://github.com/beginnercoder52/magicmirror/blob/main/css/main.css"
    click U4 "https://github.com/beginnercoder52/magicmirror/blob/main/css/custom.css.sample"

    %% Click Events for Server Side Processes
    click S1 "https://github.com/beginnercoder52/magicmirror/blob/main/serveronly/index.js"
    click S2 "https://github.com/beginnercoder52/magicmirror/blob/main/js/server_functions.js"
    click S3 "https://github.com/beginnercoder52/magicmirror/blob/main/js/node_helper.js"

    %% Click Event for Electron Wrapper
    click E "https://github.com/beginnercoder52/magicmirror/blob/main/js/electron.js"

    %% Click Events for Support & Assets
    click A1 "https://github.com/beginnercoder52/magicmirror/tree/main/translations"
    click B1 "https://github.com/beginnercoder52/magicmirror/tree/main/dockerfile"
    click B2 "https://github.com/beginnercoder52/magicmirror/blob/main/.editorconfig"
    click B3 "https://github.com/beginnercoder52/magicmirror/blob/main/.prettierignore"
    click B4 "https://github.com/beginnercoder52/magicmirror/blob/main/eslint.config.mjs"
    click B5 "https://github.com/beginnercoder52/magicmirror/blob/main/prettier.config.mjs"
```
