# wizarrrr/wizarr architecture

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

- Interactive diagram: https://gitdiagram.com/wizarrrr/wizarr
- Repository: https://github.com/wizarrrr/wizarr

## Overview

Wizarr turns an administrator-created invitation into a guided setup and automatic media-server onboarding flow. Invitees enter through the public invitation routes, complete pre-invite wizard steps, and proceed through invitation workflows that provision accounts through a media-service facade. The product also exposes administration and REST API capabilities, manages expiry and notification behavior, and monitors media activity. The README documents product capabilities; source relationships below are limited to the README and SOURCE INDEX references, so unsampled implementation links are omitted.

Main entry points: [`app/services/media/service.py`](https://github.com/wizarrrr/wizarr/blob/main/app/services/media/service.py) (Media service facade), [`app/services/invitation_flow/workflows.py`](https://github.com/wizarrrr/wizarr/blob/main/app/services/invitation_flow/workflows.py) (Invitation workflows), [`app/blueprints/public/routes.py`](https://github.com/wizarrrr/wizarr/blob/main/app/blueprints/public/routes.py) (Public invitations), [`app/blueprints/api/api_routes.py`](https://github.com/wizarrrr/wizarr/blob/main/app/blueprints/api/api_routes.py) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_invite["Invitation flow"]
  node_public["Public invitations<br/>[routes.py]"]
  node_wizard["Setup wizard<br/>[routes.py]"]
  node_invite_flow["Invitation workflows<br/>[workflows.py]"]
  node_invite_codes["Invite code state"]
  node_invite_ops["Invitation management<br/>[invites.py]"]
end

subgraph group_media["Media integrations"]
  node_media_facade["Media service facade<br/>[service.py]"]
  node_media_clients["Media client base<br/>[client_base.py]"]
  node_plex["Plex integration<br/>[plex.py]"]
  node_other_media["Other media servers"]
  node_request_apps["Request integrations<br/>[ombi_client.py]"]
end

subgraph group_manage["Administration"]
  node_admin["Admin console<br/>[routes.py]"]
  node_expiry["Membership expiry<br/>[expiry.py]"]
  node_notifications["Notifications<br/>[notifications.py]"]
end

subgraph group_activity["Activity monitoring"]
  node_monitor["Activity monitor<br/>[monitor.py]"]
  node_session_manager["Session lifecycle<br/>[session_manager.py]"]
  node_activity_ingestion["Activity ingestion<br/>[ingestion.py]"]
  node_activity_api["Activity API<br/>[blueprint.py]"]
end

subgraph group_platform["API and state"]
  node_rest_api["REST API<br/>[api_routes.py]"]
  node_models[("Application records<br/>[models.py]")]
end

node_invitee(("Invitee"))
node_media_servers_ext["Media server"]
node_request_ext["Request system"]

node_invitee -->|"opens invite"| node_public
node_public -->|"guides setup"| node_wizard
node_public -->|"routes through"| node_invite_flow
node_public -->|"uses service"| node_media_facade
node_invite_flow -->|"provisions via"| node_media_facade
node_invite_flow -->|"uses invitations"| node_invite_ops
node_wizard -->|"tracks invite code"| node_invite_codes
node_admin -->|"creates invites"| node_invite_ops
node_admin -->|"uses service"| node_media_facade
node_media_facade -->|"dispatches clients"| node_media_clients
node_media_clients -->|"specializes"| node_plex
node_media_facade -->|"manages accounts"| node_media_servers_ext
node_media_facade -->|"supports integrations"| node_other_media
node_invite_flow -->|"integrates requests"| node_request_apps
node_request_apps -->|"calls request system"| node_request_ext
node_invite_flow -->|"reads and writes"| node_models
node_expiry -->|"uses service"| node_media_facade
node_monitor -->|"manages sessions"| node_session_manager
node_session_manager -->|"enriches sessions"| node_media_facade
node_activity_ingestion -->|"stores activity"| node_models
node_activity_api -.-> node_activity_ingestion
node_rest_api -->|"manages invitations"| node_invite_ops
node_rest_api -->|"uses service"| node_media_facade
node_rest_api -->|"queries records"| node_models

click node_public "https://github.com/wizarrrr/wizarr/blob/main/app/blueprints/public/routes.py"
click node_wizard "https://github.com/wizarrrr/wizarr/blob/main/app/blueprints/wizard/routes.py"
click node_invite_flow "https://github.com/wizarrrr/wizarr/blob/main/app/services/invitation_flow/workflows.py"
click node_invite_codes "https://github.com/wizarrrr/wizarr/blob/main/app/services/invite_code_manager.py"
click node_invite_ops "https://github.com/wizarrrr/wizarr/blob/main/app/services/invites.py"
click node_media_facade "https://github.com/wizarrrr/wizarr/blob/main/app/services/media/service.py"
click node_media_clients "https://github.com/wizarrrr/wizarr/blob/main/app/services/media/client_base.py"
click node_plex "https://github.com/wizarrrr/wizarr/blob/main/app/services/media/plex.py"
click node_other_media "https://github.com/wizarrrr/wizarr/tree/main/app/services/media"
click node_request_apps "https://github.com/wizarrrr/wizarr/blob/main/app/services/ombi_client.py"
click node_admin "https://github.com/wizarrrr/wizarr/blob/main/app/blueprints/admin/routes.py"
click node_expiry "https://github.com/wizarrrr/wizarr/blob/main/app/services/expiry.py"
click node_notifications "https://github.com/wizarrrr/wizarr/blob/main/app/services/notifications.py"
click node_monitor "https://github.com/wizarrrr/wizarr/blob/main/app/activity/monitoring/monitor.py"
click node_session_manager "https://github.com/wizarrrr/wizarr/blob/main/app/activity/monitoring/session_manager.py"
click node_activity_ingestion "https://github.com/wizarrrr/wizarr/blob/main/app/services/activity/ingestion.py"
click node_activity_api "https://github.com/wizarrrr/wizarr/blob/main/app/activity/api/blueprint.py"
click node_rest_api "https://github.com/wizarrrr/wizarr/blob/main/app/blueprints/api/api_routes.py"
click node_models "https://github.com/wizarrrr/wizarr/blob/main/app/models.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_public,node_wizard,node_invite_flow,node_invite_codes,node_invite_ops toneBlue
class node_media_facade,node_media_clients,node_plex,node_other_media,node_request_apps toneAmber
class node_admin,node_expiry,node_notifications,node_media_servers_ext,node_request_ext toneMint
class node_monitor,node_session_manager,node_activity_ingestion,node_activity_api toneRose
class node_rest_api,node_models,node_invitee toneIndigo
```

## Components

### Invitation flow

- [Public invitations](https://github.com/wizarrrr/wizarr/blob/main/app/blueprints/public/routes.py): `app/blueprints/public/routes.py`
- [Setup wizard](https://github.com/wizarrrr/wizarr/blob/main/app/blueprints/wizard/routes.py): `app/blueprints/wizard/routes.py`
- [Invitation workflows](https://github.com/wizarrrr/wizarr/blob/main/app/services/invitation_flow/workflows.py): `app/services/invitation_flow/workflows.py`
- [Invite code state](https://github.com/wizarrrr/wizarr/blob/main/app/services/invite_code_manager.py): `app/services/invite_code_manager.py`
- [Invitation management](https://github.com/wizarrrr/wizarr/blob/main/app/services/invites.py): `app/services/invites.py`

### Media integrations

- [Media service facade](https://github.com/wizarrrr/wizarr/blob/main/app/services/media/service.py): `app/services/media/service.py`
- [Media client base](https://github.com/wizarrrr/wizarr/blob/main/app/services/media/client_base.py): `app/services/media/client_base.py`
- [Plex integration](https://github.com/wizarrrr/wizarr/blob/main/app/services/media/plex.py): `app/services/media/plex.py`
- [Other media servers](https://github.com/wizarrrr/wizarr/tree/main/app/services/media): `app/services/media`
- [Request integrations](https://github.com/wizarrrr/wizarr/blob/main/app/services/ombi_client.py): `app/services/ombi_client.py`

### Administration

- [Admin console](https://github.com/wizarrrr/wizarr/blob/main/app/blueprints/admin/routes.py): `app/blueprints/admin/routes.py`
- [Membership expiry](https://github.com/wizarrrr/wizarr/blob/main/app/services/expiry.py): `app/services/expiry.py`
- [Notifications](https://github.com/wizarrrr/wizarr/blob/main/app/services/notifications.py): `app/services/notifications.py`

### Activity monitoring

- [Activity monitor](https://github.com/wizarrrr/wizarr/blob/main/app/activity/monitoring/monitor.py): `app/activity/monitoring/monitor.py`
- [Session lifecycle](https://github.com/wizarrrr/wizarr/blob/main/app/activity/monitoring/session_manager.py): `app/activity/monitoring/session_manager.py`
- [Activity ingestion](https://github.com/wizarrrr/wizarr/blob/main/app/services/activity/ingestion.py): `app/services/activity/ingestion.py`
- [Activity API](https://github.com/wizarrrr/wizarr/blob/main/app/activity/api/blueprint.py): `app/activity/api/blueprint.py`

### API and state

- [REST API](https://github.com/wizarrrr/wizarr/blob/main/app/blueprints/api/api_routes.py): `app/blueprints/api/api_routes.py`
- [Application records](https://github.com/wizarrrr/wizarr/blob/main/app/models.py): `app/models.py`

### Other components

- **Invitee**
- **Media server**
- **Request system**

## Connections

- Invitee → Public invitations: opens invite
- Public invitations → Setup wizard: guides setup
- Public invitations → Invitation workflows: routes through (evidence: `app/blueprints/public/routes.py`)
- Public invitations → Media service facade: uses service (evidence: `app/blueprints/public/routes.py`)
- Invitation workflows → Media service facade: provisions via (evidence: `app/services/invitation_flow/workflows.py`)
- Invitation workflows → Invitation management: uses invitations (evidence: `app/services/invitation_flow/workflows.py`)
- Setup wizard → Invite code state: tracks invite code (evidence: `app/blueprints/wizard/routes.py`)
- Admin console → Invitation management: creates invites (evidence: `app/blueprints/admin/routes.py`)
- Admin console → Media service facade: uses service (evidence: `app/blueprints/admin/routes.py`)
- Media service facade → Media client base: dispatches clients (evidence: `app/services/media/service.py`)
- Media client base → Plex integration: specializes (evidence: `app/services/media/plex.py`)
- Media service facade → Media server: manages accounts
- Media service facade → Other media servers: supports integrations (evidence: `app/services/media/service.py`)
- Invitation workflows → Request integrations: integrates requests (evidence: `app/services/invitation_flow/workflows.py`)
- Request integrations → Request system: calls request system (evidence: `app/services/ombi_client.py`)
- Invitation workflows → Application records: reads and writes (evidence: `app/services/invitation_flow/workflows.py`)
- Membership expiry → Media service facade: uses service (evidence: `app/services/expiry.py`)
- Activity monitor → Session lifecycle: manages sessions (evidence: `app/activity/monitoring/session_manager.py`)
- Session lifecycle → Media service facade: enriches sessions (evidence: `app/activity/monitoring/session_manager.py`)
- Activity ingestion → Application records: stores activity (evidence: `app/services/activity/ingestion.py`)
- Activity API → Activity ingestion
- REST API → Invitation management: manages invitations (evidence: `app/blueprints/api/api_routes.py`)
- REST API → Media service facade: uses service (evidence: `app/blueprints/api/api_routes.py`)
- REST API → Application records: queries records (evidence: `app/blueprints/api/api_routes.py`)