# sakshamtiwarikk/wonderworld_chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/sakshamtiwarikk/wonderworld_chatbot
- Repository: https://github.com/sakshamtiwarikk/wonderworld_chatbot

## Overview

1. **Overall shape**
   - This repository is a small **chatbot monorepo** split into a **frontend client** and a **backend server**.
   - The root contains shared tooling plus a top-level `index.ts`, but the real application boundaries are clearly in `packages/client` and `packages/server`.

2. **Client application boundary**
   - `packages/client` is a **Vite + React + TypeScript** app.
   - It owns everything related to the user-facing chat experience: layout, message rendering, input capture, typing feedback, and UI styling.
   - Key entry points are `src/main.tsx` and `src/App.tsx`.

3. **Chat UI subsystem**
   - The chat UI is decomposed into focused components under `src/components/chat`:
     - `ChatInput.tsx` for message entry
     - `ChatMessages.tsx` for conversation rendering
     - `TypingIndicator.tsx` for “bot is responding” state
     - `ChatBot.tsx` as the higher-level chat orchestration component
   - This suggests a stateful client-side interaction model rather than a static page.

4. **Client-side feedback and assets**
   - The client includes sound assets in `src/assets/sounds` (`notification.mp3`, `pop.mp3`), which indicates **auditory response cues** in the chat flow.
   - These sounds likely map to message arrival and interaction feedback, making the UI more than just text rendering.

5. **Server application boundary**
   - `packages/server` is the backend, written in **TypeScript for Bun**.
   - It is organized into a classic layered structure:
     - `routes.ts` for HTTP routing
     - `controllers/` for request/response handling
     - `services/` for business logic
     - `repositories/` for data access / conversation persistence
   - This separation is the core backend architecture.

6. **Chat request lifecycle**
   - The expected flow is:
     - client submits a message
     - server route receives the request
     - controller validates/normalizes it
     - service generates the chatbot response
     - repository reads/writes conversation context
     - response returns to client
   - That flow is the most important diagram path in the repo.

7. **Prompt-driven response generation**
   - The server has a dedicated `prompts/` directory with `WonderWorld.md` and `chatbot.txt`.
   - That means response behavior is influenced by **prompt templates / system instructions** stored outside the code path.
   - In architecture terms, prompt content is a first-class backend dependency, not an incidental string in code.

8. **Conversation state boundary**
   - `repositories/conversation.repository.ts` indicates a dedicated abstraction for chat history or session context.
   - Even without seeing the implementation, the presence of a repository layer means conversation state is intentionally isolated from controllers/services.
   - This is a likely seam for persistence, memory, or future storage changes.

9. **Server API surface**
   - `controllers/chat.controller.ts` and `routes.ts` imply the backend exposes a small, purpose-built chat API rather than a broad general-purpose service.
   - The backend likely focuses on one primary capability: taking user messages and returning assistant replies.

10. **Tooling and runtime**
   - The repo uses **Bun** as the primary runtime (`bun.lockb`, README run command).
   - The client is built with **Vite**, and both packages are TypeScript-based.
   - Husky/lint-staged/Prettier/eslint config files show the repo is set up with standard code-quality hooks, but these are supporting concerns rather than architectural ones.

11. **Likely deployment model**
   - Architecturally, this is best viewed as a **two-process system**:
     - browser-based React client
     - Bun-based server API
   - The client and server are separated at the network boundary, with the server acting as the chat intelligence layer.

12. **What to emphasize in a diagram**
   - Draw the client as the interaction layer, with message input, conversation view, typing state, and audio feedback.
   - Draw the server as a layered backend: route → controller → service → repository, with prompt files feeding the service.
   - The main data flow is user message in the browser, server-side chat generation, and assistant response back to the UI.

