# desmondchoy/adventures architecture

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

- Interactive diagram: https://gitdiagram.com/desmondchoy/adventures
- Repository: https://github.com/desmondchoy/adventures

## Overview

##### Main Components
a. Backend Core:
- Entry Point & Initialization – The application’s entry (app/main.py) wires up the FastAPI app with all middleware, routers, and database initialization.
- Models & State Management – Includes modules (app/models, app/database.py) handling application data like AdventureState and Story objects.
- Services – A large portion is structured under app/services. Within these, you have several sub-components:
- WebSocket Services (e.g., app/services/websocket/*): For handling real-time communication, choice processing, content generation, streaming of narrative events, and image generation.
- LLM Integration (e.g., app/services/llm/*): For dynamic text generation, paragraph formatting, and prompt engineering.
- Summary Services (e.g., app/services/summary/*): For processing chapter summaries, questions, and overall narrative recaps.
- Other utility services for state storage and chapter management.
b. Content/Data Sources:
- Educational Content – Look at app/data/lessons (CSV files) and app/data/stories (YAML files) which provide the actual content driving lessons and narratives.
- Data Initialization – Files such as app/init_data.py help bootstrap data into the system.
c. Frontend/Presentation:
- HTTP Routers – Handled by app/routers/web.py for traditional web routes.
- Template Engine – The app/templates directory contains HTML templates which are organized using layouts, components, and macros.
- Static Assets – Managed in app/static, which includes CSS, JavaScript, and images for rendering the UI and for the integrated React summary chapter app.
d. Documentation/Design References:
- The memory-bank folder contains documentation, architectural decisions, and context that is useful for understanding design rationale.

##### Relationships and Interactions
- Traditional REST/HTTP routes (handled via the web router and templates).
- Real-Time Communication Channel (handled via the WebSocket router and its core services).
- On the backend, the WebSocket router (app/routers/websocket_router.py) communicates with the modular WebSocket core (app/services/websocket/core.py) and its submodules:
- Choice Processor, Content Generator, Stream Handler, Image Generator, and Summary Generator.
- The WebSocket components hook into other central services like the Adventure State Manager (app/services/adventure_state_manager.py) and Chapter Manager (app/services/chapter_manager.py).
- The Chapter Manager leverages the LLM service for AI-generated text and formatting.
- The Summary services bridge the information back to the client via both the WebSocket and the React Summary App (evident in the separate static assets and summary router).

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project is clearly divided into different “services” and “routers” folders that isolate the responsibilities between content generation, state management, routing, and client display.
- Modularity: Each function (e.g., image generation, summary creation, LLM integration) is encapsulated into separate modules, allowing for provider-agnostic AI integration.
- Real-Time Communication: The use of WebSockets ensures a user’s learning journey and narrative are delivered dynamically, with robust error recovery.

##### Bringing It All Together
- You capture all critical components:
- Web Client and its state management (client-side storage and React summary components).
- FastAPI-based server with both Web and WebSocket routes.
- Microservices for adventure state, chapter management, AI generation (both for text and images), and content formatting.
- Data sources that feed content into the system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Interface
    subgraph "Client Interface"
        WC["Web Client"]:::frontend
    end

    %% Frontend Presentation
    subgraph "Frontend Presentation"
        T["Templates (HTML)"]:::frontend
        SA["Static Assets & React Summary App"]:::frontend
    end

    %% HTTP Routers
    subgraph "HTTP Routers"
        WR["Web Router"]:::backend
        SR["Summary Router"]:::backend
        WSR["WebSocket Router"]:::backend
    end

    %% Backend Core
    subgraph "Backend Core"
        AIN["App Initialization"]:::backend
        MS["Models & Database"]:::backend
        subgraph "Services"
            subgraph "WebSocket Services"
                WS_Core["Core Service"]:::backend
                CP["Choice Processor"]:::backend
                CG["Content Generator"]:::backend
                SH["Stream Handler"]:::backend
                IG["Image Generator"]:::backend
                SG["Summary Generator"]:::backend
            end
            subgraph "LLM Integration"
                PF["Paragraph Formatter"]:::backend
                PE["Prompt Engineering"]:::backend
                PT["Prompt Templates"]:::backend
                LP["LLM Providers"]:::backend
            end
            subgraph "Summary Services"
                SS["Summary Processing"]:::backend
            end
            subgraph "Adventure & Chapter Management"
                ASM["Adventure State Manager"]:::backend
                CM["Chapter Manager"]:::backend
                STS["State Storage"]:::backend
            end
        end
    end

    %% Data Sources & Initialization
    subgraph "Data Sources & Init"
        LNS["Lessons Data"]:::data
        STD["Stories Data"]:::data
        LL["Lesson Loader"]:::data
        SL["Story Loader"]:::data
        DI["Data Initialization"]:::data
    end

    %% Documentation / Design References
    subgraph "Documentation"
        MB["Memory Bank"]:::doc
    end

    %% Connections
    WC -->|"HTTP"| WR
    WC -->|"WebSocket"| WSR
    WC -->|"Summary"| SR

    WR --> T
    WR --> SA
    SR --> SA

    AIN --> WR
    AIN --> SR
    AIN --> WSR
    AIN --> MS

    WSR --> WS_Core
    WS_Core --> CP
    WS_Core --> CG
    WS_Core --> SH
    WS_Core --> IG
    WS_Core --> SG

    WS_Core --> ASM
    WS_Core --> CM

    CM --> PF
    CM --> PE
    CM --> PT
    CM --> LP

    SG --> SS
    SS --> SR

    DI --> MS
    LL --> MS
    SL --> MS
    LNS --> LL
    STD --> SL

    ASM --> STS
    CM --> STS

    MB --- AIN
    MB --- MS

    %% Click Events
    click AIN "https://github.com/desmondchoy/adventures/blob/main/app/main.py"
    click MS "https://github.com/desmondchoy/adventures/tree/main/app/models"
    click MS "https://github.com/desmondchoy/adventures/blob/main/app/database.py"
    click WS_Core "https://github.com/desmondchoy/adventures/blob/main/app/services/websocket/core.py"
    click CP "https://github.com/desmondchoy/adventures/blob/main/app/services/websocket/choice_processor.py"
    click CG "https://github.com/desmondchoy/adventures/blob/main/app/services/websocket/content_generator.py"
    click SH "https://github.com/desmondchoy/adventures/blob/main/app/services/websocket/stream_handler.py"
    click IG "https://github.com/desmondchoy/adventures/blob/main/app/services/websocket/image_generator.py"
    click SG "https://github.com/desmondchoy/adventures/blob/main/app/services/websocket/summary_generator.py"
    click PF "https://github.com/desmondchoy/adventures/blob/main/app/services/llm/paragraph_formatter.py"
    click PE "https://github.com/desmondchoy/adventures/blob/main/app/services/llm/prompt_engineering.py"
    click PT "https://github.com/desmondchoy/adventures/blob/main/app/services/llm/prompt_templates.py"
    click LP "https://github.com/desmondchoy/adventures/blob/main/app/services/llm/providers.py"
    click ASM "https://github.com/desmondchoy/adventures/blob/main/app/services/adventure_state_manager.py"
    click CM "https://github.com/desmondchoy/adventures/blob/main/app/services/chapter_manager.py"
    click STS "https://github.com/desmondchoy/adventures/blob/main/app/services/state_storage_service.py"
    click LNS "https://github.com/desmondchoy/adventures/tree/main/app/data/lessons"
    click STD "https://github.com/desmondchoy/adventures/tree/main/app/data/stories"
    click LL "https://github.com/desmondchoy/adventures/blob/main/app/data/lesson_loader.py"
    click SL "https://github.com/desmondchoy/adventures/blob/main/app/data/story_loader.py"
    click DI "https://github.com/desmondchoy/adventures/blob/main/app/init_data.py"
    click WR "https://github.com/desmondchoy/adventures/blob/main/app/routers/web.py"
    click SR "https://github.com/desmondchoy/adventures/blob/main/app/routers/summary_router.py"
    click WSR "https://github.com/desmondchoy/adventures/blob/main/app/routers/websocket_router.py"
    click T "https://github.com/desmondchoy/adventures/tree/main/app/templates"
    click SA "https://github.com/desmondchoy/adventures/tree/main/app/static"
    click MB "https://github.com/desmondchoy/adventures/tree/main/memory-bank"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef backend fill:#c8e6c9,stroke:#43a047,stroke-width:2px;
    classDef data fill:#fff9c4,stroke:#fbc02d,stroke-width:2px;
    classDef doc fill:#f8bbd0,stroke:#d81b60,stroke-width:2px;
```
