# belodri/talia-custom architecture

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

- Interactive diagram: https://gitdiagram.com/belodri/talia-custom
- Repository: https://github.com/belodri/talia-custom

## Overview

##### Project Type and Purpose
- This is a Foundry VTT “module” (plugin) tailored for the Talia D&D campaign.
- It bundles character features, items, spells, world‐event hooks, macros, UI templates, styles, and utility code into a single JS module loaded by Foundry.

##### File Structure Analysis
- Top-level “module.json” + “scripts/” contain the entry point (scripts/module.mjs), constants and socket/api setup.
- “features/”, “items/”, “spells/”, “features/professions/”, “features/mythic/” house domain logic for character abilities, items, spells, professions and mythic destinies.
- “world/” holds event-driven handlers (game hooks) that apply global behavior (e.g., settlement simulations, guild manager, wild magic).
- “macros/” & “gmMacros/” contain reusable player and GM macros.
- “utils/” and “wrappers/” provide shared helpers and override core Foundry behavior via hook wrappers.
- “templates/” + “styles/” define the UI layer (Handlebars templates, CSS).
- “jsonData/” provides static lookup tables (names, settlement data, surge tables).
- “scripts/socket.mjs” and “scripts/api.mjs” manage inter-client communication.
- “types/” holds TypeScript definition for socket library.

##### Key Architectural Patterns
- Plugin/Module architecture: scripts/module.mjs registers all hooks, features, macros, templates at initialization.
- Event-Driven (hook-based) design: “world/…” and “wrappers/…” intercept Foundry events and core methods.
- Layered design:
- Core Loader & Configuration
- Domain Logic (features/items/spells/professions/mythic)
- Infrastructure (utils, wrappers, socket/api)
- UI (templates, styles, macros)
- Data (jsonData)

##### Main Components
a. Core Module Loader
- scripts/module.mjs
- scripts/constants.mjs
- scripts/api.mjs / scripts/socket.mjs
b. Domain Logic
- features/
- items/
- spells/
- features/professions/
- features/mythic/
c. Infrastructure
- utils/
- wrappers/
d. World Event Handlers
- world/ (guildmanager, settlement, wildMagic, configChanges, etc.)
e. Macros
- macros/ (player)
- gmMacros/ (GM tools)
f. UI Layer
- templates/ (Handlebars)
- styles/ (CSS)
g. Static Data
- jsonData/
- types/ (TS defs)

##### Relationships & Interactions
- The Core Loader initializes at Foundry startup → registers domain modules, hooks, templates, macros, socket listeners.
- Domain Logic modules export definitions used by the world handlers and UI.
- Infrastructure (utils + wrappers) intercepts or augments Foundry core methods called by domain and world handlers.
- World Event Handlers listen to gameplay events → invoke Domain Logic and Utils.
- Macros call into API/socket layer → trigger domain logic or world changes.
- UI Templates & Styles present data and controls for features, professions, settlements, guild management.
- JSON Data feeds lookup tables into domain logic and UI.