Main entry points: [`packages/client/src/components/chat/ChatBot.tsx`](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/components/chat/ChatBot.tsx) (ChatBot), [`packages/server/services/chat.service.ts`](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/server/services/chat.service.ts) (Service), [`packages/client/src/App.tsx`](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/App.tsx) (App shell), [`index.ts`](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/index.ts) (Root entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Workspace"]
  node_root_index["Root entry<br/>workspace entry<br/>[index.ts]"]
end

subgraph group_client["Client"]
  node_client_main["Main<br/>react bootstrap<br/>[main.tsx]"]
  node_client_app["App shell<br/>react shell<br/>[App.tsx]"]
  node_chatbot["ChatBot<br/>chat orchestrator<br/>[ChatBot.tsx]"]
  node_chat_input["Input<br/>[ChatInput.tsx]"]
  node_chat_messages["Messages<br/>chat history view<br/>[ChatMessages.tsx]"]
  node_typing_indicator(("Typing<br/>response state"))
  node_chat_sounds["Sounds<br/>audio assets"]
  node_ui_button["Button<br/>ui primitive<br/>[button.tsx]"]
  node_client_styles["Styles<br/>css styling<br/>[index.css]"]
end

subgraph group_server["Server"]
  node_server_index["Server entry<br/>bun bootstrap<br/>[index.ts]"]
  node_server_routes["Routes<br/>http routing<br/>[routes.ts]"]
  node_chat_controller["Controller<br/>request handler<br/>[chat.controller.ts]"]
  node_chat_service["Service<br/>chat logic<br/>[chat.service.ts]"]
  node_conversation_repo[("Conversation")]
  node_prompt_wonderworld["WonderWorld<br/>prompt template<br/>[WonderWorld.md]"]
  node_prompt_chatbot["Chatbot prompt<br/>prompt template<br/>[chatbot.txt]"]
end

node_root_index -->|"bootstraps"| node_client_main
node_root_index -->|"bootstraps"| node_server_index
node_client_main -->|"renders"| node_client_app
node_client_app -->|"composes"| node_chatbot
node_chatbot -->|"uses"| node_chat_input
node_chatbot -->|"uses"| node_chat_messages
node_chatbot -->|"uses"| node_typing_indicator
node_chatbot -->|"plays"| node_chat_sounds
node_chatbot -->|"reuses"| node_ui_button
node_client_app -->|"styles"| node_client_styles
node_server_index -->|"starts"| node_server_routes
node_server_routes -->|"dispatches"| node_chat_controller
node_chat_controller -->|"delegates"| node_chat_service
node_chat_service -->|"reads/writes"| node_conversation_repo
node_chat_service -->|"loads"| node_prompt_wonderworld
node_chat_service -->|"loads"| node_prompt_chatbot
node_chat_service -->|"responds to"| node_chatbot

click node_root_index "https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/index.ts"
click node_client_main "https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/main.tsx"
click node_client_app "https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/App.tsx"
click node_chatbot "https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/components/chat/ChatBot.tsx"
click node_chat_input "https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/components/chat/ChatInput.tsx"
click node_chat_messages "https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/components/chat/ChatMessages.tsx"
click node_typing_indicator "https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/components/chat/TypingIndicator.tsx"
click node_chat_sounds "https://github.com/sakshamtiwarikk/wonderworld_chatbot/tree/main/packages/client/src/assets/sounds"
click node_ui_button "https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/components/ui/button.tsx"
click node_client_styles "https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/index.css"
click node_server_index "https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/server/index.ts"
click node_server_routes "https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/server/routes.ts"
click node_chat_controller "https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/server/controllers/chat.controller.ts"
click node_chat_service "https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/server/services/chat.service.ts"
click node_conversation_repo "https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/server/repositories/conversation.repository.ts"
click node_prompt_wonderworld "https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/server/prompts/WonderWorld.md"
click node_prompt_chatbot "https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/server/prompts/chatbot.txt"

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_root_index toneBlue
class node_client_main,node_client_app,node_chatbot,node_chat_input,node_chat_messages,node_typing_indicator,node_chat_sounds,node_ui_button,node_client_styles toneAmber
class node_server_index,node_server_routes,node_chat_controller,node_chat_service,node_conversation_repo,node_prompt_wonderworld,node_prompt_chatbot toneMint
```

## Components

### Workspace

Monorepo-level tooling and shared entry points

- [Root entry](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/index.ts): workspace entry · Top-level TypeScript entry point · `index.ts`

### Client

Vite + React chat UI

- [Main](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/main.tsx): react bootstrap · Client application bootstrap · `packages/client/src/main.tsx`
- [App shell](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/App.tsx): react shell · Top-level client composition and layout · `packages/client/src/App.tsx`
- [ChatBot](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/components/chat/ChatBot.tsx): chat orchestrator · Coordinates chat state and user interaction · `packages/client/src/components/chat/ChatBot.tsx`
- [Input](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/components/chat/ChatInput.tsx): chat input · Message entry component · `packages/client/src/components/chat/ChatInput.tsx`
- [Messages](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/components/chat/ChatMessages.tsx): chat history view · Conversation rendering component · `packages/client/src/components/chat/ChatMessages.tsx`
- [Typing](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/components/chat/TypingIndicator.tsx): response state · Bot responding indicator · `packages/client/src/components/chat/TypingIndicator.tsx`
- [Sounds](https://github.com/sakshamtiwarikk/wonderworld_chatbot/tree/main/packages/client/src/assets/sounds): audio assets · Notification and feedback sounds · `packages/client/src/assets/sounds`
- [Button](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/components/ui/button.tsx): ui primitive · Reusable client UI control · `packages/client/src/components/ui/button.tsx`
- [Styles](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/client/src/index.css): css styling · Global and app styling · `packages/client/src/index.css`

### Server

Bun-based chat API

- [Server entry](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/server/index.ts): bun bootstrap · Backend process entry point · `packages/server/index.ts`
- [Routes](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/server/routes.ts): http routing · Backend API surface · `packages/server/routes.ts`
- [Controller](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/server/controllers/chat.controller.ts): request handler · Normalizes chat requests and responses · `packages/server/controllers/chat.controller.ts`
- [Service](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/server/services/chat.service.ts): chat logic · Generates assistant replies and coordinates dependencies · `packages/server/services/chat.service.ts`
- [Conversation](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/server/repositories/conversation.repository.ts): repository · Conversation state and persistence boundary · `packages/server/repositories/conversation.repository.ts`
- [WonderWorld](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/server/prompts/WonderWorld.md): prompt template · Prompt content shaping assistant behavior · `packages/server/prompts/WonderWorld.md`
- [Chatbot prompt](https://github.com/sakshamtiwarikk/wonderworld_chatbot/blob/main/packages/server/prompts/chatbot.txt): prompt template · Additional chatbot instructions · `packages/server/prompts/chatbot.txt`

## Connections

- Root entry → Main: bootstraps · Workspace entry leads into the client app
- Root entry → Server entry: bootstraps · Workspace entry leads into the backend process
- Main → App shell: renders · Client bootstrap mounts the app shell
- App shell → ChatBot: composes · App shell assembles chat experience
- ChatBot → Input: uses · Chat orchestration wires message entry
- ChatBot → Messages: uses · Chat orchestration renders conversation history
- ChatBot → Typing: uses · Chat orchestration shows response state
- ChatBot → Sounds: plays · Audio cues support chat interactions
- ChatBot → Button: reuses · Shared UI primitive supports chat controls
- App shell → Styles: styles · Global styling shapes the chat UI
- Server entry → Routes: starts · Backend entry initializes HTTP routing
- Routes → Controller: dispatches · Route layer forwards chat requests
- Controller → Service: delegates · Controller hands off business logic
- Service → Conversation: reads/writes · Service persists or loads conversation context
- Service → WonderWorld: loads · Prompt content influences response generation
- Service → Chatbot prompt: loads · Prompt content influences response generation
- Service → ChatBot: responds to · Server replies back into the client chat flow
