# pedevteam/pe architecture

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

- Interactive diagram: https://gitdiagram.com/pedevteam/pe
- Repository: https://github.com/pedevteam/pe

## Overview

##### Main Components
a. Story Content Repository – This is in the “src/Twee” directory. It is organized hierarchically into major units (e.g., “Cheer”, “School”, “Friends”, “Tasks”, “Minigames”, etc.). Each folder holds many “.twee” files that represent the various scenes, episodes, and interactive branches in the narrative.
b. JavaScript Functionality Modules – Found in “src/javascript”. These files add behavior and game logic (like chores, clothing, inventory, tasks, minigames, and more) to support the interactive narrative.
c. Build & Conversion Layer – Tweego binaries and story formats (under “tweego”) teamed with build scripts like “makeHTML.bat”. These tools convert the combined narrative (.twee) files and possibly embed the JavaScript into a final HTML file (PE.html or a similarly named output).
d. Documentation and Macros – The “Docs” folders provide guidelines, macros, and references that might drive certain conversion settings or narrative macros.
e. Debug/Testing Components – There are debug .twee files and a “WorkInProgress” section used for testing and troubleshooting narrative branches.

##### Relationships and Interactions
a. The narrative content (.twee files) is the source of the interactive story and is processed by Tweego. The build script “makeHTML.bat” acts as a coordinator that calls the Tweego conversion engine.
b. The Tweego engine (along with the Sugarcube story format) takes the narrative content and outputs an HTML file that, when run in a browser, integrates all interactive elements.
c. JavaScript modules provide dynamic functionality at runtime (e.g., controlling story flow, managing player data like items and variables, or triggering debug and tasks functions). They are integrated into the HTML so that the final output is not just static story text.
d. Documentation, configuration (Git files, README, LICENSE), and possibly macro files also connect to the build process by informing developers and possibly scripting how narrative macros function.

##### Architectural Patterns and Design Principles
a. Separation of Concerns – The narrative (content) is completely separated from the logic (JavaScript), and both are separate from the build tools. This modular structure makes it easier to maintain and extend the interactive story.
b. Clear Data Flow – The process flows from writing/editing scenes (in .twee files) → processing via Tweego with the Sugarcube story format → embedding/augmenting with JavaScript modules → final output (HTML) that delivers the interactive experience.
c. Extensibility and Debug Support – The presence of debug directories and “WorkInProgress” shows clear support for iterative testing and extension.

##### Relevant Technologies and Frameworks
a. Twine/Twee format for interactive narrative content.
b. Sugarcube (version 2.30.0) as the story format framework.
c. Tweego as the static conversion/build tool.
d. JavaScript (modularized under “src/javascript”) for runtime logic and game dynamics.
e. Batch files (“makeHTML.bat”) to automate the build process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Narrative Content Layer
    subgraph "Narrative Content Layer"
        NC["Narrative Content<br/>(Scenes: Cheer, School, Tasks, Minigames, etc.)"]:::narrative
    end

    %% Build & Conversion Layer
    subgraph "Build & Conversion Layer"
        BScript["Build Script (makeHTML.bat)"]:::build
        Tweego["Tweego & Sugarcube Engine"]:::build
        BScript -->|"triggers"| Tweego
    end

    %% Game Logic & Modules Layer
    subgraph "Game Logic & Modules Layer"
        GL["Game Logic & Modules<br/>(Inventory, Tasks, Minigames, etc.)"]:::logic
    end

    %% Documentation & Macros
    subgraph "Documentation & Macros"
        Docs["Documentation & Macros"]:::docs
    end

    %% Debug/Testing Components
    subgraph "Debug/Testing Layer"
        Debug["Debug Scenes"]:::debug
        WIP["WorkInProgress"]:::debug
    end

    %% Final Output / Runtime
    FOUT["Interactive HTML Output"]:::final

    %% Data Flow Connections
    NC -->|"processed_by"| BScript
    Tweego -->|"generates"| FOUT
    GL -->|"integrates_into"| FOUT
    Docs -->|"informs"| BScript
    Debug -->|"feedback"| NC
    WIP -->|"feedback"| NC

    %% Styles
    classDef narrative fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef build fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef logic fill:#abebc6,stroke:#229954,stroke-width:2px;
    classDef docs fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef debug fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef final fill:#e8daef,stroke:#8e44ad,stroke-width:2px;

    %% Click Events
    click NC "https://github.com/pedevteam/pe/tree/master/src/Twee"
    click GL "https://github.com/pedevteam/pe/tree/master/src/javascript"
    click BScript "https://github.com/pedevteam/pe/blob/master/makeHTML.bat"
    click Tweego "https://github.com/pedevteam/pe/tree/master/tweego"
    click Docs "https://github.com/pedevteam/pe/tree/master/Docs/Macros"
    click Debug "https://github.com/pedevteam/pe/tree/master/src/Twee/Debug"
    click WIP "https://github.com/pedevteam/pe/tree/master/src/Twee/WorkInProgress"
```
