How elct9620/ggj2025 works
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).