# harshagw/kahani architecture

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

- Interactive diagram: https://gitdiagram.com/harshagw/kahani
- Repository: https://github.com/harshagw/kahani

## Overview

Kahani World turns a player’s scene description into an AI-generated, explorable adventure: sign in, create a story bible, generate a connected world and character, explore and talk with clue-bearing NPCs, then reach a generated ending. The README identifies World as the client orchestrator for parallel scene prefetch, clues, finale, and persistence; sampled routes confirm the generation calls and server-side game listing/creation. Some client and storage wiring is documented but not present in the sampled source, so the graph omits uncertain call details.

Main entry points: [`components/World.tsx`](https://github.com/harshagw/kahani/blob/main/components/World.tsx) (World orchestrator), [`lib/world-engine.ts`](https://github.com/harshagw/kahani/blob/main/lib/world-engine.ts) (World engine), [`lib/supabase/auth.ts`](https://github.com/harshagw/kahani/blob/main/lib/supabase/auth.ts) (Session validation), [`app/api/screen/route.ts`](https://github.com/harshagw/kahani/blob/main/app/api/screen/route.ts) (Overworld scenes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Player experience"]
  node_home["World gallery<br/>[Home.tsx]"]
  node_login["Sign-in<br/>[page.tsx]"]
  node_world["World orchestrator<br/>[World.tsx]"]
  node_canvas["Movement and map<br/>[GameCanvas.tsx]"]
  node_dialogue["NPC conversations<br/>[DialogueBox.tsx]"]
end

subgraph group_generation["World generation"]
  node_universe["Story bible<br/>[route.ts]"]
  node_screen["Overworld scenes<br/>[route.ts]"]
  node_interior["Interior scenes<br/>[route.ts]"]
  node_sprite["Player sprite<br/>[route.ts]"]
  node_dialogueapi["Dialogue generation<br/>[route.ts]"]
  node_voiceapi["Voice generation<br/>[route.ts]"]
  node_finale["Finale generation<br/>[route.ts]"]
  node_engine["World engine<br/>[world-engine.ts]"]
end

subgraph group_services["Identity and persistence"]
  node_auth["Session validation<br/>[auth.ts]"]
  node_supabaseclient["Supabase clients<br/>[server.ts]"]
  node_gamehelpers["Game persistence helpers<br/>[games.ts]"]
end

subgraph group_api["Application API"]
  node_gamesapi["Saved worlds API<br/>[route.ts]"]
  node_callback["Auth callback<br/>[route.ts]"]
  node_profileapi["Profile API<br/>[route.ts]"]
end

node_player(("Player"))
node_gemini["Text and image generation"]
node_sarvam["Speech synthesis"]
node_supabase[("Supabase database and storage")]

node_player -->|"signs in"| node_login
node_login -->|"completes sign-in"| node_callback
node_player -->|"describes world"| node_home
node_home -->|"requests bible"| node_universe
node_universe -->|"checks session"| node_auth
node_universe -->|"generates bible"| node_engine
node_engine -->|"generates text and images"| node_gemini
node_home -->|"creates or lists worlds"| node_gamesapi
node_gamesapi -->|"checks session"| node_auth
node_gamesapi -->|"creates client"| node_supabaseclient
node_gamesapi -->|"checks quota and formats"| node_gamehelpers
node_gamehelpers -->|"reads and writes game assets"| node_supabase
node_supabaseclient -->|"accesses database"| node_supabase
node_player -->|"plays saved world"| node_world
node_world -->|"requests scenes"| node_screen
node_world -->|"prefetches rooms"| node_interior
node_world -->|"requests sprite"| node_sprite
node_world -->|"provides playable scene"| node_canvas
node_canvas -->|"reports exploration"| node_world
node_world -->|"opens NPC conversation"| node_dialogue
node_dialogue -->|"submits conversation"| node_dialogueapi
node_dialogueapi -->|"checks session"| node_auth
node_dialogueapi -->|"generates reply"| node_engine
node_world -->|"requests spoken lines"| node_voiceapi
node_voiceapi -->|"checks session"| node_auth
node_voiceapi -->|"synthesizes speech"| node_engine
node_engine -->|"synthesizes voice"| node_sarvam
node_world -->|"requests ending"| node_finale
node_finale -->|"checks session"| node_auth
node_finale -->|"generates finale"| node_engine
node_screen -->|"checks session"| node_auth
node_screen -->|"generates screen"| node_engine
node_screen -->|"fetches saved frame"| node_gamehelpers
node_interior -->|"checks session"| node_auth
node_interior -->|"generates interior"| node_engine
node_sprite -->|"checks session"| node_auth
node_sprite -->|"generates sprite"| node_engine
node_sprite -->|"fetches reference frame"| node_gamehelpers
node_callback -->|"exchanges session"| node_supabaseclient
node_profileapi -->|"checks session"| node_auth

click node_home "https://github.com/harshagw/kahani/blob/main/components/Home.tsx"
click node_login "https://github.com/harshagw/kahani/blob/main/app/login/page.tsx"
click node_world "https://github.com/harshagw/kahani/blob/main/components/World.tsx"
click node_canvas "https://github.com/harshagw/kahani/blob/main/components/GameCanvas.tsx"
click node_dialogue "https://github.com/harshagw/kahani/blob/main/components/DialogueBox.tsx"
click node_universe "https://github.com/harshagw/kahani/blob/main/app/api/universe/route.ts"
click node_screen "https://github.com/harshagw/kahani/blob/main/app/api/screen/route.ts"
click node_interior "https://github.com/harshagw/kahani/blob/main/app/api/scene/route.ts"
click node_sprite "https://github.com/harshagw/kahani/blob/main/app/api/sprite/route.ts"
click node_dialogueapi "https://github.com/harshagw/kahani/blob/main/app/api/dialogue/route.ts"
click node_voiceapi "https://github.com/harshagw/kahani/blob/main/app/api/voice/route.ts"
click node_finale "https://github.com/harshagw/kahani/blob/main/app/api/finale/route.ts"
click node_engine "https://github.com/harshagw/kahani/blob/main/lib/world-engine.ts"
click node_auth "https://github.com/harshagw/kahani/blob/main/lib/supabase/auth.ts"
click node_supabaseclient "https://github.com/harshagw/kahani/blob/main/lib/supabase/server.ts"
click node_gamesapi "https://github.com/harshagw/kahani/blob/main/app/api/games/route.ts"
click node_gamehelpers "https://github.com/harshagw/kahani/blob/main/lib/games.ts"
click node_callback "https://github.com/harshagw/kahani/blob/main/app/auth/callback/route.ts"
click node_profileapi "https://github.com/harshagw/kahani/blob/main/app/api/profile/route.ts"

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_home,node_login,node_world,node_canvas,node_dialogue toneBlue
class node_universe,node_screen,node_interior,node_sprite,node_dialogueapi,node_voiceapi,node_finale,node_engine,node_supabase toneAmber
class node_auth,node_supabaseclient,node_gamehelpers toneMint
class node_gamesapi,node_callback,node_profileapi toneRose
class node_player,node_gemini,node_sarvam toneIndigo
```

## Components

### Player experience

- [World gallery](https://github.com/harshagw/kahani/blob/main/components/Home.tsx): `components/Home.tsx`
- [Sign-in](https://github.com/harshagw/kahani/blob/main/app/login/page.tsx): `app/login/page.tsx`
- [World orchestrator](https://github.com/harshagw/kahani/blob/main/components/World.tsx): `components/World.tsx`
- [Movement and map](https://github.com/harshagw/kahani/blob/main/components/GameCanvas.tsx): `components/GameCanvas.tsx`
- [NPC conversations](https://github.com/harshagw/kahani/blob/main/components/DialogueBox.tsx): `components/DialogueBox.tsx`

### World generation

- [Story bible](https://github.com/harshagw/kahani/blob/main/app/api/universe/route.ts): `app/api/universe/route.ts`
- [Overworld scenes](https://github.com/harshagw/kahani/blob/main/app/api/screen/route.ts): `app/api/screen/route.ts`
- [Interior scenes](https://github.com/harshagw/kahani/blob/main/app/api/scene/route.ts): `app/api/scene/route.ts`
- [Player sprite](https://github.com/harshagw/kahani/blob/main/app/api/sprite/route.ts): `app/api/sprite/route.ts`
- [Dialogue generation](https://github.com/harshagw/kahani/blob/main/app/api/dialogue/route.ts): `app/api/dialogue/route.ts`
- [Voice generation](https://github.com/harshagw/kahani/blob/main/app/api/voice/route.ts): `app/api/voice/route.ts`
- [Finale generation](https://github.com/harshagw/kahani/blob/main/app/api/finale/route.ts): `app/api/finale/route.ts`
- [World engine](https://github.com/harshagw/kahani/blob/main/lib/world-engine.ts): `lib/world-engine.ts`

### Identity and persistence

- [Session validation](https://github.com/harshagw/kahani/blob/main/lib/supabase/auth.ts): `lib/supabase/auth.ts`
- [Supabase clients](https://github.com/harshagw/kahani/blob/main/lib/supabase/server.ts): `lib/supabase/server.ts`
- [Game persistence helpers](https://github.com/harshagw/kahani/blob/main/lib/games.ts): `lib/games.ts`

### Application API

- [Saved worlds API](https://github.com/harshagw/kahani/blob/main/app/api/games/route.ts): `app/api/games/route.ts`
- [Auth callback](https://github.com/harshagw/kahani/blob/main/app/auth/callback/route.ts): `app/auth/callback/route.ts`
- [Profile API](https://github.com/harshagw/kahani/blob/main/app/api/profile/route.ts): `app/api/profile/route.ts`

### Other components

- **Player**
- **Text and image generation**
- **Speech synthesis**
- **Supabase database and storage**

## Connections

- Player → Sign-in: signs in
- Sign-in → Auth callback: completes sign-in
- Player → World gallery: describes world
- World gallery → Story bible: requests bible
- Story bible → Session validation: checks session
- Story bible → World engine: generates bible
- World engine → Text and image generation: generates text and images
- World gallery → Saved worlds API: creates or lists worlds
- Saved worlds API → Session validation: checks session
- Saved worlds API → Supabase clients: creates client
- Saved worlds API → Game persistence helpers: checks quota and formats
- Game persistence helpers → Supabase database and storage: reads and writes game assets
- Supabase clients → Supabase database and storage: accesses database
- Player → World orchestrator: plays saved world
- World orchestrator → Overworld scenes: requests scenes
- World orchestrator → Interior scenes: prefetches rooms
- World orchestrator → Player sprite: requests sprite
- World orchestrator → Movement and map: provides playable scene
- Movement and map → World orchestrator: reports exploration
- World orchestrator → NPC conversations: opens NPC conversation
- NPC conversations → Dialogue generation: submits conversation
- Dialogue generation → Session validation: checks session
- Dialogue generation → World engine: generates reply
- World orchestrator → Voice generation: requests spoken lines
- Voice generation → Session validation: checks session
- Voice generation → World engine: synthesizes speech
- World engine → Speech synthesis: synthesizes voice
- World orchestrator → Finale generation: requests ending
- Finale generation → Session validation: checks session
- Finale generation → World engine: generates finale
- Overworld scenes → Session validation: checks session
- Overworld scenes → World engine: generates screen
- Overworld scenes → Game persistence helpers: fetches saved frame
- Interior scenes → Session validation: checks session
- Interior scenes → World engine: generates interior
- Player sprite → Session validation: checks session
- Player sprite → World engine: generates sprite
- Player sprite → Game persistence helpers: fetches reference frame
- Auth callback → Supabase clients: exchanges session
- Profile API → Session validation: checks session