# uglyboy-tl/obsidian-ink-player architecture

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

- Interactive diagram: https://gitdiagram.com/uglyboy-tl/obsidian-ink-player
- Repository: https://github.com/uglyboy-tl/obsidian-ink-player

## Overview

##### Project Type & Purpose
- The plugin integrates with Obsidian (a note-taking platform) and provides a gaming/interactive fiction experience.
- It uses the ink engine to interpret and render ink scripts; therefore, there is a clear separation between the UI components (which handle display and interaction) and the story logic (parsing and story control).

##### File Structure
- Top-level files such as manifest.json, main.ts, and src/plugin.ts indicate the entry points for the Obsidian plugin.
- The src folder is organized into several key areas:
‒ components: Contains React components (e.g., InkStory.tsx, InkChoices.tsx) that build the visible UI for the story.
‒ hooks: Handles lifecycle events, errors, file handling, and story updates. These hooks act as glue between user actions and the underlying story logic.
‒ lib:
▪ ink: Contains the core logic for the ink engine including parsers and functions to process ink files. Files like choice_parser.ts, parser.ts, and main.ts are central to story parsing.
▪ patches: Contains additional modifications (or “patches”) for features like autosave, custom buttons, and image/audio handling to extend or modify the ink behavior.
▪ utils: Contains utility functions (e.g., file handlers) for supporting various operations across the plugin.
- locales directory holds language files for internationalization, emphasizing support for both English and Chinese.

##### Key Components and Their Relationships
- Obsidian Environment:
‒ The plugin integrates with Obsidian (using manifest.json, plugin.ts), receiving commands when a user activates an ink story.
- Plugin Core:
‒ src/plugin.ts and src/settings.ts form the backbone of the plugin, initializing the system, handling commands, and managing global configurations.
- UI/Presentation Layer:
‒ The components folder contains React-based UI components that display story content, choices, menus, images – all driven by the ink narrative.
‒ src/view.ts can be seen as the main entry point that binds UI components with the story logic.
- Story and Logic Handling:
‒ The hooks directory is responsible for wiring up events and managing asynchronous tasks such as error reporting, file reading, or managing story state.
‒ The lib/ink directory processes ink files and interprets story structures, while the hooks/story sub-directory helps manage story-specific events like choices and variable states.
- Extensions & Patches:
‒ The patches directory shows how the plugin extends core behaviors (like autosave, custom tags, or UI tweaks) to further refine the interactive experience.
- Utilities & Internationalization:
‒ The lib/utils directory provides shared helper functions, ensuring smooth integration with Obsidian files.
‒ The locales folder supplies i18n support, ensuring messages and UI elements are correctly localized.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph: Obsidian Integration
    subgraph "Obsidian Integration"
        A1["Obsidian Host: Manifest"]:::integration
        A2["Obsidian Host: Plugin Entry"]:::integration
    end

    %% Subgraph: Plugin Core
    subgraph "Plugin Core"
        B1["Plugin Settings"]:::core
        B2["Plugin Main"]:::core
    end

    %% Subgraph: Presentation Layer
    subgraph "Presentation Layer"
        C["UI Components (React)"]:::ui
    end

    %% Subgraph: Story Processing
    subgraph "Story Processing"
        D["Event Hooks"]:::logic
        E["Ink Engine & Parsing Module"]:::logic
    end

    %% Subgraph: Extensions
    subgraph "Extensions"
        F["Patches & Extensions"]:::patch
    end

    %% Subgraph: Support Modules
    subgraph "Support Modules"
        G1["Utilities"]:::support
        G2["Internationalization"]:::support
    end

    %% Connections between components
    A1 --> A2
    A2 --> B1
    A2 --> B2
    B1 --> C
    B2 --> C
    B1 --> D
    B2 --> D
    C --> D
    D --> E

    %% Bidirectional interactions for Extensions
    F --> C
    C --> F
    F --> E
    E --> F

    %% Support Modules interactions
    G1 --> C
    G1 --> D
    G1 --> E
    G2 --> C
    G2 --> D
    G2 --> E

    %% Styles
    classDef integration fill:#FFEEAD,stroke:#333,stroke-width:2px;
    classDef core fill:#B3E5FC,stroke:#333,stroke-width:2px;
    classDef ui fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef logic fill:#F8BBD0,stroke:#333,stroke-width:2px;
    classDef patch fill:#D1C4E9,stroke:#333,stroke-width:2px;
    classDef support fill:#FFE0B2,stroke:#333,stroke-width:2px;

    %% Click Events for Component Mapping
    click A1 "https://github.com/uglyboy-tl/obsidian-ink-player/blob/master/manifest.json"
    click A2 "https://github.com/uglyboy-tl/obsidian-ink-player/blob/master/src/plugin.ts"
    click B1 "https://github.com/uglyboy-tl/obsidian-ink-player/blob/master/src/settings.ts"
    click B2 "https://github.com/uglyboy-tl/obsidian-ink-player/blob/master/main.ts"
    click C "https://github.com/uglyboy-tl/obsidian-ink-player/tree/master/src/components"
    click D "https://github.com/uglyboy-tl/obsidian-ink-player/tree/master/src/hooks"
    click E "https://github.com/uglyboy-tl/obsidian-ink-player/tree/master/src/lib/ink"
    click F "https://github.com/uglyboy-tl/obsidian-ink-player/tree/master/src/lib/patches"
    click G1 "https://github.com/uglyboy-tl/obsidian-ink-player/tree/master/src/lib/utils"
    click G2 "https://github.com/uglyboy-tl/obsidian-ink-player/tree/master/src/locales"
```
