# svtrhub/karsa_demo architecture

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

- Interactive diagram: https://gitdiagram.com/svtrhub/karsa_demo
- Repository: https://github.com/svtrhub/karsa_demo

## Overview

Karsa is a student-development demo: a student completes profile onboarding, tours the workspace, chooses a specialist persona, and receives profile-aware streamed chat guidance. The page composes the experience; shared demo state and domain transitions support onboarding, chat, and rewards. The README also lists rate limiting and CORS validation, and planned competition, portfolio, coin-ledger, and room-customization features. Those planned features appear as locked “coming soon” UI, not implemented product subsystems. Some component wiring is supported only by the source index; unsampled internals are not inferred.

Main entry points: [`src/app/page.tsx`](https://github.com/svtrhub/karsa_demo/blob/master/src/app/page.tsx) (Application flow), [`src/context/DemoContext.tsx`](https://github.com/svtrhub/karsa_demo/blob/master/src/context/DemoContext.tsx) (Demo state), [`src/components/dashboard/RumahKarsaRoom.tsx`](https://github.com/svtrhub/karsa_demo/blob/master/src/components/dashboard/RumahKarsaRoom.tsx) (Workspace room), [`src/components/chat/ChatModal.tsx`](https://github.com/svtrhub/karsa_demo/blob/master/src/components/chat/ChatModal.tsx) (Chat interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Student experience"]
  node_home["Application flow<br/>[page.tsx]"]
  node_splash["Splash screen"]
  node_onboarding["Profile onboarding<br/>[OnboardingFlow.tsx]"]
  node_ftux["First-use tour<br/>[FTUXSequence.tsx]"]
  node_room["Workspace room<br/>[RumahKarsaRoom.tsx]"]
  node_camera["Room camera"]
  node_sprite["Character sprites"]
  node_sidebar["Persona navigation<br/>[Sidebar.tsx]"]
  node_topbar["Workspace controls<br/>[TopBar.tsx]"]
  node_command["Command center"]
  node_chat["Chat interface<br/>[ChatModal.tsx]"]
  node_future["Planned features"]
end

subgraph group_state["Profile and state"]
  node_context["Demo state<br/>[DemoContext.tsx]"]
  node_domain["State transitions<br/>[domainEngine.ts]"]
  node_browser[("Browser storage")]
end

subgraph group_guidance["Persona guidance"]
  node_persona["Persona prompts<br/>[personas.ts]"]
end

subgraph group_service["Chat service"]
  node_streamhook["Chat stream hook<br/>[useChatStream.ts]"]
  node_route["Chat API route<br/>[route.ts]"]
  node_limiter["Rate limiter<br/>[rateLimit.ts]"]
  node_llm["LLM streaming<br/>[llm.ts]"]
end

node_student(("Student"))
node_gemini["Google Gemini"]

node_student -->|"opens app"| node_home
node_home -->|"renders"| node_splash
node_home -->|"renders"| node_onboarding
node_home -->|"renders"| node_ftux
node_home -->|"renders"| node_room
node_home -->|"renders"| node_sidebar
node_home -->|"renders"| node_topbar
node_home -->|"renders"| node_command
node_home -->|"renders"| node_chat
node_home -->|"renders"| node_future
node_home -->|"reads state"| node_context
node_onboarding -.->|"updates profile"| node_context
node_sidebar -->|"opens persona chat"| node_context
node_room -->|"uses camera"| node_camera
node_room -->|"renders characters"| node_sprite
node_chat -->|"reads and updates chat"| node_context
node_context -->|"delegates transitions"| node_domain
node_context -->|"persists state"| node_browser
node_chat -->|"sends messages"| node_streamhook
node_streamhook -->|"posts chat"| node_route
node_route -->|"checks limits"| node_limiter
node_route -->|"requests stream"| node_llm
node_llm -->|"builds prompt"| node_persona
node_llm -->|"streams response"| node_gemini

click node_home "https://github.com/svtrhub/karsa_demo/blob/master/src/app/page.tsx"
click node_splash "https://github.com/svtrhub/karsa_demo/blob/master/src/components/splash/AppSplashScreen.tsx"
click node_onboarding "https://github.com/svtrhub/karsa_demo/blob/master/src/components/onboarding/OnboardingFlow.tsx"
click node_ftux "https://github.com/svtrhub/karsa_demo/blob/master/src/components/ftux/FTUXSequence.tsx"
click node_room "https://github.com/svtrhub/karsa_demo/blob/master/src/components/dashboard/RumahKarsaRoom.tsx"
click node_camera "https://github.com/svtrhub/karsa_demo/blob/master/src/hooks/useCameraViewport.ts"
click node_sprite "https://github.com/svtrhub/karsa_demo/blob/master/src/components/dashboard/CharacterSprite.tsx"
click node_sidebar "https://github.com/svtrhub/karsa_demo/blob/master/src/components/dashboard/Sidebar.tsx"
click node_topbar "https://github.com/svtrhub/karsa_demo/blob/master/src/components/dashboard/TopBar.tsx"
click node_command "https://github.com/svtrhub/karsa_demo/blob/master/src/components/dashboard/FloatingCommandCenter.tsx"
click node_chat "https://github.com/svtrhub/karsa_demo/blob/master/src/components/chat/ChatModal.tsx"
click node_future "https://github.com/svtrhub/karsa_demo/blob/master/src/components/dashboard/ComingSoonModal.tsx"
click node_context "https://github.com/svtrhub/karsa_demo/blob/master/src/context/DemoContext.tsx"
click node_domain "https://github.com/svtrhub/karsa_demo/blob/master/src/lib/domainEngine.ts"
click node_persona "https://github.com/svtrhub/karsa_demo/blob/master/src/lib/personas.ts"
click node_streamhook "https://github.com/svtrhub/karsa_demo/blob/master/src/hooks/useChatStream.ts"
click node_route "https://github.com/svtrhub/karsa_demo/blob/master/src/app/api/chat/route.ts"
click node_limiter "https://github.com/svtrhub/karsa_demo/blob/master/src/lib/rateLimit.ts"
click node_llm "https://github.com/svtrhub/karsa_demo/blob/master/src/lib/llm.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_splash,node_onboarding,node_ftux,node_room,node_camera,node_sprite,node_sidebar,node_topbar,node_command,node_chat,node_future toneBlue
class node_context,node_domain,node_browser toneAmber
class node_persona toneMint
class node_streamhook,node_route,node_limiter,node_llm toneRose
class node_student,node_gemini toneIndigo
```

## Components

### Student experience

- [Application flow](https://github.com/svtrhub/karsa_demo/blob/master/src/app/page.tsx): `src/app/page.tsx`
- [Splash screen](https://github.com/svtrhub/karsa_demo/blob/master/src/components/splash/AppSplashScreen.tsx): `src/components/splash/AppSplashScreen.tsx`
- [Profile onboarding](https://github.com/svtrhub/karsa_demo/blob/master/src/components/onboarding/OnboardingFlow.tsx): `src/components/onboarding/OnboardingFlow.tsx`
- [First-use tour](https://github.com/svtrhub/karsa_demo/blob/master/src/components/ftux/FTUXSequence.tsx): `src/components/ftux/FTUXSequence.tsx`
- [Workspace room](https://github.com/svtrhub/karsa_demo/blob/master/src/components/dashboard/RumahKarsaRoom.tsx): `src/components/dashboard/RumahKarsaRoom.tsx`
- [Room camera](https://github.com/svtrhub/karsa_demo/blob/master/src/hooks/useCameraViewport.ts): `src/hooks/useCameraViewport.ts`
- [Character sprites](https://github.com/svtrhub/karsa_demo/blob/master/src/components/dashboard/CharacterSprite.tsx): `src/components/dashboard/CharacterSprite.tsx`
- [Persona navigation](https://github.com/svtrhub/karsa_demo/blob/master/src/components/dashboard/Sidebar.tsx): `src/components/dashboard/Sidebar.tsx`
- [Workspace controls](https://github.com/svtrhub/karsa_demo/blob/master/src/components/dashboard/TopBar.tsx): `src/components/dashboard/TopBar.tsx`
- [Command center](https://github.com/svtrhub/karsa_demo/blob/master/src/components/dashboard/FloatingCommandCenter.tsx): `src/components/dashboard/FloatingCommandCenter.tsx`
- [Chat interface](https://github.com/svtrhub/karsa_demo/blob/master/src/components/chat/ChatModal.tsx): `src/components/chat/ChatModal.tsx`
- [Planned features](https://github.com/svtrhub/karsa_demo/blob/master/src/components/dashboard/ComingSoonModal.tsx): `src/components/dashboard/ComingSoonModal.tsx`

### Profile and state

- [Demo state](https://github.com/svtrhub/karsa_demo/blob/master/src/context/DemoContext.tsx): `src/context/DemoContext.tsx`
- [State transitions](https://github.com/svtrhub/karsa_demo/blob/master/src/lib/domainEngine.ts): `src/lib/domainEngine.ts`
- **Browser storage**

### Persona guidance

- [Persona prompts](https://github.com/svtrhub/karsa_demo/blob/master/src/lib/personas.ts): `src/lib/personas.ts`

### Chat service

- [Chat stream hook](https://github.com/svtrhub/karsa_demo/blob/master/src/hooks/useChatStream.ts): `src/hooks/useChatStream.ts`
- [Chat API route](https://github.com/svtrhub/karsa_demo/blob/master/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [Rate limiter](https://github.com/svtrhub/karsa_demo/blob/master/src/lib/rateLimit.ts): `src/lib/rateLimit.ts`
- [LLM streaming](https://github.com/svtrhub/karsa_demo/blob/master/src/lib/llm.ts): `src/lib/llm.ts`

### Other components

- **Student**
- **Google Gemini**

## Connections

- Student → Application flow: opens app (evidence: `README.md`)
- Application flow → Splash screen: renders (evidence: `src/app/page.tsx`)
- Application flow → Profile onboarding: renders (evidence: `src/app/page.tsx`)
- Application flow → First-use tour: renders (evidence: `src/app/page.tsx`)
- Application flow → Workspace room: renders (evidence: `src/app/page.tsx`)
- Application flow → Persona navigation: renders (evidence: `src/app/page.tsx`)
- Application flow → Workspace controls: renders (evidence: `src/app/page.tsx`)
- Application flow → Command center: renders (evidence: `src/app/page.tsx`)
- Application flow → Chat interface: renders (evidence: `src/app/page.tsx`)
- Application flow → Planned features: renders (evidence: `src/app/page.tsx`)
- Application flow → Demo state: reads state (evidence: `src/app/page.tsx`)
- Profile onboarding → Demo state: updates profile (evidence: `src/components/onboarding/OnboardingFlow.tsx`)
- Persona navigation → Demo state: opens persona chat (evidence: `src/components/dashboard/Sidebar.tsx`)
- Workspace room → Room camera: uses camera (evidence: `src/components/dashboard/RumahKarsaRoom.tsx`)
- Workspace room → Character sprites: renders characters (evidence: `src/components/dashboard/RumahKarsaRoom.tsx`)
- Chat interface → Demo state: reads and updates chat (evidence: `src/components/chat/ChatModal.tsx`)
- Demo state → State transitions: delegates transitions (evidence: `src/context/DemoContext.tsx`)
- Demo state → Browser storage: persists state (evidence: `src/context/DemoContext.tsx`)
- Chat interface → Chat stream hook: sends messages (evidence: `src/components/chat/ChatModal.tsx`)
- Chat stream hook → Chat API route: posts chat (evidence: `src/hooks/useChatStream.ts`)
- Chat API route → Rate limiter: checks limits (evidence: `src/app/api/chat/route.ts`)
- Chat API route → LLM streaming: requests stream (evidence: `src/app/api/chat/route.ts`)
- LLM streaming → Persona prompts: builds prompt (evidence: `src/lib/llm.ts`)
- LLM streaming → Google Gemini: streams response (evidence: `src/lib/llm.ts`)
