# caoban123/aistoryadventure architecture

> Architecture diagram of the GitHub repository caoban123/aistoryadventure, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/caoban123/aistoryadventure
- Repository: https://github.com/caoban123/aistoryadventure

## Overview

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: [`app/services/story_service.py`](https://github.com/caoban123/aistoryadventure/blob/main/app/services/story_service.py) (Story service), [`app/services/readiness.py`](https://github.com/caoban123/aistoryadventure/blob/main/app/services/readiness.py) (Readiness), [`app/memory/memory_service.py`](https://github.com/caoban123/aistoryadventure/blob/main/app/memory/memory_service.py) (Memory service), [`frontend/index.html`](https://github.com/caoban123/aistoryadventure/blob/main/frontend/index.html) (Browser UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser_client["Browser UI<br/>static client<br/>[index.html]"]
  node_admin_ui["Admin UI<br/>static admin<br/>[admin.html]"]
  node_frontend_config["Client config<br/>runtime config<br/>[config.js]"]
end

subgraph group_backend["Backend API"]
  node_entrypoint["App entry<br/>API bootstrap<br/>[main.py]"]
  node_story_routes["Story routes<br/>HTTP routes<br/>[story_routes.py]"]
  node_admin_routes["Admin routes<br/>HTTP routes<br/>[admin_routes.py]"]
  node_story_service{{"Story service<br/>orchestrator<br/>[story_service.py]"}}
  node_admin_service["Admin service<br/>admin logic<br/>[admin_service.py]"]
  node_readiness["Readiness<br/>health checks<br/>[readiness.py]"]
  node_token_usage["Token usage<br/>usage tracking"]
  node_firebase_auth["Firebase auth<br/>auth adapter<br/>[firebase_auth.py]"]
  node_ai_provider{{"AI provider<br/>llm abstraction<br/>[provider.py]"}}
  node_ai_prompt["Prompt builder<br/>prompting<br/>[prompt.py]"]
  node_ai_parser["Output parser<br/>response parsing<br/>[output_parser.py]"]
  node_memory_service{{"Memory service<br/>memory orchestration<br/>[memory_service.py]"}}
  node_firebase_store[("Firebase store<br/>persistent store<br/>[firebase_store.py]")]
  node_vector_store[("Vector memory<br/>semantic store<br/>[vector_store.py]")]
  node_domain_models["Domain models<br/>data model<br/>[models.py]"]
  node_domain_schemas["API schemas<br/>contracts<br/>[schemas.py]"]
  node_world_catalog["World catalog<br/>world data<br/>[world_catalog.py]"]
end

subgraph group_ops["Deployment & Ops"]
  node_deploy_packaging["Deploy assets<br/>deployment<br/>[README.md]"]
  node_ops_scripts["Ops scripts<br/>maintenance tools<br/>[backup_local.py]"]
end

node_browser_client -->|"loads config"| node_frontend_config
node_browser_client -->|"calls API"| node_story_routes
node_admin_ui -->|"loads config"| node_frontend_config
node_admin_ui -->|"calls API"| node_admin_routes
node_entrypoint -->|"mounts"| node_story_routes
node_entrypoint -->|"mounts"| node_admin_routes
node_story_routes -->|"delegates"| node_story_service
node_admin_routes -->|"delegates"| node_admin_service
node_story_service -->|"authenticates"| node_firebase_auth
node_story_service -->|"reads/writes"| node_memory_service
node_story_service -->|"builds prompt"| node_ai_prompt
node_story_service -->|"generates text"| node_ai_provider
node_story_service -->|"parses output"| node_ai_parser
node_story_service -->|"shapes payloads"| node_domain_schemas
node_story_service -->|"uses models"| node_domain_models
node_story_service -->|"resolves world"| node_world_catalog
node_memory_service -->|"persists state"| node_firebase_store
node_memory_service -->|"retrieves context"| node_vector_store
node_admin_service -->|"checks claims"| node_firebase_auth
node_readiness -->|"checks dependency"| node_firebase_store
node_readiness -->|"checks dependency"| node_ai_provider
node_readiness -->|"checks dependency"| node_vector_store
node_deploy_packaging -->|"runs backend"| node_entrypoint
node_deploy_packaging -->|"serves frontend"| node_browser_client
node_ops_scripts -->|"backup/restore"| node_firebase_store
node_ops_scripts -->|"admin setup"| node_firebase_auth

click node_browser_client "https://github.com/caoban123/aistoryadventure/blob/main/frontend/index.html"
click node_admin_ui "https://github.com/caoban123/aistoryadventure/blob/main/frontend/admin.html"
click node_frontend_config "https://github.com/caoban123/aistoryadventure/blob/main/frontend/config.js"
click node_entrypoint "https://github.com/caoban123/aistoryadventure/blob/main/app/main.py"
click node_story_routes "https://github.com/caoban123/aistoryadventure/blob/main/app/api/story_routes.py"
click node_admin_routes "https://github.com/caoban123/aistoryadventure/blob/main/app/api/admin_routes.py"
click node_story_service "https://github.com/caoban123/aistoryadventure/blob/main/app/services/story_service.py"
click node_admin_service "https://github.com/caoban123/aistoryadventure/blob/main/app/services/admin_service.py"
click node_readiness "https://github.com/caoban123/aistoryadventure/blob/main/app/services/readiness.py"
click node_token_usage "https://github.com/caoban123/aistoryadventure/blob/main/app/services/app/services/token_usage_service.py"
click node_firebase_auth "https://github.com/caoban123/aistoryadventure/blob/main/app/auth/firebase_auth.py"
click node_ai_provider "https://github.com/caoban123/aistoryadventure/blob/main/app/ai/provider.py"
click node_ai_prompt "https://github.com/caoban123/aistoryadventure/blob/main/app/ai/prompt.py"
click node_ai_parser "https://github.com/caoban123/aistoryadventure/blob/main/app/ai/output_parser.py"
click node_memory_service "https://github.com/caoban123/aistoryadventure/blob/main/app/memory/memory_service.py"
click node_firebase_store "https://github.com/caoban123/aistoryadventure/blob/main/app/memory/firebase_store.py"
click node_vector_store "https://github.com/caoban123/aistoryadventure/blob/main/app/memory/vector_store.py"
click node_domain_models "https://github.com/caoban123/aistoryadventure/blob/main/app/domain/models.py"
click node_domain_schemas "https://github.com/caoban123/aistoryadventure/blob/main/app/domain/schemas.py"
click node_world_catalog "https://github.com/caoban123/aistoryadventure/blob/main/app/domain/world_catalog.py"
click node_deploy_packaging "https://github.com/caoban123/aistoryadventure/blob/main/deploy/README.md"
click node_ops_scripts "https://github.com/caoban123/aistoryadventure/blob/main/scripts/backup_local.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser_client,node_admin_ui,node_frontend_config toneBlue
class node_entrypoint,node_story_routes,node_admin_routes,node_story_service,node_admin_service,node_readiness,node_token_usage,node_firebase_auth,node_ai_provider,node_ai_prompt,node_ai_parser,node_memory_service,node_firebase_store,node_vector_store,node_domain_models,node_domain_schemas,node_world_catalog toneAmber
class node_deploy_packaging,node_ops_scripts toneMint
```

## Components

### Frontend

Static browser client and admin UI

- [Browser UI](https://github.com/caoban123/aistoryadventure/blob/main/frontend/index.html): static client · Player-facing browser interface that talks to the API · `frontend/index.html`
- [Admin UI](https://github.com/caoban123/aistoryadventure/blob/main/frontend/admin.html): static admin · Separate browser interface for privileged operations · `frontend/admin.html`
- [Client config](https://github.com/caoban123/aistoryadventure/blob/main/frontend/config.js): runtime config · Browser-side API base URL and environment wiring · `frontend/config.js`

### Backend API

FastAPI application, services, auth, AI, and persistence

- [App entry](https://github.com/caoban123/aistoryadventure/blob/main/app/main.py): API bootstrap · Backend application startup and FastAPI mounting · `app/main.py`
- [Story routes](https://github.com/caoban123/aistoryadventure/blob/main/app/api/story_routes.py): HTTP routes · Gameplay endpoints for sessions, turns, worlds, and status · `app/api/story_routes.py`
- [Admin routes](https://github.com/caoban123/aistoryadventure/blob/main/app/api/admin_routes.py): HTTP routes · Privileged endpoints for administrative actions · `app/api/admin_routes.py`
- [Story service](https://github.com/caoban123/aistoryadventure/blob/main/app/services/story_service.py): orchestrator · Coordinates game flow across auth, memory, AI, and persistence · `app/services/story_service.py`
- [Admin service](https://github.com/caoban123/aistoryadventure/blob/main/app/services/admin_service.py): admin logic · Handles privileged backend operations and identity lookup · `app/services/admin_service.py`
- [Readiness](https://github.com/caoban123/aistoryadventure/blob/main/app/services/readiness.py): health checks · Dependency and production readiness checks · `app/services/readiness.py`
- [Token usage](https://github.com/caoban123/aistoryadventure/blob/main/app/services/app/services/token_usage_service.py): usage tracking · Token accounting and usage limits support · `app/services/app/services/token_usage_service.py`
- [Firebase auth](https://github.com/caoban123/aistoryadventure/blob/main/app/auth/firebase_auth.py): auth adapter · Verifies user identity and admin claims · `app/auth/firebase_auth.py`
- [AI provider](https://github.com/caoban123/aistoryadventure/blob/main/app/ai/provider.py): llm abstraction · Pluggable text generation providers and local mock · `app/ai/provider.py`
- [Prompt builder](https://github.com/caoban123/aistoryadventure/blob/main/app/ai/prompt.py): prompting · Builds story prompts for model calls · `app/ai/prompt.py`
- [Output parser](https://github.com/caoban123/aistoryadventure/blob/main/app/ai/output_parser.py): response parsing · Converts model output into structured story data · `app/ai/output_parser.py`
- [Memory service](https://github.com/caoban123/aistoryadventure/blob/main/app/memory/memory_service.py): memory orchestration · Coordinates durable state and contextual retrieval · `app/memory/memory_service.py`
- [Firebase store](https://github.com/caoban123/aistoryadventure/blob/main/app/memory/firebase_store.py): persistent store · Primary durable storage for sessions and application state · `app/memory/firebase_store.py`
- [Vector memory](https://github.com/caoban123/aistoryadventure/blob/main/app/memory/vector_store.py): semantic store · Chroma-style semantic retrieval for story context · `app/memory/vector_store.py`
- [Domain models](https://github.com/caoban123/aistoryadventure/blob/main/app/domain/models.py): data model · Canonical internal entities and contracts · `app/domain/models.py`
- [API schemas](https://github.com/caoban123/aistoryadventure/blob/main/app/domain/schemas.py): contracts · Request and response payload definitions · `app/domain/schemas.py`
- [World catalog](https://github.com/caoban123/aistoryadventure/blob/main/app/domain/world_catalog.py): world data · Predefined worlds exposed to the player · `app/domain/world_catalog.py`

### Deployment & Ops

Runtime packaging, deployment, and maintenance tooling

- [Deploy assets](https://github.com/caoban123/aistoryadventure/blob/main/deploy/README.md): deployment · Caddy, Coolify, and systemd packaging for production · `deploy/README.md`
- [Ops scripts](https://github.com/caoban123/aistoryadventure/blob/main/scripts/backup_local.py): maintenance tools · Backup, restore, and admin-claim helper scripts · `scripts/backup_local.py`

## Connections

- 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
