# elct9620/ggj2025 architecture

> Architecture diagram of the GitHub repository elct9620/ggj2025, 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/elct9620/ggj2025
- Repository: https://github.com/elct9620/ggj2025

## Overview

##### Overall Architecture
- Project Purpose & Type: This is an interactive game where players communicate via email. The game logic involves responding to email interactions, managing game state (e.g., cities, NPCs, events), and building dynamic email messages.
- Hosting Environment: It is deployed on Cloudflare Workers using Cloudflare KV for persistence, and it integrates with AWS SES for sending emails and OpenAI’s API for AI-based interactions.

##### Out the Main Components
- External Interfaces:
- User Email Interaction: The entry point is email communication initiated by users.
- Cloudflare Email Routing: Directs incoming emails to the Cloudflare Worker.
- External Dependencies: AWS SES (sending emails), OpenAI API (likely providing AI-completion or interaction capabilities).
- Cloudflare Worker & Deployment:
- The wrangler.json configuration and other Cloudflare-specific files indicate that the game runtime is hosted on Cloudflare Workers.
- Cloudflare KV: Acts as a persistence layer for storing game state (managed through src/repository/KvCityRepository.ts).
- Application Core (src/app):
- API/HTTP Routes: The email endpoint (in src/app/routes/email.ts) and web interface (src/app/web.tsx) provide different access paths.
- Configuration and Dependency Injection: Files like container.ts and config.ts show that the app has a defined configuration and dependency management system.
- LLM Middleware: Found in src/app/llm/middleware.ts, this layer likely handles requests to/from the OpenAI API.
- Domain and Business Logic:
- Agents: In src/agent, these handle the NPC behavior (for example, GuideAgent, NpcJack, etc.) and have supporting tools (like Favorability, Skill, Valve) and prompt templates.
- Use Cases: (src/usecase) These files encapsulate game actions (e.g., TalkWithNpcUsecase, CitySnapshotUsecase, etc.) and represent the core gameplay logic.
- Controllers: (src/controller) They connect incoming requests to game logic, managing different interactions like starting a new game or handling NPC dialogues.
- Builders and Presenters: The builder components (in src/builder) generate game messages (e.g., welcome and end messages), while the presenter (SesEmailPresenter) formats emails to be sent.
- Persistence and Domain Entities:
- Entities: (located in src/entity) define core game objects such as City, CityEvent, and Npc.
- Repository: The KvCityRepository implements persistence for these domain objects.

