How desmondchoy/adventures works
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.