# magicmirrororg/magicmirror architecture

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

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

## Overview

MagicMirror² is a modular smart-mirror platform wrapped by Electron, with a server-only mode and a client-only launcher for connecting to a remote server. The principal workflow is application startup, configuration and module loading, serving the mirror interface, and displaying module-provided information. Major built-in capabilities include calendar, news, weather, clock, compliments, alerts, and update notifications. The graph includes those documented-by-tree product features, but the sampled source does not show all their wiring; unverified module relationships are therefore omitted.

Main entry points: [`js/server.js`](https://github.com/magicmirrororg/magicmirror/blob/master/js/server.js) (HTTP and Socket server), [`js/main.js`](https://github.com/magicmirrororg/magicmirror/blob/master/js/main.js) (Mirror bootstrap), [`js/app.js`](https://github.com/magicmirrororg/magicmirror/blob/master/js/app.js) (Application lifecycle), [`defaultmodules/weather/providers/fmi.js`](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/weather/providers/fmi.js) (FMI provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application runtime"]
  node_electron["Electron wrapper<br/>[electron.js]"]
  node_client_launcher["Remote client launcher<br/>[index.js]"]
  node_app["Application lifecycle<br/>[app.js]"]
  node_server_entry["Server-only entry<br/>[index.js]"]
end

subgraph group_transport["Serving and communication"]
  node_server["HTTP and Socket server<br/>[server.js]"]
  node_client_main["Mirror bootstrap<br/>[main.js]"]
  node_module_loader["Module loader<br/>[loader.js]"]
  node_module_api["Module API<br/>[module.js]"]
  node_socket_client["Module socket client<br/>[socketclient.js]"]
end

subgraph group_calendar_news["Calendar and news"]
  node_calendar_view["Calendar display<br/>[calendar.js]"]
  node_calendar_fetcher["Calendar fetcher<br/>[calendarfetcher.js]"]
  node_calendar_fetch_utils["Calendar data utilities"]
  node_calendar_helper["Calendar server helper<br/>[node_helper.js]"]
  node_news_view["News display<br/>[newsfeed.js]"]
  node_news_fetcher["News fetcher<br/>[newsfeedfetcher.js]"]
  node_feed_items["Feed item normalization<br/>[feeditem.js]"]
  node_news_helper["News server helper<br/>[node_helper.js]"]
end

subgraph group_weather["Weather"]
  node_weather_view["Weather display<br/>[weather.js]"]
  node_weather_data["Weather objects<br/>[weatherobject.js]"]
  node_weather_helper["Weather server helper<br/>[node_helper.js]"]
  node_weather_provider["Weather provider base<br/>[weatherprovider.js]"]
  node_weather_provider_utils["Provider utilities<br/>[provider-utils.js]"]
  node_openmeteo["Open-Meteo provider<br/>[openmeteo.js]"]
  node_fmi["FMI provider<br/>[fmi.js]"]
end

subgraph group_display["Display modules"]
  node_clock["Clock<br/>[clock.js]"]
  node_compliments["Compliments<br/>[compliments.js]"]
  node_alerts["Alerts and notifications<br/>[alert.js]"]
  node_update_notice["Update notifications"]
end

node_user(("Mirror user"))

node_user -->|"starts mirror"| node_electron
node_electron -.->|"starts application"| node_app
node_user -->|"starts remote client"| node_client_launcher
node_client_launcher -->|"requests config"| node_server
node_server_entry -->|"starts application"| node_app
node_app -->|"creates server"| node_server
node_server -->|"serves mirror UI"| node_user
node_client_main -->|"loads modules"| node_module_loader
node_client_main -->|"initializes bridge"| node_module_api
node_client_main -.->|"renders interface"| node_user
node_calendar_fetcher -->|"filters calendar data"| node_calendar_fetch_utils
node_news_fetcher -->|"normalizes feed items"| node_feed_items
node_fmi -->|"extends provider"| node_weather_provider
node_fmi -->|"validates coordinates"| node_weather_provider_utils
node_openmeteo -->|"extends provider"| node_weather_provider
node_socket_client -.->|"opens Socket.IO connection"| node_server

click node_electron "https://github.com/magicmirrororg/magicmirror/blob/master/js/electron.js"
click node_client_launcher "https://github.com/magicmirrororg/magicmirror/blob/master/clientonly/index.js"
click node_app "https://github.com/magicmirrororg/magicmirror/blob/master/js/app.js"
click node_server_entry "https://github.com/magicmirrororg/magicmirror/blob/master/serveronly/index.js"
click node_server "https://github.com/magicmirrororg/magicmirror/blob/master/js/server.js"
click node_client_main "https://github.com/magicmirrororg/magicmirror/blob/master/js/main.js"
click node_module_loader "https://github.com/magicmirrororg/magicmirror/blob/master/js/loader.js"
click node_module_api "https://github.com/magicmirrororg/magicmirror/blob/master/js/module.js"
click node_socket_client "https://github.com/magicmirrororg/magicmirror/blob/master/js/socketclient.js"
click node_calendar_view "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/calendar/calendar.js"
click node_calendar_fetcher "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/calendar/calendarfetcher.js"
click node_calendar_fetch_utils "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/calendar/calendarfetcherutils.js"
click node_calendar_helper "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/calendar/node_helper.js"
click node_news_view "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/newsfeed/newsfeed.js"
click node_news_fetcher "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/newsfeed/newsfeedfetcher.js"
click node_feed_items "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/newsfeed/feeditem.js"
click node_news_helper "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/newsfeed/node_helper.js"
click node_weather_view "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/weather/weather.js"
click node_weather_data "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/weather/weatherobject.js"
click node_weather_helper "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/weather/node_helper.js"
click node_weather_provider "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/weather/weatherprovider.js"
click node_weather_provider_utils "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/weather/provider-utils.js"
click node_openmeteo "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/weather/providers/openmeteo.js"
click node_fmi "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/weather/providers/fmi.js"
click node_clock "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/clock/clock.js"
click node_compliments "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/compliments/compliments.js"
click node_alerts "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/alert/alert.js"
click node_update_notice "https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/updatenotification/updatenotification.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_electron,node_client_launcher,node_app,node_server_entry,node_user toneBlue
class node_server,node_client_main,node_module_loader,node_module_api,node_socket_client toneAmber
class node_calendar_view,node_calendar_fetcher,node_calendar_fetch_utils,node_calendar_helper,node_news_view,node_news_fetcher,node_feed_items,node_news_helper toneMint
class node_weather_view,node_weather_data,node_weather_helper,node_weather_provider,node_weather_provider_utils,node_openmeteo,node_fmi toneRose
class node_clock,node_compliments,node_alerts,node_update_notice toneIndigo
```

## Components

### Application runtime

- [Electron wrapper](https://github.com/magicmirrororg/magicmirror/blob/master/js/electron.js): `js/electron.js`
- [Remote client launcher](https://github.com/magicmirrororg/magicmirror/blob/master/clientonly/index.js): `clientonly/index.js`
- [Application lifecycle](https://github.com/magicmirrororg/magicmirror/blob/master/js/app.js): `js/app.js`
- [Server-only entry](https://github.com/magicmirrororg/magicmirror/blob/master/serveronly/index.js): `serveronly/index.js`

### Serving and communication

- [HTTP and Socket server](https://github.com/magicmirrororg/magicmirror/blob/master/js/server.js): `js/server.js`
- [Mirror bootstrap](https://github.com/magicmirrororg/magicmirror/blob/master/js/main.js): `js/main.js`
- [Module loader](https://github.com/magicmirrororg/magicmirror/blob/master/js/loader.js): `js/loader.js`
- [Module API](https://github.com/magicmirrororg/magicmirror/blob/master/js/module.js): `js/module.js`
- [Module socket client](https://github.com/magicmirrororg/magicmirror/blob/master/js/socketclient.js): `js/socketclient.js`

### Calendar and news

- [Calendar display](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/calendar/calendar.js): `defaultmodules/calendar/calendar.js`
- [Calendar fetcher](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/calendar/calendarfetcher.js): `defaultmodules/calendar/calendarfetcher.js`
- [Calendar data utilities](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/calendar/calendarfetcherutils.js): `defaultmodules/calendar/calendarfetcherutils.js`
- [Calendar server helper](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/calendar/node_helper.js): `defaultmodules/calendar/node_helper.js`
- [News display](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/newsfeed/newsfeed.js): `defaultmodules/newsfeed/newsfeed.js`
- [News fetcher](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/newsfeed/newsfeedfetcher.js): `defaultmodules/newsfeed/newsfeedfetcher.js`
- [Feed item normalization](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/newsfeed/feeditem.js): `defaultmodules/newsfeed/feeditem.js`
- [News server helper](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/newsfeed/node_helper.js): `defaultmodules/newsfeed/node_helper.js`

### Weather

- [Weather display](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/weather/weather.js): `defaultmodules/weather/weather.js`
- [Weather objects](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/weather/weatherobject.js): `defaultmodules/weather/weatherobject.js`
- [Weather server helper](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/weather/node_helper.js): `defaultmodules/weather/node_helper.js`
- [Weather provider base](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/weather/weatherprovider.js): `defaultmodules/weather/weatherprovider.js`
- [Provider utilities](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/weather/provider-utils.js): `defaultmodules/weather/provider-utils.js`
- [Open-Meteo provider](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/weather/providers/openmeteo.js): `defaultmodules/weather/providers/openmeteo.js`
- [FMI provider](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/weather/providers/fmi.js): `defaultmodules/weather/providers/fmi.js`

### Display modules

- [Clock](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/clock/clock.js): `defaultmodules/clock/clock.js`
- [Compliments](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/compliments/compliments.js): `defaultmodules/compliments/compliments.js`
- [Alerts and notifications](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/alert/alert.js): `defaultmodules/alert/alert.js`
- [Update notifications](https://github.com/magicmirrororg/magicmirror/blob/master/defaultmodules/updatenotification/updatenotification.js): `defaultmodules/updatenotification/updatenotification.js`

### Other components

- **Mirror user**

## Connections

- Mirror user → Electron wrapper: starts mirror
- Electron wrapper → Application lifecycle: starts application
- Mirror user → Remote client launcher: starts remote client (evidence: `clientonly/index.js`)
- Remote client launcher → HTTP and Socket server: requests config (evidence: `clientonly/index.js`)
- Server-only entry → Application lifecycle: starts application (evidence: `serveronly/index.js`)
- Application lifecycle → HTTP and Socket server: creates server (evidence: `js/app.js`)
- HTTP and Socket server → Mirror user: serves mirror UI (evidence: `js/server.js`)
- Mirror bootstrap → Module loader: loads modules (evidence: `js/main.js`)
- Mirror bootstrap → Module API: initializes bridge (evidence: `js/main.js`)
- Mirror bootstrap → Mirror user: renders interface
- Calendar fetcher → Calendar data utilities: filters calendar data (evidence: `defaultmodules/calendar/calendarfetcher.js`)
- News fetcher → Feed item normalization: normalizes feed items (evidence: `defaultmodules/newsfeed/newsfeedfetcher.js`)
- FMI provider → Weather provider base: extends provider (evidence: `defaultmodules/weather/providers/fmi.js`)
- FMI provider → Provider utilities: validates coordinates (evidence: `defaultmodules/weather/providers/fmi.js`)
- Open-Meteo provider → Weather provider base: extends provider (evidence: `defaultmodules/weather/providers/openmeteo.js`)
- Module socket client → HTTP and Socket server: opens Socket.IO connection
