# lewlew-glitch/qm_companion architecture

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

- Interactive diagram: https://gitdiagram.com/lewlew-glitch/qm_companion
- Repository: https://github.com/lewlew-glitch/qm_companion
- Video tour (about a minute): https://gitdiagram.com/lewlew-glitch/qm_companion/video

## Overview

Quartermaster Companion is a self-hosted control panel and setup-transfer service for the Quartermaster phone app. The main workflow is owner sign-in, service discovery and review, then creation of a short-lived encrypted setup transfer; the panel also presents Docker and service status and can optionally manage Docker. Separate capabilities cover webhook alerts and certificate-pinned mobile access. The excerpts show selected routing and authentication calls; other capability links rely on the README and are omitted where implementation wiring is not evidenced.

Main entry points: [`src/server.js`](https://github.com/lewlew-glitch/qm_companion/blob/main/src/server.js) (HTTP routes), [`src/alerts/intake.js`](https://github.com/lewlew-glitch/qm_companion/blob/main/src/alerts/intake.js) (Alert intake), [`src/index.js`](https://github.com/lewlew-glitch/qm_companion/blob/main/src/index.js) (Application entry), [`src/auth.js`](https://github.com/lewlew-glitch/qm_companion/blob/main/src/auth.js) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web panel"]
  node_entry["Application entry<br/>[index.js]"]
  node_server["HTTP routes<br/>[server.js]"]
  node_auth["Authentication<br/>[auth.js]"]
  node_authplane["Login transport<br/>[auth-plane.js]"]
  node_state[("Encrypted state<br/>[store.js]")]
  node_ui["Panel views<br/>[views.js]"]
end

subgraph group_pairing["Service setup"]
  node_discovery["Service discovery<br/>[detect.js]"]
  node_pairform["Pairing review<br/>[pair-form.js]"]
  node_pairbuild["Transfer creation<br/>[build.js]"]
end

subgraph group_docker["Docker operations"]
  node_docker["Docker access<br/>[docker.js]"]
  node_compose["Compose deployment<br/>[compose.js]"]
  node_cron["Scheduled jobs<br/>[cron.js]"]
end

subgraph group_mobile["Mobile access"]
  node_mobileowner["Device enrollment<br/>[owner-routes.js]"]
  node_mobileroutes["Mobile API<br/>[routes.js]"]
  node_mobilestate[("Mobile state<br/>[store.js]")]
end

subgraph group_alerts["Alerts"]
  node_alertroutes["Alert settings<br/>[routes.js]"]
  node_alertintake["Alert intake<br/>[intake.js]"]
  node_alertdelivery["Alert delivery<br/>[delivery.js]"]
  node_alertstate[("Alert state<br/>[store.js]")]
end

node_owner(("Owner"))
node_browser(("Browser"))
node_phone(("Quartermaster app"))
node_services(("Service instances"))
node_dockerengine(("Docker engine"))
node_webhook(("Service webhooks"))

node_owner -->|"uses"| node_browser
node_browser -->|"requests"| node_entry
node_entry -->|"dispatches"| node_server
node_server -->|"handles login"| node_authplane
node_authplane -->|"authenticates"| node_auth
node_auth -->|"reads/writes owner"| node_state
node_server -->|"renders pages"| node_ui
node_server -->|"discovers services"| node_discovery
node_server -->|"prepares review"| node_pairform
node_server -->|"creates transfer"| node_pairbuild
node_pairform -->|"uses service data"| node_discovery
node_pairbuild -->|"packages setup details"| node_services
node_server -->|"loads status / operates"| node_docker
node_docker -->|"inspects / controls"| node_dockerengine
node_server -->|"deploys stacks"| node_compose
node_server -->|"manages schedules"| node_cron
node_phone -->|"connects directly"| node_services
node_phone -.->|"optional HTTPS API"| node_mobileroutes
node_server -.->|"routes device actions"| node_mobileowner
node_mobileowner -.->|"reads/writes enrollment"| node_mobilestate
node_mobileroutes -.->|"reads mobile state"| node_mobilestate
node_webhook -->|"submits events"| node_alertintake
node_server -->|"routes alert settings"| node_alertroutes
node_alertroutes -->|"reads/writes settings"| node_alertstate
node_alertintake -->|"records events"| node_alertstate
node_alertintake -->|"dispatches alerts"| node_alertdelivery
node_alertdelivery -->|"sends notifications"| node_phone

click node_entry "https://github.com/lewlew-glitch/qm_companion/blob/main/src/index.js"
click node_server "https://github.com/lewlew-glitch/qm_companion/blob/main/src/server.js"
click node_auth "https://github.com/lewlew-glitch/qm_companion/blob/main/src/auth.js"
click node_authplane "https://github.com/lewlew-glitch/qm_companion/blob/main/src/auth-plane.js"
click node_state "https://github.com/lewlew-glitch/qm_companion/blob/main/src/store.js"
click node_ui "https://github.com/lewlew-glitch/qm_companion/blob/main/src/ui/views.js"
click node_discovery "https://github.com/lewlew-glitch/qm_companion/blob/main/src/detect.js"
click node_pairform "https://github.com/lewlew-glitch/qm_companion/blob/main/src/pair-form.js"
click node_pairbuild "https://github.com/lewlew-glitch/qm_companion/blob/main/src/build.js"
click node_docker "https://github.com/lewlew-glitch/qm_companion/blob/main/src/docker.js"
click node_compose "https://github.com/lewlew-glitch/qm_companion/blob/main/src/compose.js"
click node_cron "https://github.com/lewlew-glitch/qm_companion/blob/main/src/cron.js"
click node_mobileowner "https://github.com/lewlew-glitch/qm_companion/blob/main/src/mobile/owner-routes.js"
click node_mobileroutes "https://github.com/lewlew-glitch/qm_companion/blob/main/src/mobile/routes.js"
click node_mobilestate "https://github.com/lewlew-glitch/qm_companion/blob/main/src/mobile/store.js"
click node_alertroutes "https://github.com/lewlew-glitch/qm_companion/blob/main/src/alerts/routes.js"
click node_alertintake "https://github.com/lewlew-glitch/qm_companion/blob/main/src/alerts/intake.js"
click node_alertdelivery "https://github.com/lewlew-glitch/qm_companion/blob/main/src/alerts/delivery.js"
click node_alertstate "https://github.com/lewlew-glitch/qm_companion/blob/main/src/alerts/store.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_entry,node_server,node_auth,node_authplane,node_state,node_ui,node_browser toneBlue
class node_discovery,node_pairform,node_pairbuild toneAmber
class node_docker,node_compose,node_cron,node_webhook toneMint
class node_mobileowner,node_mobileroutes,node_mobilestate toneRose
class node_alertroutes,node_alertintake,node_alertdelivery,node_alertstate,node_owner,node_phone,node_services,node_dockerengine toneIndigo
```

## Components

### Web panel

- [Application entry](https://github.com/lewlew-glitch/qm_companion/blob/main/src/index.js): `src/index.js`
- [HTTP routes](https://github.com/lewlew-glitch/qm_companion/blob/main/src/server.js): `src/server.js`
- [Authentication](https://github.com/lewlew-glitch/qm_companion/blob/main/src/auth.js): `src/auth.js`
- [Login transport](https://github.com/lewlew-glitch/qm_companion/blob/main/src/auth-plane.js): `src/auth-plane.js`
- [Encrypted state](https://github.com/lewlew-glitch/qm_companion/blob/main/src/store.js): `src/store.js`
- [Panel views](https://github.com/lewlew-glitch/qm_companion/blob/main/src/ui/views.js): `src/ui/views.js`

### Service setup

- [Service discovery](https://github.com/lewlew-glitch/qm_companion/blob/main/src/detect.js): `src/detect.js`
- [Pairing review](https://github.com/lewlew-glitch/qm_companion/blob/main/src/pair-form.js): `src/pair-form.js`
- [Transfer creation](https://github.com/lewlew-glitch/qm_companion/blob/main/src/build.js): `src/build.js`

### Docker operations

- [Docker access](https://github.com/lewlew-glitch/qm_companion/blob/main/src/docker.js): `src/docker.js`
- [Compose deployment](https://github.com/lewlew-glitch/qm_companion/blob/main/src/compose.js): `src/compose.js`
- [Scheduled jobs](https://github.com/lewlew-glitch/qm_companion/blob/main/src/cron.js): `src/cron.js`

### Mobile access

- [Device enrollment](https://github.com/lewlew-glitch/qm_companion/blob/main/src/mobile/owner-routes.js): `src/mobile/owner-routes.js`
- [Mobile API](https://github.com/lewlew-glitch/qm_companion/blob/main/src/mobile/routes.js): `src/mobile/routes.js`
- [Mobile state](https://github.com/lewlew-glitch/qm_companion/blob/main/src/mobile/store.js): `src/mobile/store.js`

### Alerts

- [Alert settings](https://github.com/lewlew-glitch/qm_companion/blob/main/src/alerts/routes.js): `src/alerts/routes.js`
- [Alert intake](https://github.com/lewlew-glitch/qm_companion/blob/main/src/alerts/intake.js): `src/alerts/intake.js`
- [Alert delivery](https://github.com/lewlew-glitch/qm_companion/blob/main/src/alerts/delivery.js): `src/alerts/delivery.js`
- [Alert state](https://github.com/lewlew-glitch/qm_companion/blob/main/src/alerts/store.js): `src/alerts/store.js`

### Other components

- **Owner**
- **Browser**
- **Quartermaster app**
- **Service instances**
- **Docker engine**
- **Service webhooks**

## Connections

- Owner → Browser: uses
- Browser → Application entry: requests
- Application entry → HTTP routes: dispatches
- HTTP routes → Login transport: handles login
- Login transport → Authentication: authenticates
- Authentication → Encrypted state: reads/writes owner
- HTTP routes → Panel views: renders pages
- HTTP routes → Service discovery: discovers services
- HTTP routes → Pairing review: prepares review
- HTTP routes → Transfer creation: creates transfer
- Pairing review → Service discovery: uses service data
- Transfer creation → Service instances: packages setup details
- HTTP routes → Docker access: loads status / operates
- Docker access → Docker engine: inspects / controls
- HTTP routes → Compose deployment: deploys stacks
- HTTP routes → Scheduled jobs: manages schedules
- Quartermaster app → Service instances: connects directly
- Quartermaster app → Mobile API: optional HTTPS API
- HTTP routes → Device enrollment: routes device actions
- Device enrollment → Mobile state: reads/writes enrollment
- Mobile API → Mobile state: reads mobile state
- Service webhooks → Alert intake: submits events
- HTTP routes → Alert settings: routes alert settings
- Alert settings → Alert state: reads/writes settings
- Alert intake → Alert state: records events
- Alert intake → Alert delivery: dispatches alerts
- Alert delivery → Quartermaster app: sends notifications