# yatsenkoyura/netsanctum architecture

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

- Interactive diagram: https://gitdiagram.com/yatsenkoyura/netsanctum
- Repository: https://github.com/yatsenkoyura/netsanctum

## Overview

NetSanctum is a self-hosted modular web platform: the owner enters through the web application, which discovers and mounts enabled module routers; each module then serves its own application behavior using shared infrastructure. The README documents module discovery and shared services, while sampled source confirms several specific module-to-service relationships. Some listed product modules are represented at their directory paths because their implementation files were not sampled; their internal flows are therefore not asserted.

Main entry points: [`app/core/modules.py`](https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/modules.py) (Module registry), [`app/main.py`](https://github.com/yatsenkoyura/netsanctum/blob/main/app/main.py) (Web application), [`app/modules/music`](https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/music) (Music library), [`app/modules/vault`](https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/vault) (Encrypted Vault)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application runtime"]
  node_webapp["Web application<br/>[main.py]"]
end

subgraph group_framework["Module framework"]
  node_registry["Module registry<br/>[modules.py]"]
  node_contracts["Module contracts<br/>[module_types.py]"]
end

subgraph group_shared["Shared services"]
  node_auth["Authentication<br/>[security.py]"]
  node_database[("Database sessions<br/>[database.py]")]
  node_settings["Settings service<br/>[service.py]"]
  node_storage["Object storage<br/>[storage.py]"]
  node_templates["Template rendering<br/>[templates.py]"]
  node_tasks["Background tasks<br/>[task_dispatch.py]"]
  node_packages["Offline packages<br/>[packages_router.py]"]
  node_browser["Browser runtime client<br/>[browser_client.py]"]
end

subgraph group_apps["Product modules"]
  node_alllib["AllLib library"]
  node_music["Music library"]
  node_vault["Encrypted Vault"]
  node_games["Tabletop games"]
  node_video["Video Archiver"]
  node_youtube["YouTube"]
  node_planner["Planner"]
  node_search["Search"]
  node_sharing["Scoped sharing"]
end

subgraph group_assistant["Assistant and automation"]
  node_miku["Miku assistant<br/>[router.py]"]
  node_agent["Agent engine<br/>[engine.py]"]
  node_agentclient["Agent client<br/>[agent_client.py]"]
end

node_owner(("Owner"))

node_owner -->|"uses"| node_webapp
node_webapp -->|"discovers modules"| node_registry
node_registry -->|"validates manifests"| node_contracts
node_registry -->|"mounts enabled routers"| node_alllib
node_registry -->|"mounts enabled routers"| node_music
node_registry -->|"mounts enabled routers"| node_vault
node_registry -->|"mounts enabled routers"| node_games
node_registry -->|"mounts enabled routers"| node_video
node_registry -->|"mounts enabled routers"| node_youtube
node_registry -->|"mounts enabled routers"| node_planner
node_registry -->|"mounts enabled routers"| node_search
node_registry -->|"mounts enabled routers"| node_sharing
node_registry -->|"mounts enabled routers"| node_miku
node_webapp -->|"uses authentication"| node_auth
node_webapp -->|"opens sessions"| node_database
node_webapp -->|"seeds settings"| node_settings
node_registry -->|"registers template dirs"| node_templates
node_miku -->|"requests agent turns"| node_agentclient
node_agentclient -->|"calls runtime engine"| node_agent
node_music -->|"uses browser client"| node_browser
node_youtube -->|"uses browser client"| node_browser
node_alllib -->|"uses storage"| node_storage
node_vault -->|"uses storage"| node_storage
node_games -->|"uses sessions"| node_database
node_video -->|"uses storage"| node_storage
node_miku -->|"uses sessions"| node_database
node_music -->|"dispatches tasks"| node_tasks
node_vault -->|"dispatches tasks"| node_tasks
node_video -->|"uses browser client"| node_browser
node_webapp -->|"mounts package routes"| node_packages

click node_webapp "https://github.com/yatsenkoyura/netsanctum/blob/main/app/main.py"
click node_registry "https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/modules.py"
click node_contracts "https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/module_types.py"
click node_auth "https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/security.py"
click node_database "https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/database.py"
click node_settings "https://github.com/yatsenkoyura/netsanctum/blob/main/app/modules/system/settings/service.py"
click node_storage "https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/storage.py"
click node_templates "https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/templates.py"
click node_tasks "https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/task_dispatch.py"
click node_packages "https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/packages_router.py"
click node_alllib "https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/alllib"
click node_music "https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/music"
click node_vault "https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/vault"
click node_games "https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/tabletop_games"
click node_video "https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/video_archiver"
click node_youtube "https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/youtube"
click node_planner "https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/planner"
click node_search "https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/search"
click node_sharing "https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/system/sharing"
click node_miku "https://github.com/yatsenkoyura/netsanctum/blob/main/app/modules/miku/router.py"
click node_agent "https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/agent/engine.py"
click node_agentclient "https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/agent_client.py"
click node_browser "https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/browser_client.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_webapp toneBlue
class node_registry,node_contracts toneAmber
class node_auth,node_database,node_settings,node_storage,node_templates,node_tasks,node_packages,node_browser toneMint
class node_alllib,node_music,node_vault,node_games,node_video,node_youtube,node_planner,node_search,node_sharing toneRose
class node_miku,node_agent,node_agentclient,node_owner toneIndigo
```

## Components

### Application runtime

- [Web application](https://github.com/yatsenkoyura/netsanctum/blob/main/app/main.py): `app/main.py`

### Module framework

- [Module registry](https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/modules.py): `app/core/modules.py`
- [Module contracts](https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/module_types.py): `app/core/module_types.py`

### Shared services

- [Authentication](https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/security.py): `app/core/security.py`
- [Database sessions](https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/database.py): `app/core/database.py`
- [Settings service](https://github.com/yatsenkoyura/netsanctum/blob/main/app/modules/system/settings/service.py): `app/modules/system/settings/service.py`
- [Object storage](https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/storage.py): `app/core/storage.py`
- [Template rendering](https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/templates.py): `app/core/templates.py`
- [Background tasks](https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/task_dispatch.py): `app/core/task_dispatch.py`
- [Offline packages](https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/packages_router.py): `app/core/packages_router.py`
- [Browser runtime client](https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/browser_client.py): `app/core/browser_client.py`

### Product modules

- [AllLib library](https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/alllib): `app/modules/alllib`
- [Music library](https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/music): `app/modules/music`
- [Encrypted Vault](https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/vault): `app/modules/vault`
- [Tabletop games](https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/tabletop_games): `app/modules/tabletop_games`
- [Video Archiver](https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/video_archiver): `app/modules/video_archiver`
- [YouTube](https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/youtube): `app/modules/youtube`
- [Planner](https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/planner): `app/modules/planner`
- [Search](https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/search): `app/modules/search`
- [Scoped sharing](https://github.com/yatsenkoyura/netsanctum/tree/main/app/modules/system/sharing): `app/modules/system/sharing`

### Assistant and automation

- [Miku assistant](https://github.com/yatsenkoyura/netsanctum/blob/main/app/modules/miku/router.py): `app/modules/miku/router.py`
- [Agent engine](https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/agent/engine.py): `app/core/agent/engine.py`
- [Agent client](https://github.com/yatsenkoyura/netsanctum/blob/main/app/core/agent_client.py): `app/core/agent_client.py`

### Other components

- **Owner**

## Connections

- Owner → Web application: uses (evidence: `README.md`)
- Web application → Module registry: discovers modules (evidence: `README.md`)
- Module registry → Module contracts: validates manifests (evidence: `app/core/modules.py`)
- Module registry → AllLib library: mounts enabled routers (evidence: `README.md`)
- Module registry → Music library: mounts enabled routers (evidence: `README.md`)
- Module registry → Encrypted Vault: mounts enabled routers (evidence: `README.md`)
- Module registry → Tabletop games: mounts enabled routers (evidence: `README.md`)
- Module registry → Video Archiver: mounts enabled routers (evidence: `README.md`)
- Module registry → YouTube: mounts enabled routers (evidence: `README.md`)
- Module registry → Planner: mounts enabled routers (evidence: `README.md`)
- Module registry → Search: mounts enabled routers (evidence: `README.md`)
- Module registry → Scoped sharing: mounts enabled routers (evidence: `README.md`)
- Module registry → Miku assistant: mounts enabled routers (evidence: `README.md`)
- Web application → Authentication: uses authentication (evidence: `app/main.py`)
- Web application → Database sessions: opens sessions (evidence: `app/main.py`)
- Web application → Settings service: seeds settings (evidence: `app/main.py`)
- Module registry → Template rendering: registers template dirs (evidence: `app/core/templates.py`)
- Miku assistant → Agent client: requests agent turns (evidence: `app/modules/miku/router.py`)
- Agent client → Agent engine: calls runtime engine (evidence: `app/core/agent_client.py`)
- Music library → Browser runtime client: uses browser client (evidence: `app/modules/music/router.py`)
- YouTube → Browser runtime client: uses browser client (evidence: `app/modules/youtube/services.py`)
- AllLib library → Object storage: uses storage (evidence: `app/modules/alllib/router.py`)
- Encrypted Vault → Object storage: uses storage (evidence: `app/modules/vault/router.py`)
- Tabletop games → Database sessions: uses sessions (evidence: `app/modules/tabletop_games/router.py`)
- Video Archiver → Object storage: uses storage (evidence: `app/modules/video_archiver/router.py`)
- Miku assistant → Database sessions: uses sessions (evidence: `app/modules/miku/router.py`)
- Music library → Background tasks: dispatches tasks (evidence: `app/modules/music/router.py`)
- Encrypted Vault → Background tasks: dispatches tasks (evidence: `app/modules/vault/router.py`)
- Video Archiver → Browser runtime client: uses browser client (evidence: `app/modules/video_archiver/router.py`)
- Web application → Offline packages: mounts package routes (evidence: `app/core/packages_router.py`)
