# emilithe-tech/veilrunner-system architecture

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

- Interactive diagram: https://gitdiagram.com/emilithe-tech/veilrunner-system
- Repository: https://github.com/emilithe-tech/veilrunner-system

## Overview

Veilrunner is a Foundry VTT game system for character management, rules-driven play, combat, and campaign recordkeeping. Its principal player workflow runs from character creation and progression through a hero sheet into action selection and combat execution. GMs also author canonical progression content and manage shared relations, maps, and events through the Datapad. The graph emphasizes documented entry-point wiring and sampled calls; several feature internals are represented by their exact enclosing directories because their source was not sampled.

Main entry points: [`veilrunner.mjs`](https://github.com/emilithe-tech/veilrunner-system/blob/main/veilrunner.mjs) (Veilrunner system), [`modules/relations/service.mjs`](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/relations/service.mjs) (Relations service), [`modules/data/progression/catalog-provider.mjs`](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/data/progression/catalog-provider.mjs) (Progression catalog), [`modules/apps/action-hud/controller.mjs`](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/apps/action-hud/controller.mjs) (Action HUD)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["System Runtime"]
  node_system["Veilrunner system<br/>[veilrunner.mjs]"]
  node_settings["System settings<br/>[settings.mjs]"]
end

subgraph group_play["Play And Combat"]
  node_action_hud["Action HUD<br/>[controller.mjs]"]
  node_hud_execution["Action execution<br/>[execution.mjs]"]
  node_firearms["Firearms<br/>[firearms.mjs]"]
  node_combat_tools["Combat tools"]
end

subgraph group_character["Characters And Progression"]
  node_hero["Hero sheet<br/>[hero-sheet.mjs]"]
  node_chargen["Character creation"]
  node_chargen_views["Creation workflow"]
  node_progression_catalog["Progression catalog"]
  node_progression_authoring["Progression authoring"]
  node_progression_content["Content creation"]
end

subgraph group_rules["Rules And Definitions"]
  node_action_resolution["Action resolution"]
  node_item_rules["Item rules<br/>[item-rules.mjs]"]
  node_definition_identity["Definition identity<br/>[canonical-id.mjs]"]
  node_definition_validation["Definition validation<br/>[validation.mjs]"]
  node_compendium["Compendium routing"]
end

subgraph group_campaign["Campaign Records"]
  node_datapad["Datapad<br/>[datapad.mjs]"]
  node_relations_view["Relations workspace<br/>[view.mjs]"]
  node_relations_service["Relations service<br/>[service.mjs]"]
  node_relations_model["Relations model<br/>[model.mjs]"]
  node_relations_vault[("Relations storage<br/>[vault.mjs]")]
  node_party_helpers["Party data<br/>[party.mjs]"]
end

node_foundry(("Foundry user"))

node_foundry -->|"starts system"| node_system
node_system -->|"registers sheets"| node_hero
node_system -->|"registers app"| node_chargen
node_system -->|"registers HUD"| node_action_hud
node_system -->|"registers app"| node_datapad
node_system -->|"registers apps"| node_combat_tools
node_system -->|"registers settings"| node_settings
node_system -->|"initializes catalog"| node_progression_catalog
node_system -->|"initializes authoring"| node_progression_authoring
node_action_hud -->|"executes actions"| node_hud_execution
node_action_hud -->|"reads preferences"| node_settings
node_hud_execution -->|"uses firearm actions"| node_firearms
node_firearms -->|"checks item rules"| node_item_rules
node_hero -->|"renders relations"| node_relations_view
node_hero -->|"resolves owned actions"| node_action_resolution
node_chargen -->|"opens creation flow"| node_chargen_views
node_chargen -->|"loads catalog"| node_progression_catalog
node_chargen -->|"uses authoring"| node_progression_authoring
node_progression_authoring -->|"creates content"| node_progression_content
node_progression_authoring -->|"uses catalog"| node_progression_catalog
node_progression_content -->|"builds canonical IDs"| node_definition_identity
node_progression_content -->|"validates definitions"| node_definition_validation
node_progression_catalog -->|"routes definitions"| node_compendium
node_progression_catalog -->|"builds canonical IDs"| node_definition_identity
node_datapad -->|"renders workspace"| node_relations_view
node_datapad -->|"reads relations"| node_relations_service
node_relations_view -->|"reads state"| node_relations_service
node_relations_service -->|"projects and transacts"| node_relations_model
node_relations_service -->|"seals stored data"| node_relations_vault
node_relations_service -.->|"uses party data"| node_party_helpers
node_action_hud -->|"uses party context"| node_party_helpers

click node_system "https://github.com/emilithe-tech/veilrunner-system/blob/main/veilrunner.mjs"
click node_settings "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/settings.mjs"
click node_hero "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/sheets/hero-sheet.mjs"
click node_chargen "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/apps/character-creation.mjs"
click node_chargen_views "https://github.com/emilithe-tech/veilrunner-system/tree/main/modules/apps/chargen"
click node_progression_catalog "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/data/progression/catalog-provider.mjs"
click node_progression_authoring "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/data/progression/authoring-services.mjs"
click node_progression_content "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/data/progression/content-creation-service.mjs"
click node_action_hud "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/apps/action-hud/controller.mjs"
click node_hud_execution "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/apps/action-hud/execution.mjs"
click node_firearms "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/items/firearms.mjs"
click node_combat_tools "https://github.com/emilithe-tech/veilrunner-system/tree/main/modules/apps"
click node_action_resolution "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/actions/resolved-action.mjs"
click node_item_rules "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/rules/item-rules.mjs"
click node_definition_identity "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/data/definitions/canonical-id.mjs"
click node_definition_validation "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/data/definitions/validation.mjs"
click node_compendium "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/data/definitions/compendium-router.mjs"
click node_datapad "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/apps/datapad.mjs"
click node_relations_view "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/relations/view.mjs"
click node_relations_service "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/relations/service.mjs"
click node_relations_model "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/relations/model.mjs"
click node_relations_vault "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/relations/vault.mjs"
click node_party_helpers "https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/helpers/party.mjs"

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_system,node_settings,node_foundry toneBlue
class node_action_hud,node_hud_execution,node_firearms,node_combat_tools toneAmber
class node_hero,node_chargen,node_chargen_views,node_progression_catalog,node_progression_authoring,node_progression_content toneMint
class node_action_resolution,node_item_rules,node_definition_identity,node_definition_validation,node_compendium toneRose
class node_datapad,node_relations_view,node_relations_service,node_relations_model,node_relations_vault,node_party_helpers toneIndigo
```

## Components

### System Runtime

- [Veilrunner system](https://github.com/emilithe-tech/veilrunner-system/blob/main/veilrunner.mjs): `veilrunner.mjs`
- [System settings](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/settings.mjs): `modules/settings.mjs`

### Play And Combat

- [Action HUD](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/apps/action-hud/controller.mjs): `modules/apps/action-hud/controller.mjs`
- [Action execution](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/apps/action-hud/execution.mjs): `modules/apps/action-hud/execution.mjs`
- [Firearms](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/items/firearms.mjs): `modules/items/firearms.mjs`
- [Combat tools](https://github.com/emilithe-tech/veilrunner-system/tree/main/modules/apps): `modules/apps`

### Characters And Progression

- [Hero sheet](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/sheets/hero-sheet.mjs): `modules/sheets/hero-sheet.mjs`
- [Character creation](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/apps/character-creation.mjs): `modules/apps/character-creation.mjs`
- [Creation workflow](https://github.com/emilithe-tech/veilrunner-system/tree/main/modules/apps/chargen): `modules/apps/chargen`
- [Progression catalog](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/data/progression/catalog-provider.mjs): `modules/data/progression/catalog-provider.mjs`
- [Progression authoring](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/data/progression/authoring-services.mjs): `modules/data/progression/authoring-services.mjs`
- [Content creation](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/data/progression/content-creation-service.mjs): `modules/data/progression/content-creation-service.mjs`

### Rules And Definitions

- [Action resolution](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/actions/resolved-action.mjs): `modules/actions/resolved-action.mjs`
- [Item rules](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/rules/item-rules.mjs): `modules/rules/item-rules.mjs`
- [Definition identity](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/data/definitions/canonical-id.mjs): `modules/data/definitions/canonical-id.mjs`
- [Definition validation](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/data/definitions/validation.mjs): `modules/data/definitions/validation.mjs`
- [Compendium routing](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/data/definitions/compendium-router.mjs): `modules/data/definitions/compendium-router.mjs`

### Campaign Records

- [Datapad](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/apps/datapad.mjs): `modules/apps/datapad.mjs`
- [Relations workspace](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/relations/view.mjs): `modules/relations/view.mjs`
- [Relations service](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/relations/service.mjs): `modules/relations/service.mjs`
- [Relations model](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/relations/model.mjs): `modules/relations/model.mjs`
- [Relations storage](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/relations/vault.mjs): `modules/relations/vault.mjs`
- [Party data](https://github.com/emilithe-tech/veilrunner-system/blob/main/modules/helpers/party.mjs): `modules/helpers/party.mjs`

### Other components

- **Foundry user**

## Connections

- Foundry user → Veilrunner system: starts system (evidence: `veilrunner.mjs`)
- Veilrunner system → Hero sheet: registers sheets (evidence: `veilrunner.mjs`)
- Veilrunner system → Character creation: registers app (evidence: `veilrunner.mjs`)
- Veilrunner system → Action HUD: registers HUD (evidence: `veilrunner.mjs`)
- Veilrunner system → Datapad: registers app (evidence: `veilrunner.mjs`)
- Veilrunner system → Combat tools: registers apps (evidence: `veilrunner.mjs`)
- Veilrunner system → System settings: registers settings (evidence: `veilrunner.mjs`)
- Veilrunner system → Progression catalog: initializes catalog (evidence: `veilrunner.mjs`)
- Veilrunner system → Progression authoring: initializes authoring (evidence: `veilrunner.mjs`)
- Action HUD → Action execution: executes actions (evidence: `modules/apps/action-hud/controller.mjs`)
- Action HUD → System settings: reads preferences (evidence: `modules/apps/action-hud/controller.mjs`)
- Action execution → Firearms: uses firearm actions (evidence: `modules/apps/action-hud/execution.mjs`)
- Firearms → Item rules: checks item rules (evidence: `modules/items/firearms.mjs`)
- Hero sheet → Relations workspace: renders relations (evidence: `modules/sheets/hero-sheet.mjs`)
- Hero sheet → Action resolution: resolves owned actions (evidence: `modules/sheets/hero-sheet.mjs`)
- Character creation → Creation workflow: opens creation flow (evidence: `modules/apps/character-creation.mjs`)
- Character creation → Progression catalog: loads catalog (evidence: `modules/apps/character-creation.mjs`)
- Character creation → Progression authoring: uses authoring (evidence: `modules/apps/character-creation.mjs`)
- Progression authoring → Content creation: creates content (evidence: `modules/data/progression/authoring-services.mjs`)
- Progression authoring → Progression catalog: uses catalog (evidence: `modules/data/progression/authoring-services.mjs`)
- Content creation → Definition identity: builds canonical IDs (evidence: `modules/data/progression/content-creation-service.mjs`)
- Content creation → Definition validation: validates definitions (evidence: `modules/data/progression/content-creation-service.mjs`)
- Progression catalog → Compendium routing: routes definitions (evidence: `modules/data/progression/catalog-provider.mjs`)
- Progression catalog → Definition identity: builds canonical IDs (evidence: `modules/data/progression/catalog-provider.mjs`)
- Datapad → Relations workspace: renders workspace (evidence: `modules/apps/datapad.mjs`)
- Datapad → Relations service: reads relations (evidence: `modules/apps/datapad.mjs`)
- Relations workspace → Relations service: reads state (evidence: `modules/relations/view.mjs`)
- Relations service → Relations model: projects and transacts (evidence: `modules/relations/service.mjs`)
- Relations service → Relations storage: seals stored data (evidence: `modules/relations/service.mjs`)
- Relations service → Party data: uses party data (evidence: `modules/relations/service.mjs`)
- Action HUD → Party data: uses party context
