# arksine/moonraker architecture

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

- Interactive diagram: https://gitdiagram.com/arksine/moonraker
- Repository: https://github.com/arksine/moonraker
- Video tour (about a minute): https://gitdiagram.com/arksine/moonraker/video

## Overview

Moonraker is a Python API server that lets client applications inspect and control Klipper-based 3D printers. Clients make HTTP or WebSocket requests; the server routes API/RPC calls to printer, file, job, and system components, which interact with Klipper, persistent state, or host services. The tree and excerpts support the server, transport, file-management, database, and update-management roles shown here. Other product capabilities are represented by their named component paths; their internal wiring was not sampled, so uncertain connections are omitted.

Main entry points: [`moonraker/components/application.py`](https://github.com/arksine/moonraker/blob/master/moonraker/components/application.py) (HTTP handlers), [`moonraker/components/file_manager/file_manager.py`](https://github.com/arksine/moonraker/blob/master/moonraker/components/file_manager/file_manager.py) (File manager), [`moonraker/server.py`](https://github.com/arksine/moonraker/blob/master/moonraker/server.py) (Server lifecycle), [`moonraker/components/klippy_connection.py`](https://github.com/arksine/moonraker/blob/master/moonraker/components/klippy_connection.py) (Klippy connection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and server"]
  node_server["Server lifecycle<br/>[server.py]"]
  node_application["HTTP handlers<br/>[application.py]"]
  node_rpc["JSON-RPC<br/>[common.py]"]
  node_websockets["WebSocket transport<br/>[websockets.py]"]
  node_authorization["Authorization<br/>[authorization.py]"]
end

subgraph group_printer["Printer workflow"]
  node_klippy_conn["Klippy connection"]
  node_klippy_api["Klippy APIs<br/>[klippy_apis.py]"]
  node_job_state["Job state<br/>[job_state.py]"]
  node_history["Print history<br/>[history.py]"]
  node_analysis["Print analysis<br/>[analysis.py]"]
end

subgraph group_files["Files and jobs"]
  node_file_manager["File manager<br/>[file_manager.py]"]
  node_metadata["G-code metadata<br/>[metadata.py]"]
  node_job_queue["Job queue<br/>[job_queue.py]"]
  node_database[("SQLite database<br/>[database.py]")]
end

subgraph group_system["Host management"]
  node_machine["Machine services<br/>[machine.py]"]
  node_power["Power control<br/>[power.py]"]
  node_update_manager["Update manager<br/>[update_manager.py]"]
  node_deploy["Git deployment<br/>[git_deploy.py]"]
end

subgraph group_integrations["Extensions and services"]
  node_announcements["Announcements<br/>[announcements.py]"]
  node_notifier["Notifications<br/>[notifier.py]"]
  node_mqtt["MQTT integration<br/>[mqtt.py]"]
end

node_clients(("Client applications"))
node_klipper(("Klipper firmware"))
node_host_os(("Host operating system"))

node_clients -->|"sends requests"| node_application
node_application -->|"checks access"| node_authorization
node_application -->|"dispatches RPC"| node_rpc
node_application -->|"uploads files"| node_file_manager
node_server -->|"loads transport"| node_websockets
node_server -->|"registers handlers"| node_application
node_klippy_api -->|"uses connection"| node_klippy_conn
node_klippy_conn -->|"communicates"| node_klipper
node_job_state -->|"records jobs"| node_history
node_file_manager -->|"parses metadata"| node_metadata
node_file_manager -->|"stores metadata"| node_database
node_job_queue -->|"persists queue"| node_database
node_update_manager -->|"runs deployment"| node_deploy
node_deploy -->|"updates software"| node_host_os
node_machine -->|"queries host"| node_host_os
node_power -->|"controls devices"| node_host_os

click node_server "https://github.com/arksine/moonraker/blob/master/moonraker/server.py"
click node_application "https://github.com/arksine/moonraker/blob/master/moonraker/components/application.py"
click node_rpc "https://github.com/arksine/moonraker/blob/master/moonraker/common.py"
click node_websockets "https://github.com/arksine/moonraker/blob/master/moonraker/components/websockets.py"
click node_authorization "https://github.com/arksine/moonraker/blob/master/moonraker/components/authorization.py"
click node_klippy_conn "https://github.com/arksine/moonraker/blob/master/moonraker/components/klippy_connection.py"
click node_klippy_api "https://github.com/arksine/moonraker/blob/master/moonraker/components/klippy_apis.py"
click node_job_state "https://github.com/arksine/moonraker/blob/master/moonraker/components/job_state.py"
click node_history "https://github.com/arksine/moonraker/blob/master/moonraker/components/history.py"
click node_analysis "https://github.com/arksine/moonraker/blob/master/moonraker/components/analysis.py"
click node_file_manager "https://github.com/arksine/moonraker/blob/master/moonraker/components/file_manager/file_manager.py"
click node_metadata "https://github.com/arksine/moonraker/blob/master/moonraker/components/file_manager/metadata.py"
click node_job_queue "https://github.com/arksine/moonraker/blob/master/moonraker/components/job_queue.py"
click node_database "https://github.com/arksine/moonraker/blob/master/moonraker/components/database.py"
click node_machine "https://github.com/arksine/moonraker/blob/master/moonraker/components/machine.py"
click node_power "https://github.com/arksine/moonraker/blob/master/moonraker/components/power.py"
click node_update_manager "https://github.com/arksine/moonraker/blob/master/moonraker/components/update_manager/update_manager.py"
click node_deploy "https://github.com/arksine/moonraker/blob/master/moonraker/components/update_manager/git_deploy.py"
click node_announcements "https://github.com/arksine/moonraker/blob/master/moonraker/components/announcements.py"
click node_notifier "https://github.com/arksine/moonraker/blob/master/moonraker/components/notifier.py"
click node_mqtt "https://github.com/arksine/moonraker/blob/master/moonraker/components/mqtt.py"

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_server,node_application,node_rpc,node_websockets,node_authorization,node_clients toneBlue
class node_klippy_conn,node_klippy_api,node_job_state,node_history,node_analysis toneAmber
class node_file_manager,node_metadata,node_job_queue,node_database toneMint
class node_machine,node_power,node_update_manager,node_deploy toneRose
class node_announcements,node_notifier,node_mqtt,node_klipper,node_host_os toneIndigo
```

## Components

### API and server

- [Server lifecycle](https://github.com/arksine/moonraker/blob/master/moonraker/server.py): `moonraker/server.py`
- [HTTP handlers](https://github.com/arksine/moonraker/blob/master/moonraker/components/application.py): `moonraker/components/application.py`
- [JSON-RPC](https://github.com/arksine/moonraker/blob/master/moonraker/common.py): `moonraker/common.py`
- [WebSocket transport](https://github.com/arksine/moonraker/blob/master/moonraker/components/websockets.py): `moonraker/components/websockets.py`
- [Authorization](https://github.com/arksine/moonraker/blob/master/moonraker/components/authorization.py): `moonraker/components/authorization.py`

### Printer workflow

- [Klippy connection](https://github.com/arksine/moonraker/blob/master/moonraker/components/klippy_connection.py): `moonraker/components/klippy_connection.py`
- [Klippy APIs](https://github.com/arksine/moonraker/blob/master/moonraker/components/klippy_apis.py): `moonraker/components/klippy_apis.py`
- [Job state](https://github.com/arksine/moonraker/blob/master/moonraker/components/job_state.py): `moonraker/components/job_state.py`
- [Print history](https://github.com/arksine/moonraker/blob/master/moonraker/components/history.py): `moonraker/components/history.py`
- [Print analysis](https://github.com/arksine/moonraker/blob/master/moonraker/components/analysis.py): `moonraker/components/analysis.py`

### Files and jobs

- [File manager](https://github.com/arksine/moonraker/blob/master/moonraker/components/file_manager/file_manager.py): `moonraker/components/file_manager/file_manager.py`
- [G-code metadata](https://github.com/arksine/moonraker/blob/master/moonraker/components/file_manager/metadata.py): `moonraker/components/file_manager/metadata.py`
- [Job queue](https://github.com/arksine/moonraker/blob/master/moonraker/components/job_queue.py): `moonraker/components/job_queue.py`
- [SQLite database](https://github.com/arksine/moonraker/blob/master/moonraker/components/database.py): `moonraker/components/database.py`

### Host management

- [Machine services](https://github.com/arksine/moonraker/blob/master/moonraker/components/machine.py): `moonraker/components/machine.py`
- [Power control](https://github.com/arksine/moonraker/blob/master/moonraker/components/power.py): `moonraker/components/power.py`
- [Update manager](https://github.com/arksine/moonraker/blob/master/moonraker/components/update_manager/update_manager.py): `moonraker/components/update_manager/update_manager.py`
- [Git deployment](https://github.com/arksine/moonraker/blob/master/moonraker/components/update_manager/git_deploy.py): `moonraker/components/update_manager/git_deploy.py`

### Extensions and services

- [Announcements](https://github.com/arksine/moonraker/blob/master/moonraker/components/announcements.py): `moonraker/components/announcements.py`
- [Notifications](https://github.com/arksine/moonraker/blob/master/moonraker/components/notifier.py): `moonraker/components/notifier.py`
- [MQTT integration](https://github.com/arksine/moonraker/blob/master/moonraker/components/mqtt.py): `moonraker/components/mqtt.py`

### Other components

- **Client applications**
- **Klipper firmware**
- **Host operating system**

## Connections

- Client applications → HTTP handlers: sends requests
- HTTP handlers → Authorization: checks access
- HTTP handlers → JSON-RPC: dispatches RPC
- HTTP handlers → File manager: uploads files
- Server lifecycle → WebSocket transport: loads transport
- Server lifecycle → HTTP handlers: registers handlers
- Klippy APIs → Klippy connection: uses connection
- Klippy connection → Klipper firmware: communicates
- Job state → Print history: records jobs
- File manager → G-code metadata: parses metadata
- File manager → SQLite database: stores metadata
- Job queue → SQLite database: persists queue
- Update manager → Git deployment: runs deployment
- Git deployment → Host operating system: updates software
- Machine services → Host operating system: queries host
- Power control → Host operating system: controls devices
