How caoban123/aistoryadventure works
1. Overall shape
- This is a two-part application: a Python backend API and a static browser frontend.
- The backend is the system of record for game state, auth, AI calls, memory, admin functions, and readiness checks.
- The frontend is a thin client that loads configuration from frontend/config.js and talks to the backend over HTTP.
2. Backend entrypoint and API boundary
- app/main.py is the backend entrypoint, likely mounting a FastAPI app.
- Public API routes are split into app/api/story_routes.py for gameplay and app/api/admin_routes.py for administrative operations.
- The documented API surface includes session/game operations, world listing, status, and admin identity lookup.
3. Game orchestration layer
- app/services/story_service.py appears to be the central orchestrator for game flow.
- It likely handles start and turn requests by combining player input, current session state, world context, memory retrieval, and AI generation.
- This is the main business-logic boundary between HTTP requests and the AI/persistence subsystems.
4. AI generation subsystem
- app/ai/provider.py abstracts text generation providers: OpenAI, Gemini, Ollama, and a mock provider for local testing.
- app/ai/prompt.py builds the prompts used to steer story generation.
- app/ai/output_parser.py turns model output back into structured data the service layer can use.
- The provider choice is environment-driven, so the AI backend is a replaceable dependency rather than a fixed implementation.
5. Persistence and memory
- app/memory/firebase_store.py and app/memory/memory_service.py suggest durable storage for sessions, turns, or user-related state in Firebase-backed storage.
- app/memory/vector_store.py adds semantic memory via ChromaDB-style vector storage, used to retrieve relevant story context.
- The repo explicitly supports a fallback local store when Firebase is unavailable, which affects deployment and local development architecture.
6. Domain model and world data
- app/domain/models.py and app/domain/schemas.py define the canonical shapes for game entities, API payloads, and internal data contracts.
- app/domain/world_catalog.py likely provides the predefined “worlds” exposed by GET /game/worlds.
- This domain layer is the shared contract between routes, services, storage, and frontend expectations.
7. Authentication and admin boundary
- app/auth/firebase_auth.py integrates Firebase authentication.
- The app supports admin controls, with app/services/admin_service.py and /admin routes handling privileged operations.
- The frontend includes a dedicated admin UI at frontend/admin.html, separate from the player experience.
8. Usage, limits, and readiness
- app/services/app/services/token_usage_service.py and related service code imply token accounting and rate-limit tracking.
- app/services/readiness.py powers the /status endpoint and the production readiness check mentioned in the README.
- Operationally, the system distinguishes between “app is running” and “all dependencies are ready,” which matters for deployment and health monitoring.
9. Frontend structure
- The player UI is in frontend/index.html, frontend/app.js, and frontend/style.css.
- The admin UI is separate in frontend/admin.html, frontend/admin.js, and frontend/admin.css.
- The frontend is static and can be served by any simple HTTP server or production web server; it does not appear to have its own build system.
10. Configuration and environment boundaries
- Backend config comes from environment variables in app/config.py, including provider choice, Firebase credentials, and production mode.
- Frontend config is a runtime JS file (frontend/config.js / production example) that sets the API base URL.
- This split means backend secrets stay server-side, while the browser only receives non-secret endpoint configuration.
11. Deployment topology
- The deploy/ directory shows multiple production options: Caddy reverse proxy, Coolify containers, and systemd services.
- deploy/frontend/ contains production frontend packaging, while deploy/coolify/ and deploy/systemd/ cover backend and backup services.
- The deployment design suggests a backend API behind a web server/reverse proxy, with the frontend served as static assets.
12. Operational tooling
- scripts/backup_local.py, scripts/restore_local.py, and scripts/set_admin_claim.py support local recovery and Firebase admin setup.
- BACKUP_RESTORE.md, DEPLOYMENT.md, and PRODUCTION_READINESS.md document operational workflows rather than app logic.
- These tools indicate the repo treats persistence and admin configuration as first-class operational concerns.
13. How data flows through the system
- A browser request enters the frontend, which calls the backend API.
- The backend authenticates the user via Firebase, resolves session and world context, retrieves relevant memory, generates text through the selected AI provider, parses the result, stores updated state, and returns the next story state to the client.
- Admin requests follow a similar path but are gated by Firebase admin claims and handled through the admin service layer.
14. Key architectural takeaway
- The architecture is a clean separation of presentation (static frontend), API/application services (FastAPI), AI abstraction, memory/persistence, and deployment/ops.
- For an architecture diagram, the most important boundaries are the browser-to-API boundary, the auth boundary via Firebase, the AI provider boundary, and the persistence boundary split between Firebase storage and vector memory.
Main entry points: story_service.py Story service · readiness.py Readiness · memory_service.py Memory service · index.html Browser UI
Components 22
Frontend
Static browser client and admin UI
- Browser UI · Player-facing browser interface that talks to the API
frontend/index.html - Admin UI · Separate browser interface for privileged operations
frontend/admin.html - Client config · Browser-side API base URL and environment wiring
frontend/config.js
Backend API
FastAPI application, services, auth, AI, and persistence
- App entry · Backend application startup and FastAPI mounting
app/main.py - Story routes · Gameplay endpoints for sessions, turns, worlds, and status
app/api/story_routes.py - Admin routes · Privileged endpoints for administrative actions
app/api/admin_routes.py - Story service · Coordinates game flow across auth, memory, AI, and persistence
app/services/story_service.py - Admin service · Handles privileged backend operations and identity lookup
app/services/admin_service.py - Readiness · Dependency and production readiness checks
app/services/readiness.py - Token usage · Token accounting and usage limits support
app/services/app/services/token_usage_service.py - Firebase auth · Verifies user identity and admin claims
app/auth/firebase_auth.py - AI provider · Pluggable text generation providers and local mock
app/ai/provider.py - Prompt builder · Builds story prompts for model calls
app/ai/prompt.py - Output parser · Converts model output into structured story data
app/ai/output_parser.py - Memory service · Coordinates durable state and contextual retrieval
app/memory/memory_service.py - Firebase store · Primary durable storage for sessions and application state
app/memory/firebase_store.py - Vector memory · Chroma-style semantic retrieval for story context
app/memory/vector_store.py - Domain models · Canonical internal entities and contracts
app/domain/models.py - API schemas · Request and response payload definitions
app/domain/schemas.py - World catalog · Predefined worlds exposed to the player
app/domain/world_catalog.py
Deployment & Ops
Runtime packaging, deployment, and maintenance tooling
- Deploy assets · Caddy, Coolify, and systemd packaging for production
deploy/README.md - Ops scripts · Backup, restore, and admin-claim helper scripts
scripts/backup_local.py
Connections 26
- Browser UI → Client config: loads config · Browser UI reads runtime API settings
- Browser UI → Story routes: calls API · Player interactions go to gameplay endpoints
- Admin UI → Client config: loads config · Admin UI also uses runtime API settings
- Admin UI → Admin routes: calls API · Admin actions go to privileged endpoints
- App entry → Story routes: mounts · Application bootstrap registers gameplay routes
- App entry → Admin routes: mounts · Application bootstrap registers admin routes
- Story routes → Story service: delegates · HTTP gameplay requests are handled by the service layer
- Admin routes → Admin service: delegates · Admin HTTP requests are handled by admin logic
- Story service → Firebase auth: authenticates · Service checks user identity and claims
- Story service → Memory service: reads/writes · Service loads and persists session and context state
- Story service → Prompt builder: builds prompt · Service assembles model instructions and context
- Story service → AI provider: generates text · Service invokes the selected LLM provider
- Story service → Output parser: parses output · Service converts model output into structured game state
- Story service → API schemas: shapes payloads · Service uses API contract definitions for requests and responses
- Story service → Domain models: uses models · Service works with canonical game entities
- Story service → World catalog: resolves world · Service looks up available worlds and settings
- Memory service → Firebase store: persists state · Durable session and turn data live in Firebase-backed storage
- Memory service → Vector memory: retrieves context · Semantic memory is queried for relevant story context
- Admin service → Firebase auth: checks claims · Admin operations are gated by Firebase identity metadata
- Readiness → Firebase store: checks dependency · Readiness verifies primary persistence availability
- Readiness → AI provider: checks dependency · Readiness verifies model backend availability
- Readiness → Vector memory: checks dependency · Readiness verifies semantic memory availability
- Deploy assets → App entry: runs backend · Deployment artifacts start the API service
- Deploy assets → Browser UI: serves frontend · Production packaging hosts static client assets
- Ops scripts → Firebase store: backup/restore · Operational scripts manage durable application data
- Ops scripts → Firebase auth: admin setup · Scripts can provision admin claims