##### Essential Elements
- Clear labels: folder names, role (“Loader”, “Feature Modules”, “World Hooks”, etc.)
- Annotations: note the hook-based pattern, plugin registration step, and client/server messaging via socket

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Foundry Core
    FC["Foundry VTT Core"]:::external

    %% Layer 2: Loader & Configuration
    subgraph "Loader & Configuration"
        direction TB
        MJSON["module.json"]:::loader
        Module["module.mjs"]:::loader
        Constants["constants.mjs"]:::loader
        API["api.mjs"]:::loader
        Socket["socket.mjs"]:::loader
    end

    %% Layer 3: Domain Logic & Static Data
    subgraph "Domain Logic"
        direction TB
        Features["features/"]:::domain
        Items["items/"]:::domain
        Spells["spells/"]:::domain
        Professions["features/professions/"]:::domain
        Mythic["features/mythic/"]:::domain
    end
    subgraph "Static Data & Types"
        direction TB
        JSONData["jsonData/"]:::data
        Types["types/"]:::data
    end

    %% Layer 4: Infrastructure
    subgraph "Infrastructure"
        direction TB
        Utils["utils/"]:::infra
        Wrappers["wrappers/"]:::infra
    end

    %% Layer 5: Event Handlers & Macros
    subgraph "World Event Handlers"
        direction TB
        WorldCore["world/"]:::event
        GuildMgr["world/guildmanager/"]:::event
        Settlement["world/settlement/"]:::event
        WildMagic["world/wildMagic/wildMagic.mjs"]:::event
    end
    subgraph "Macros"
        direction TB
        PlayerMacros["macros/"]:::event
        GMMacros["gmMacros/"]:::event
    end

    %% Layer 6: UI Layer
    subgraph "UI Templates & Styles"
        direction TB
        Templates["templates/"]:::ui
        Styles["styles/"]:::ui
    end

    %% Connections
    FC -->|loads| MJSON
    MJSON --> Module
    Module -->|registers| Features
    Module -->|registers| Items
    Module -->|registers| Spells
    Module -->|registers| Professions
    Module -->|registers| Mythic
    Module -->|init| Utils
    Module -->|init| Wrappers
    Module -->|registers hooks| WorldCore
    Module -->|registers| PlayerMacros
    Module -->|registers| GMMacros
    Module -->|registers| Templates
    Module -->|registers| Styles
    Features <--> Utils
    Items <--> Utils
    Spells <--> Utils
    WorldCore -->|invokes| Features
    WorldCore -->|invokes| Utils
    PlayerMacros -->|calls| API
    PlayerMacros -->|calls| Socket
    API -->|sends| WorldCore
    Socket -->|sends| WorldCore
    Templates -->|display data from| Features
    Templates -->|display data from| JSONData
    Styles -->|style| Templates

    %% Click Events
    click MJSON "https://github.com/belodri/talia-custom/blob/main/module.json"
    click Module "https://github.com/belodri/talia-custom/blob/main/scripts/module.mjs"
    click Constants "https://github.com/belodri/talia-custom/blob/main/scripts/constants.mjs"
    click API "https://github.com/belodri/talia-custom/blob/main/scripts/api.mjs"
    click Socket "https://github.com/belodri/talia-custom/blob/main/scripts/socket.mjs"
    click Features "https://github.com/belodri/talia-custom/blob/main/features/_features.mjs"
    click Professions "https://github.com/belodri/talia-custom/tree/main/features/professions/"
    click Mythic "https://github.com/belodri/talia-custom/tree/main/features/mythic/"
    click Items "https://github.com/belodri/talia-custom/blob/main/items/_items.mjs"
    click Spells "https://github.com/belodri/talia-custom/blob/main/spells/_spells.mjs"
    click Utils "https://github.com/belodri/talia-custom/blob/main/utils/_utils.mjs"
    click Wrappers "https://github.com/belodri/talia-custom/blob/main/wrappers/_wrappers.mjs"
    click WorldCore "https://github.com/belodri/talia-custom/blob/main/world/_world.mjs"
    click GuildMgr "https://github.com/belodri/talia-custom/blob/main/world/guildmanager/_guildmanager.mjs"
    click Settlement "https://github.com/belodri/talia-custom/blob/main/world/settlement/_settlement.mjs"
    click PlayerMacros "https://github.com/belodri/talia-custom/blob/main/macros/_macros.mjs"
    click GMMacros "https://github.com/belodri/talia-custom/blob/main/gmMacros/_gmMacros.mjs"
    click JSONData "https://github.com/belodri/talia-custom/blob/main/jsonData/fantasyNames.json"
    click Types "https://github.com/belodri/talia-custom/blob/main/types/Socketlib.d.ts"

    %% Styles
    classDef loader fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef domain fill:#90EE90,stroke:#333,stroke-width:1px
    classDef infra fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef event fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef ui fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef data fill:#FFDAB9,stroke:#333,stroke-width:1px
```