a. Start by sketching out external components on the left:
- The “Application Core” layer (src/app) which further subdivides into:
- API/HTTP Endpoints (e.g., email route, web route)
- Configuration & Dependency Container
- LLM Middleware for processing requests with the OpenAI API.
c. Inside or directly connected to the Cloudflare Worker, add the “Game Logic” section:
- Separate these further into Agents (NPC logic, GuideAgent, etc.), Usecases (gameplay flow and interactions), Controllers (mapping incoming requests to game actions), Builders (message creation), and Presenters (formatting emails).
g. Architectural Patterns:
- That the project employs a layered architecture (presentation, application, domain, infrastructure) reminiscent of the Clean Architecture or MVC/MVVM hybrid.
- Modularity by drawing boundaries between the UI layer (web and email interface), the core game logic (usecases, agents, controllers), and the persistence layer (repositories via Cloudflare KV).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces
    subgraph "External Interfaces"
        extUser["User Email Interaction"]:::external
        extRouting["Cloudflare Email Routing"]:::external
        extSES["AWS SES"]:::external
        extOpenAI["OpenAI API"]:::external
    end

    %% Cloudflare Worker Layer
    subgraph "Cloudflare Worker"
        cwDeployment["Cloudflare Deployment (wrangler.json)"]:::worker
        cwConfig["Configuration & Container"]:::worker
        cwEmailEndpoint["Email API Endpoint"]:::core
        cwWebInterface["Web Interface"]:::core
        llmMiddleware["LLM Middleware"]:::middleware
    end

    %% Game Logic Layer
    subgraph "Game Logic"
        %% Controllers
        subgraph "Controllers"
            ctrlEmail["Email Controller"]:::controller
            ctrlCity["CityViewController"]:::controller
            ctrlNewGame["NewGame Controller"]:::controller
            ctrlDestroy["Destroy Controller"]:::controller
            ctrlNpc["Npc Controller"]:::controller
            ctrlNpcJack["NpcJack Controller"]:::controller
            ctrlNpcMary["NpcMary Controller"]:::controller
            ctrlNpcMatt["NpcMatt Controller"]:::controller
        end

        %% Usecases
        subgraph "Usecases"
            ucCitySnapshot["CitySnapshotUsecase"]:::usecase
            ucDestroy["DestroyUsecase"]:::usecase
            ucGuide["GuideUsecase"]:::usecase
            ucTalkWithNpc["TalkWithNpcUsecase"]:::usecase
            ucInterface["Usecase Interface"]:::usecase
        end

        %% Agents & NPC Logic
        subgraph "Agents"
            agentGuide["GuideAgent"]:::agent
            agentNpc["Npc"]:::agent
            agentNpcJack["NpcJack"]:::agent
            agentNpcMary["NpcMary"]:::agent
            agentNpcMatt["NpcMatt"]:::agent
            agentPrompts["Agent Prompts"]:::agent
            agentTools["Agent Tools & Utils"]:::agent
        end

        %% Builders & Presenter
        subgraph "Builders & Presenters"
            builderEnd["EndMessageBuilder"]:::builder
            builderProgress["ProgressBuilder"]:::builder
            builderWelcome["WelcomeMessageBuilder"]:::builder
            presenterSES["SesEmailPresenter"]:::builder
        end
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        kvRepo["Cloudflare KV Repository"]:::persistence
    end

    %% Domain Entities
    subgraph "Domain Entities"
        entityCity["City"]:::domain
        entityCityEvent["CityEvent"]:::domain
        entityNpc["Npc Entity"]:::domain
    end

    %% Connections
    extUser -->|"sendsEmail"| extRouting
    extRouting -->|"routesTo"| cwDeployment
    cwDeployment --> cwConfig
    cwConfig --> cwEmailEndpoint
    cwDeployment --> cwWebInterface
    cwEmailEndpoint -->|"handlesEmail"| ctrlEmail
    cwEmailEndpoint --> llmMiddleware
    llmMiddleware -->|"queries"| extOpenAI

    ctrlEmail -->|"startsAction"| ucTalkWithNpc
    ctrlNewGame --> ucGuide
    ctrlCity --> ucCitySnapshot
    ctrlDestroy --> ucDestroy
    ctrlNpc --> ucTalkWithNpc
    ctrlNpcJack --> ucTalkWithNpc
    ctrlNpcMary --> ucTalkWithNpc
    ctrlNpcMatt --> ucTalkWithNpc

    ucTalkWithNpc -->|"interactsWith"| agentNpc
    ucGuide -->|"guidedBy"| agentGuide

    ucCitySnapshot --> kvRepo
    ucDestroy --> kvRepo
    ucGuide --> kvRepo
    ucTalkWithNpc --> kvRepo

    ucGuide -->|"formatsMessage"| builderWelcome
    ucTalkWithNpc -->|"formatsMessage"| builderProgress
    ucTalkWithNpc -->|"finalizesMessage"| builderEnd

    builderEnd --> presenterSES
    builderProgress --> presenterSES
    builderWelcome --> presenterSES

    presenterSES -->|"sendsEmail"| extSES
    extSES -->|"deliversEmail"| extUser

    agentGuide --- agentPrompts
    agentNpc --- agentPrompts
    agentNpcJack --- agentPrompts
    agentNpcMary --- agentPrompts
    agentNpcMatt --- agentPrompts

    agentGuide --- agentTools
    agentNpc --- agentTools
    agentNpcJack --- agentTools
    agentNpcMary --- agentTools
    agentNpcMatt --- agentTools

    kvRepo -->|"managesData"| entityCity
    kvRepo --> entityCityEvent
    kvRepo --> entityNpc

    %% Click Events
    click cwDeployment "https://github.com/elct9620/ggj2025/blob/main/wrangler.json"
    click cwConfig "https://github.com/elct9620/ggj2025/blob/main/src/app/config.ts"
    click cwConfig "https://github.com/elct9620/ggj2025/blob/main/src/app/container.ts"
    click cwEmailEndpoint "https://github.com/elct9620/ggj2025/blob/main/src/app/routes/email.ts"
    click cwEmailEndpoint "https://github.com/elct9620/ggj2025/blob/main/src/app/email.ts"
    click cwWebInterface "https://github.com/elct9620/ggj2025/blob/main/src/app/web.tsx"
    click llmMiddleware "https://github.com/elct9620/ggj2025/blob/main/src/app/llm/middleware.ts"
    click kvRepo "https://github.com/elct9620/ggj2025/blob/main/src/repository/KvCityRepository.ts"
    click agentGuide "https://github.com/elct9620/ggj2025/blob/main/src/agent/GuideAgent.ts"
    click agentNpc "https://github.com/elct9620/ggj2025/blob/main/src/agent/Npc.ts"
    click agentNpcJack "https://github.com/elct9620/ggj2025/blob/main/src/agent/NpcJack.ts"
    click agentNpcMary "https://github.com/elct9620/ggj2025/blob/main/src/agent/NpcMary.ts"
    click agentNpcMatt "https://github.com/elct9620/ggj2025/blob/main/src/agent/NpcMatt.ts"
    click agentPrompts "https://github.com/elct9620/ggj2025/blob/main/src/agent/prompts/guide.md"
    click agentPrompts "https://github.com/elct9620/ggj2025/blob/main/src/agent/prompts/jack.md"
    click agentPrompts "https://github.com/elct9620/ggj2025/blob/main/src/agent/prompts/mary.md"
    click agentPrompts "https://github.com/elct9620/ggj2025/blob/main/src/agent/prompts/matt.md"
    click agentTools "https://github.com/elct9620/ggj2025/blob/main/src/agent/tools/Favorability.ts"
    click agentTools "https://github.com/elct9620/ggj2025/blob/main/src/agent/tools/Skill.ts"
    click agentTools "https://github.com/elct9620/ggj2025/blob/main/src/agent/tools/Valve.ts"
    click agentTools "https://github.com/elct9620/ggj2025/blob/main/src/agent/utils.ts"
    click ctrlEmail "https://github.com/elct9620/ggj2025/blob/main/src/controller/EmailController.ts"
    click ctrlCity "https://github.com/elct9620/ggj2025/blob/main/src/controller/CityViewController.tsx"
    click ctrlNewGame "https://github.com/elct9620/ggj2025/blob/main/src/controller/NewGameController.ts"
    click ctrlDestroy "https://github.com/elct9620/ggj2025/blob/main/src/controller/DestroyController.ts"
    click ctrlNpc "https://github.com/elct9620/ggj2025/blob/main/src/controller/NpcController.ts"
    click ctrlNpcJack "https://github.com/elct9620/ggj2025/blob/main/src/controller/NpcJackController.ts"
    click ctrlNpcMary "https://github.com/elct9620/ggj2025/blob/main/src/controller/NpcMaryController.ts"
    click ctrlNpcMatt "https://github.com/elct9620/ggj2025/blob/main/src/controller/NpcMattController.ts"
    click ucCitySnapshot "https://github.com/elct9620/ggj2025/blob/main/src/usecase/CitySnapshotUsecase.ts"
    click ucDestroy "https://github.com/elct9620/ggj2025/blob/main/src/usecase/DestroyUsecase.ts"
    click ucGuide "https://github.com/elct9620/ggj2025/blob/main/src/usecase/GuideUsecase.ts"
    click ucTalkWithNpc "https://github.com/elct9620/ggj2025/blob/main/src/usecase/TalkWithNpcUsecase.ts"
    click ucInterface "https://github.com/elct9620/ggj2025/blob/main/src/usecase/interface.ts"
    click builderEnd "https://github.com/elct9620/ggj2025/blob/main/src/builder/EndMessageBuilder.ts"
    click builderProgress "https://github.com/elct9620/ggj2025/blob/main/src/builder/ProgressBuilder.ts"
    click builderWelcome "https://github.com/elct9620/ggj2025/blob/main/src/builder/WelcomeMessageBuilder.ts"
    click builderEnd "https://github.com/elct9620/ggj2025/blob/main/src/builder/text/end.txt"
    click builderWelcome "https://github.com/elct9620/ggj2025/blob/main/src/builder/text/welcome.txt"
    click presenterSES "https://github.com/elct9620/ggj2025/blob/main/src/presenter/SesEmailPresenter.ts"
    click entityCity "https://github.com/elct9620/ggj2025/blob/main/src/entity/City.ts"
    click entityCityEvent "https://github.com/elct9620/ggj2025/blob/main/src/entity/CityEvent.ts"
    click entityNpc "https://github.com/elct9620/ggj2025/blob/main/src/entity/Npc.ts"

    %% Styles
    classDef external fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef worker fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef core fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef middleware fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef controller fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef usecase fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef agent fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
    classDef builder fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef persistence fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef domain fill:#f8d7da,stroke:#721c24,stroke-width:2px;

    class extUser,extRouting,extSES,extOpenAI external;
    class cwDeployment,cwConfig worker;
    class cwEmailEndpoint,cwWebInterface core;
    class llmMiddleware middleware;
    class ctrlEmail,ctrlCity,ctrlNewGame,ctrlDestroy,ctrlNpc,ctrlNpcJack,ctrlNpcMary,ctrlNpcMatt controller;
    class ucCitySnapshot,ucDestroy,ucGuide,ucTalkWithNpc,ucInterface usecase;
    class agent,agentPrompts,agentTools agent;
    class builderEnd,builderProgress,builderWelcome,presenterSES builder;
    class kvRepo persistence;
    class entityCity,entityCityEvent,entityNpc domain;
```
