# werewolvesrevamped/werewolves-roles architecture

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

- Interactive diagram: https://gitdiagram.com/werewolvesrevamped/werewolves-roles
- Repository: https://github.com/werewolvesrevamped/werewolves-roles

## Overview

##### Project type and purpose
- This is a content-generation project for the “Werewolves Revamped” role book: essentially a static documentation/data generator.
- It ingests a large hierarchy of Markdown files (roles, rules, categories, info, prompts.json) and produces:
- A static website (http://werewolves.me/)
- Data files (JSON for the Werewolves Bot)
- A formatted role-book document

##### File structure
- Top-level content folders (each containing Markdown files):
- _categories  – category headers/templates
- _rules       – rule definitions
- _game        – game data (abilities, displays, polls, teams, etc.)
- _info        – informational messages/queries
- paths        – lookup mappings for commands
- rules        – detailed rule breakdowns
- archive, limited, extra, other, townsfolk, werewolves, unaligned, haunting – role definitions by grouping
- book         – master order file driving TOC generation
- prompts.json – definitions of chatbot prompts
- website      – static assets or site configuration
- No visible application code, but the README describes automated sync, pull-request workflow, query syntax, and book/site generation

##### README for additional insights
- “Book Generation” section describes how the “book” file and folder structure drive ordering
- “Auto Role Sync” ties folder conventions to bot data ingestion
- Query macro syntax (`@Query;…;…@`) is a lightweight template engine built into the generator

##### Main components
a. Content Repository
– GitHub repo managing all Markdown content (roles, rules, categories, info, prompts.json)
b. Build/Generation Engine
– A CLI script or tool (likely Node.js or similar) that:
- Reads the “book” file and directory hierarchy
- Applies category headers from “_categories”
- Parses queries (`@Query;…;…@`) and inline includes (`@x path`)
- Outputs:
– Static HTML/CSS/JS (into “website”) for the public role book site
– JSON payloads (e.g. prompts.json variants) consumed by Werewolves Bot
– A formatted role-book document (e.g. PDF or Doc export)
c. Query Engine Module
– Processes queries in info files, maps metadata (Team, Class, Category, Type) to content
d. Deployment Pipeline / CI
– GitHub Actions or similar that:
- Triggers on pull requests/merges
- Validates Markdown syntax, runs generation scripts
- Deploys static site (to GitHub Pages or Netlify)
- Publishes updated JSON data to the bot repo or a CDN
e. External Integrations
– Google Docs (for the master Role Book Document)
– Werewolves Bot repository (pulls JSON data)

##### Architectural patterns & design principles
- Content-first architecture: folder structure as canonical source
- Template engine for includes & queries (lightweight DSL)
- Separation of concerns: content vs. build scripts vs. output
- Convention over configuration: folder names drive category/role sync
- CI/CD for automated validation and deployment

##### Detail is critical
- Enumerate all major Markdown domains: roles, rules, game, info, prompts
- “book” file as the orchestrator of ordering
- Don’t shy away from listing sub-modules in the Build Engine (Include Resolver, Query Resolver, TOC Generator, JSON Serializer)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD Pipeline
    CI["CI/CD Pipeline"]:::pipeline

    %% Content Repository Subgraph
    subgraph "Content Repository"
        direction TB
        categories["_categories/"]:::content
        rulesDir["_rules/"]:::content
        game["_game/"]:::content
        info["_info/"]:::content
        pathsDir["_paths/"]:::content
        archive["archive/"]:::content
        limited["limited/"]:::content
        extra["extra/"]:::content
        other["other/"]:::content
        townsfolk["townsfolk/"]:::content
        werewolves["werewolves/"]:::content
        unaligned["unaligned/"]:::content
        haunting["haunting/"]:::content
        bookFile["book"]:::content
        prompts["prompts.json"]:::content
    end

    %% Build Engine Subgraph
    subgraph "Build Engine" 
        direction TB
        subgraph "Content Parsers"
            direction TB
            catEngine["Category Template Engine"]:::module
            ruleParser["Rule Parser"]:::module
            gameLoader["Game Data Loader"]:::module
            queryProc["Query Processor"]:::module
            cmdMapper["Command Path Mapper"]:::module
        end
        subgraph "Orchestrator & Serializers"
            direction TB
            bookOrch["Book Orchestrator"]:::module
            includeRes["Include Resolver"]:::module
            queryRes["Query Resolver"]:::module
            tocGen["TOC Generator"]:::module
            jsonSer["JSON Serializer"]:::module
        end
    end

    %% Outputs Subgraph
    subgraph "Outputs"
        direction TB
        site["Static Site"]:::output
        jsonOut["JSON Data"]:::output
        doc["Formatted Role-Book Document"]:::output
    end

    %% External Integrations
    subgraph "External Integrations"
        direction TB
        googleDoc["Google Docs"]:::external
        botRepo["Werewolves Bot Repo"]:::external
        iconsRepo["Icons Repo"]:::external
    end

    %% Flows
    CI -->|"triggers build"| categories
    CI --> rulesDir
    CI --> game
    CI --> info
    CI --> pathsDir
    CI --> archive
    CI --> limited
    CI --> extra
    CI --> other
    CI --> townsfolk
    CI --> werewolves
    CI --> unaligned
    CI --> haunting
    CI --> bookFile
    CI --> prompts

    categories --> catEngine
    rulesDir --> ruleParser
    game --> gameLoader
    info --> queryProc
    pathsDir --> cmdMapper
    archive --> ruleParser
    limited --> ruleParser
    extra --> ruleParser
    other --> ruleParser
    townsfolk --> ruleParser
    werewolves --> ruleParser
    unaligned --> ruleParser
    haunting --> ruleParser
    bookFile --> bookOrch
    prompts --> jsonSer

    catEngine --> includeRes
    ruleParser --> includeRes
    gameLoader --> includeRes
    queryProc --> queryRes
    cmdMapper --> queryRes

    includeRes --> tocGen
    queryRes --> tocGen
    tocGen --> jsonSer
    jsonSer --> site
    jsonSer --> jsonOut
    tocGen --> doc

    site -->|"deployed to"| googleDoc
    jsonOut --> botRepo
    site --> iconsRepo

    %% Click Events for Content Components
    click categories "https://github.com/werewolvesrevamped/werewolves-roles/tree/main/_categories/"
    click rulesDir "https://github.com/werewolvesrevamped/werewolves-roles/tree/main/_rules/"
    click game "https://github.com/werewolvesrevamped/werewolves-roles/tree/main/_game/"
    click info "https://github.com/werewolvesrevamped/werewolves-roles/tree/main/_info/"
    click pathsDir "https://github.com/werewolvesrevamped/werewolves-roles/tree/main/_paths/"
    click archive "https://github.com/werewolvesrevamped/werewolves-roles/tree/main/archive/"
    click limited "https://github.com/werewolvesrevamped/werewolves-roles/tree/main/limited/"
    click extra "https://github.com/werewolvesrevamped/werewolves-roles/tree/main/extra/"
    click other "https://github.com/werewolvesrevamped/werewolves-roles/tree/main/other/"
    click townsfolk "https://github.com/werewolvesrevamped/werewolves-roles/tree/main/townsfolk/"
    click werewolves "https://github.com/werewolvesrevamped/werewolves-roles/tree/main/werewolves/"
    click unaligned "https://github.com/werewolvesrevamped/werewolves-roles/tree/main/unaligned/"
    click haunting "https://github.com/werewolvesrevamped/werewolves-roles/tree/main/haunting/"
    click bookFile "https://github.com/werewolvesrevamped/werewolves-roles/tree/main/book"
    click prompts "https://github.com/werewolvesrevamped/werewolves-roles/blob/main/prompts.json"

    %% Styles
    classDef content fill:#CCF,stroke:#333,stroke-width:1px;
    classDef module fill:#CFC,stroke:#333,stroke-width:1px;
    classDef output fill:#FCF,stroke:#333,stroke-width:1px;
    classDef external fill:#CFF,stroke:#333,stroke-width:1px;
    classDef pipeline fill:#FFC,stroke:#333,stroke-width:1px;
```
