# maoxiaoyuz/long-novel-gpt architecture

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

- Interactive diagram: https://gitdiagram.com/maoxiaoyuz/long-novel-gpt
- Repository: https://github.com/maoxiaoyuz/long-novel-gpt

## Overview

##### Project Overview
- Long-Novel-GPT is a full-stack application that lets users generate long novels via a multi-phase creative workflow (大纲 → 章节 → 正文). It leverages GPT and other large language models to generate and refine story content.
- The architecture includes components for handling API calls to different LLM services, a rich collection of prompt templates (organized under the prompts folder), and both backend and frontend parts—all containerized via Docker (with dedicated Dockerfiles for overall, backend, and frontend).

##### Main Components
a. Frontend:
- Directory: “frontend”
- Features: Contains the UI assets (HTML, CSS, JavaScript), an Nginx config for serving the static content, and example novel data.
- Role: Acts as the client-facing web interface where users interact with the system (e.g., initiating creative requests, monitoring progress, configuring settings).

b. Backend:
- Directory: “backend”
- Features: Contains the main backend application (app.py, healthcheck.py, summary.py, xapp.py, etc.), utilities, and configuration (setting.py, requirements.txt).
- Role: Processes API requests coming from the frontend, manages workflow logic (creating chapters, outlines, etc.), and handles the "reflective loop" to refine story generation.

c. Core Library:
- Directory: “core”
- Features: Contains shared functionality (e.g., writer utilities, parsing, and functions to manage both frontend and backend operations).
- Role: Encapsulates business logic that is re-used across the application, enabling the transformation of prompts into usable story segments.

d. LLM API Integration:
- Directory: “llm_api”
- Features: Modules for different LLM providers (OpenAI, Baidu, SparkAI, etc.), integration with MongoDB-related caching (mongodb_cache, mongodb_cost) and price configurations.
- Role: Acts as the abstraction layer for communicating with external large language model services, managing API keys, endpoints, cost tracking, and caching.

e. Prompts and Templates:
- Directory: “prompts”
- Features: Rich assortment of prompt files (YAML, text, and Jinja2 templates) for different creative tasks (创作剧情、创作正文、审阅, etc.).
- Role: Provides the structured instructions that drive each stage of novel creation, allowing for modular and community-driven contributions.

f. Docker and Deployment:
- Files: Dockerfile’s at the root, in “backend”, “frontend”, docker_build.sh, docker_run.sh, .env.example, etc.
- Role: Containerizes different components to simplify deployment, with instructions for environment configuration and inter-container communication (note the special parameters like --add-host for local LLM services).

