# edwardathomson/novelwriter architecture

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

- Interactive diagram: https://gitdiagram.com/edwardathomson/novelwriter
- Repository: https://github.com/edwardathomson/novelwriter

## Overview

##### Project Type and Purpose
- Full‐stack standalone Python desktop application with a GUI (Tkinter)
- Purpose: guide authors through multi‐stage novel creation (parameters → lore → structure → scenes → chapters), leveraging LLMs

##### File Structure
- Top level:
– main.py (app entry, launches GUI)
– ai_helper.py, rag_helper.py, helper_fns.py, logger_config.py (shared utilities/helpers)
– parameters.py, lore.py, story_structure.py, scene_plan.py, chapter_writing.py (core pipeline modules)
– Generators/ (genre‐specific generator classes and JSON profiles)
– genre_configs/ (genre parameter configurations)
– combine.py (post‐processing script to assemble chapters)
- Supporting docs under docs/ and screenshots/ for user/developer guidance

##### README for Architecture Insights
- Modular architecture:
– Genre Handlers
– Configuration System
– Character & Faction Generators
– Story Integration (structure + scenes)
- Workflow stages mapped to GUI tabs

##### Main Components & Their Interactions
a. User Interface Layer (Tkinter GUI – main.py)
- Captures user selections: genre, model, story structure, etc.
- Presents each stage as a tab (Parameters, Lore, Structure, Scenes, Write)
→ Calls core pipeline modules
b. Core Pipeline Modules
1) Parameters Manager (parameters.py + genre_configs/)
2) Lore Generation (lore.py + Generators/ + ai_helper.py + rag_helper.py)
3) Story Structure (story_structure.py)
4) Scene Planning (scene_plan.py)
5) Chapter Writing (chapter_writing.py)
6) Combine Script (combine.py) – optional CLI utility
c. Helpers & Utilities
- ai_helper.py: abstracts LLM API calls (OpenAI, Gemini, Claude)
- rag_helper.py: retrieval‐augmented generation support
- helper_fns.py: shared data transformations
- logger_config.py: centralized logging setup
d. Configuration & Data
- .env (API keys)
- JSON profiles in Generators/
- genre_configs/*.py for parameter defaults
- Generated outputs in current_work/ (chapters, intermediate files)
e. External Services
- LLM endpoints (OpenAI, Google Gemini, Anthropic Claude)

##### Architectural Patterns & Design Principles
- Modular, stage‐based pipeline
- Genre‐driven strategy pattern (Genre Handlers + configs)
- Separation of concerns: UI vs. core logic vs. helpers vs. data
- Externalized configurations (JSON + Python modules)
- Clear single responsibility for each script/module

##### Essential Elements
- Clear labels (module name + purpose)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI["main.py\nTkinter GUI"]:::ui
    end

    %% Core Pipeline Modules
    subgraph "Core Pipeline"
        subgraph "Parameters Manager"
            Params["parameters.py"]:::core
            GenreConfigs["genre_configs"]:::data
        end
        subgraph "Lore Generation"
            Lore["lore.py"]:::core
            GeneratorsDir["Generators"]:::data
            AIH["ai_helper.py"]:::util
            RAG["rag_helper.py"]:::util
        end
        SS["story_structure.py"]:::core
        SP["scene_plan.py"]:::core
        CW["chapter_writing.py"]:::core
        Combine["combine.py"]:::core
    end

    %% Utilities
    subgraph "Utilities"
        HelperFns["helper_fns.py"]:::util
        Logger["logger_config.py"]:::util
    end

    %% Configuration & Data
    subgraph "Configuration & Data Stores"
        Env[".env\n(API Keys)"]:::data
        Profiles["faction_profiles.json"]:::data
    end

    %% External Services
    ExternalLLM(("OpenAI\nGemini\nClaude")):::external

    %% Connections
    UI -->|"invokes"| Params
    UI -->|"invokes"| Lore
    UI -->|"invokes"| SS
    UI -->|"invokes"| SP
    UI -->|"invokes"| CW

    Params -->|"loads configs"| GenreConfigs
    Lore -->|"uses generators"| GeneratorsDir
    Lore -->|"calls"| AIH
    Lore -->|"calls"| RAG

    AIH -->|"API calls"| ExternalLLM
    RAG -->|"augments via"| ExternalLLM

    Params -->|"logs & transforms"| HelperFns
    Lore -->|"logs & transforms"| HelperFns
    SS -->|"logs & transforms"| HelperFns
    SP -->|"logs & transforms"| HelperFns
    CW -->|"logs & transforms"| HelperFns
    Combine -->|"logs & transforms"| HelperFns

    Params -->|"logging"| Logger
    Lore -->|"logging"| Logger
    SS -->|"logging"| Logger
    SP -->|"logging"| Logger
    CW -->|"logging"| Logger
    Combine -->|"logging"| Logger

    Combine -->|"writes outputs"| Profiles

    %% Click Events
    click UI "https://github.com/edwardathomson/novelwriter/blob/main/main.py"
    click Params "https://github.com/edwardathomson/novelwriter/blob/main/parameters.py"
    click GenreConfigs "https://github.com/edwardathomson/novelwriter/tree/main/genre_configs/"
    click Lore "https://github.com/edwardathomson/novelwriter/blob/main/lore.py"
    click GeneratorsDir "https://github.com/edwardathomson/novelwriter/tree/main/Generators/"
    click AIH "https://github.com/edwardathomson/novelwriter/blob/main/ai_helper.py"
    click RAG "https://github.com/edwardathomson/novelwriter/blob/main/rag_helper.py"
    click SS "https://github.com/edwardathomson/novelwriter/blob/main/story_structure.py"
    click SP "https://github.com/edwardathomson/novelwriter/blob/main/scene_plan.py"
    click CW "https://github.com/edwardathomson/novelwriter/blob/main/chapter_writing.py"
    click Combine "https://github.com/edwardathomson/novelwriter/blob/main/combine.py"
    click HelperFns "https://github.com/edwardathomson/novelwriter/blob/main/helper_fns.py"
    click Logger "https://github.com/edwardathomson/novelwriter/blob/main/logger_config.py"
    click Profiles "https://github.com/edwardathomson/novelwriter/blob/main/Generators/faction_profiles.json"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef util fill:#FFD700,stroke:#333,stroke-width:1px;
    classDef data fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px;
```