##### Relationships and Interaction Flow
- User/Client → Frontend: Browser accesses the frontend static assets served (often by Nginx as configured in nginx.conf) which handle user interactions.
- Frontend → Backend: UI interactions trigger AJAX calls to the backend, which provides APIs for initiating novel generation requests.
- Backend → Core & Prompts: The backend uses the core library to process user requests, utilizes prompt templates (from the prompts directory) to generate instructions for text creation phases.
- Backend → LLM API: Backend components then call corresponding LLM API modules (in llm_api) to interact with external language models for generating text.
- Data Feedback Loop: Results from external API calls are fed back into the workflow (using utilities in “core” and custom scripts in “custom”) to refine content iteratively.
- Docker Environment: The Docker configuration encapsulates both frontend and backend components, ensuring consistent deployment. Environment variables (.env) and scripts (docker_run.sh) mediate how components interact, including linking to local model services if needed.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The clear division into frontend, backend, core utilities, prompt templates, and API integration layers.
- Modularity & Extensibility: The use of multiple directories (especially for prompts and llm_api) illustrates how the system can add new language models or creative templates with minimal interdependency.
- Containerization: Dockerfiles for backend and frontend indicate a microservices-like approach, although components remain tightly integrated through API calls.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    User["User/Client"]:::client

    %% Application Layer
    subgraph "Application Layer"
        %% Frontend Subgraph
        subgraph "Frontend"
            FE_Main["Frontend (UI)"]:::frontend
            FE_Assets["Assets: index.html, nginx.conf, JS/CSS"]:::frontend_small
            FE_Main --> FE_Assets
        end

        %% Backend Subgraph
        subgraph "Backend"
            BE_Main["Backend (API & Workflow)"]:::backend
            Core["Core Library"]:::core
            Prompts["Prompts/Templates"]:::prompt
            LLM["LLM API Integration"]:::api
            BE_Main -->|"uses"| Core
            BE_Main -->|"uses"| Prompts
            BE_Main -->|"calls"| LLM
            LLM -->|"feedback"| BE_Main
        end
    end

    %% Deployment Layer
    subgraph "Deployment"
        Docker_Root["Dockerfile (Root)"]:::deployment
        Docker_BE["Dockerfile.backend"]:::deployment
        Docker_FE["Dockerfile.frontend"]:::deployment
        Env[".env.example"]:::deployment
        Build["docker_build.sh"]:::deployment
        Run["docker_run.sh"]:::deployment
        FE_Run["frontend/docker_run.sh"]:::deployment
    end

    %% Interactions/Flow
    User -->|"accesses"| FE_Main
    FE_Main -->|"triggers"| BE_Main

    %% Docker encapsulation links (dotted arrows for deployment association)
    Docker_Root --- FE_Main
    Docker_Root --- BE_Main
    Docker_BE --- BE_Main
    Docker_FE --- FE_Main
    Build --- Docker_Root
    Run --- Docker_Root
    FE_Run --- FE_Main

    %% Click Events
    click FE_Main "https://github.com/maoxiaoyuz/long-novel-gpt/tree/main/frontend"
    click BE_Main "https://github.com/maoxiaoyuz/long-novel-gpt/tree/main/backend"
    click Core "https://github.com/maoxiaoyuz/long-novel-gpt/tree/main/core"
    click Prompts "https://github.com/maoxiaoyuz/long-novel-gpt/tree/main/prompts"
    click LLM "https://github.com/maoxiaoyuz/long-novel-gpt/tree/main/llm_api"
    click Docker_Root "https://github.com/maoxiaoyuz/long-novel-gpt/tree/main/Dockerfile"
    click Docker_BE "https://github.com/maoxiaoyuz/long-novel-gpt/blob/main/backend/Dockerfile.backend"
    click Docker_FE "https://github.com/maoxiaoyuz/long-novel-gpt/blob/main/frontend/Dockerfile.frontend"
    click Env "https://github.com/maoxiaoyuz/long-novel-gpt/blob/main/.env.example"
    click Build "https://github.com/maoxiaoyuz/long-novel-gpt/blob/main/docker_build.sh"
    click Run "https://github.com/maoxiaoyuz/long-novel-gpt/blob/main/docker_run.sh"
    click FE_Run "https://github.com/maoxiaoyuz/long-novel-gpt/blob/main/frontend/docker_run.sh"

    %% Styles
    classDef client fill:#43AA8B,stroke:#2B7A0B,stroke-width:2px,color:#ffffff;
    classDef frontend fill:#f9c74f,stroke:#c17c00,stroke-width:2px,color:#000000;
    classDef frontend_small fill:#f9c74f,stroke:#c17c00,stroke-width:1px,color:#000000;
    classDef backend fill:#90be6d,stroke:#5a8b43,stroke-width:2px,color:#000000;
    classDef core fill:#f8961e,stroke:#d27e00,stroke-width:2px,color:#ffffff;
    classDef prompt fill:#577590,stroke:#3b4f6c,stroke-width:2px,color:#ffffff;
    classDef api fill:#277da1,stroke:#105e8d,stroke-width:2px,color:#ffffff;
    classDef deployment fill:#f94144,stroke:#c62828,stroke-width:2px,color:#ffffff;
```
