# saran-ex/baymax-bloom architecture

> Architecture diagram of the GitHub repository saran-ex/baymax-bloom, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saran-ex/baymax-bloom
- Repository: https://github.com/saran-ex/baymax-bloom

## Overview

1. **Top-level shape**
   - This is a **two-part repo**: a **React/Vite frontend** at the root and a separate **Node backend** under `backend/`.
   - The app is structured like a **single-page experience** with a distinct API service for conversation/AI features.

2. **Frontend runtime**
   - The frontend is built with **TypeScript + React + Vite**.
   - Entry points are `src/main.tsx` and `src/App.tsx`, with route/page organization under `src/pages/`.
   - Pages include `HomePage`, `LoginPage`, `Index`, and `NotFound`, suggesting client-side navigation and a fallback route.

3. **UI composition layer**
   - The visual system is heavily componentized:
     - Custom scene/character components: `BaymaxScene.tsx`, `BaymaxFace.tsx`, `NavLink.tsx`
     - A large `src/components/ui/` library of **shadcn-style primitives** (button, dialog, sheet, tabs, toast, etc.)
   - This indicates the UI is assembled from reusable primitives rather than a monolithic page implementation.

4. **Presentation and animation assets**
   - Static assets live in `public/`, including `public/videos/baymax-bg.mp4`.
   - The naming of `Baymax*` components and the video asset suggests the frontend includes a **character-driven or animated landing experience** as part of the user interface.

5. **Frontend state and utility boundaries**
   - Shared client helpers live in `src/lib/utils.ts`.
   - Cross-cutting hooks are isolated in `src/hooks/`, including mobile detection and toast state.
   - This separates reusable UI behavior from the page and component layers.

6. **Backend service boundary**
   - The backend is isolated in `backend/` and likely runs as a separate **Express-style API server**.
   - `backend/server.js` and `backend/src/app.js` imply a conventional server bootstrap + app composition split.
   - This backend is the boundary for server-side integration work rather than general page rendering.

7. **Chat/conversation API subsystem**
   - The backend’s main domain appears to be **chat**:
     - `src/routes/chatRoutes.js`
     - `src/controllers/chatController.js`
     - `src/prompts/`
   - This suggests a request flow of: client submits message → route/controller handles it → prompt logic is assembled → AI response is returned.

8. **LLM integration**
   - `backend/src/config/gemini.js` is the key integration point for **Google Gemini** or a Gemini-compatible API.
   - Prompts are separated into `stellaPrompt.js` and `conversationTopics.js`, which indicates prompt engineering is treated as application logic, not embedded directly in the controller.
   - The backend is therefore acting as an **LLM orchestration layer** between the UI and the model API.

9. **Backend support concerns**
   - `backend/src/utils/logger.js` indicates centralized server logging.
   - `backend/.env` shows the backend relies on environment-based configuration, likely for API keys and runtime settings.
   - This keeps secrets and provider configuration out of the frontend bundle.

10. **Data flow across the system**
   - The likely end-to-end path is:
     - User interacts with the frontend character/chat UI
     - Frontend sends a request to the backend chat route
     - The controller builds or selects a prompt context
     - The Gemini config/client sends the model request
     - The backend returns the generated response
     - The UI renders the response and any associated visual feedback
   - The main architectural boundary is **browser UI vs. server-side AI orchestration**.

11. **Tooling and build system**
   - Frontend tooling: **Vite**, **TypeScript**, **Tailwind CSS**, **shadcn-ui**.
   - Testing: **Vitest** with setup files under `src/test/`.
   - Code quality/configuration is managed through `eslint.config.js`, `tailwind.config.ts`, and multiple `tsconfig` files.
   - This supports a modern frontend build pipeline with separate app/node TypeScript configurations.

12. **Repository-level implications for diagramming**
   - A good architecture diagram should show:
     - A **React frontend** consuming local UI components and static assets
     - A **Node/Express backend API**
     - A distinct **chat/LLM integration path** through Gemini
     - Prompt assets and logging as backend support modules
   - The diagram should emphasize that the backend is not a generic CRUD service; it is specifically an **AI chat orchestration service** behind the frontend.

Main entry points: [`src/App.tsx`](https://github.com/saran-ex/baymax-bloom/blob/main/src/App.tsx) (App), [`backend/src/controllers/chatController.js`](https://github.com/saran-ex/baymax-bloom/blob/main/backend/src/controllers/chatController.js) (Chat Controller), [`src/pages/Index.tsx`](https://github.com/saran-ex/baymax-bloom/blob/main/src/pages/Index.tsx) (Pages), [`src/pages/HomePage.tsx`](https://github.com/saran-ex/baymax-bloom/blob/main/src/pages/HomePage.tsx) (Home)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_main["Entry<br/>vite bootstrap<br/>[main.tsx]"]
  node_app["App<br/>react shell<br/>[App.tsx]"]
  node_pages["Pages<br/>routes/views<br/>[Index.tsx]"]
  node_home["Home<br/>landing page<br/>[HomePage.tsx]"]
  node_login["Login<br/>auth page<br/>[LoginPage.tsx]"]
  node_notfound["Not Found<br/>fallback page<br/>[NotFound.tsx]"]
  node_scene(("Baymax Scene<br/>animated UI<br/>[BaymaxScene.tsx]"))
  node_face(("Baymax Face<br/>character UI<br/>[BaymaxFace.tsx]"))
  node_navlink["Nav Link<br/>nav component<br/>[NavLink.tsx]"]
  node_ui["UI Primitives<br/>shadcn library<br/>[button.tsx]"]
  node_hooks["Hooks<br/>[use-mobile.tsx]"]
  node_utils["Utils<br/>client helpers<br/>[utils.ts]"]
  node_assets["Video Asset<br/>static media<br/>[baymax-bg.mp4]"]
end

subgraph group_backend["Backend"]
  node_server["Server<br/>node bootstrap<br/>[server.js]"]
  node_appjs["API App<br/>server composition<br/>[app.js]"]
  node_routes["Chat Routes<br/>api routes<br/>[chatRoutes.js]"]
  node_controller["Chat Controller<br/>request handler<br/>[chatController.js]"]
  node_gemini["Gemini Client<br/>llm integration<br/>[gemini.js]"]
  node_prompts["Prompts<br/>prompt assets<br/>[stellaPrompt.js]"]
  node_logger["Logger<br/>server logging<br/>[logger.js]"]
end

node_main -->|"mounts"| node_app
node_app -->|"navigates"| node_pages
node_pages -->|"includes"| node_home
node_pages -->|"includes"| node_login
node_pages -->|"includes"| node_notfound
node_home -->|"uses"| node_scene
node_scene -->|"renders"| node_face
node_home -->|"uses"| node_navlink
node_home -->|"builds with"| node_ui
node_app -->|"uses"| node_hooks
node_app -->|"uses"| node_utils
node_scene -->|"plays"| node_assets
node_server -->|"starts"| node_appjs
node_appjs -->|"registers"| node_routes
node_routes -->|"dispatches"| node_controller
node_controller -->|"assembles"| node_prompts
node_controller -->|"calls"| node_gemini
node_controller -->|"logs"| node_logger
node_app -->|"requests AI"| node_controller

click node_main "https://github.com/saran-ex/baymax-bloom/blob/main/src/main.tsx"
click node_app "https://github.com/saran-ex/baymax-bloom/blob/main/src/App.tsx"
click node_pages "https://github.com/saran-ex/baymax-bloom/blob/main/src/pages/Index.tsx"
click node_home "https://github.com/saran-ex/baymax-bloom/blob/main/src/pages/HomePage.tsx"
click node_login "https://github.com/saran-ex/baymax-bloom/blob/main/src/pages/LoginPage.tsx"
click node_notfound "https://github.com/saran-ex/baymax-bloom/blob/main/src/pages/NotFound.tsx"
click node_scene "https://github.com/saran-ex/baymax-bloom/blob/main/src/components/BaymaxScene.tsx"
click node_face "https://github.com/saran-ex/baymax-bloom/blob/main/src/components/BaymaxFace.tsx"
click node_navlink "https://github.com/saran-ex/baymax-bloom/blob/main/src/components/NavLink.tsx"
click node_ui "https://github.com/saran-ex/baymax-bloom/blob/main/src/components/ui/button.tsx"
click node_hooks "https://github.com/saran-ex/baymax-bloom/blob/main/src/hooks/use-mobile.tsx"
click node_utils "https://github.com/saran-ex/baymax-bloom/blob/main/src/lib/utils.ts"
click node_assets "https://github.com/saran-ex/baymax-bloom/blob/main/public/videos/baymax-bg.mp4"
click node_server "https://github.com/saran-ex/baymax-bloom/blob/main/backend/server.js"
click node_appjs "https://github.com/saran-ex/baymax-bloom/blob/main/backend/src/app.js"
click node_routes "https://github.com/saran-ex/baymax-bloom/blob/main/backend/src/routes/chatRoutes.js"
click node_controller "https://github.com/saran-ex/baymax-bloom/blob/main/backend/src/controllers/chatController.js"
click node_gemini "https://github.com/saran-ex/baymax-bloom/blob/main/backend/src/config/gemini.js"
click node_prompts "https://github.com/saran-ex/baymax-bloom/blob/main/backend/src/prompts/stellaPrompt.js"
click node_logger "https://github.com/saran-ex/baymax-bloom/blob/main/backend/src/utils/logger.js"

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_main,node_app,node_pages,node_home,node_login,node_notfound,node_scene,node_face,node_navlink,node_ui,node_hooks,node_utils,node_assets toneBlue
class node_server,node_appjs,node_routes,node_controller,node_gemini,node_prompts,node_logger toneAmber
```

## Components

### Frontend

React/Vite single-page app and UI system

- [Entry](https://github.com/saran-ex/baymax-bloom/blob/main/src/main.tsx): vite bootstrap · Starts the React app · `src/main.tsx`
- [App](https://github.com/saran-ex/baymax-bloom/blob/main/src/App.tsx): react shell · Top-level client composition · `src/App.tsx`
- [Pages](https://github.com/saran-ex/baymax-bloom/blob/main/src/pages/Index.tsx): routes/views · Client-side page views · `src/pages/Index.tsx`
- [Home](https://github.com/saran-ex/baymax-bloom/blob/main/src/pages/HomePage.tsx): landing page · Primary landing experience · `src/pages/HomePage.tsx`
- [Login](https://github.com/saran-ex/baymax-bloom/blob/main/src/pages/LoginPage.tsx): auth page · Sign-in flow · `src/pages/LoginPage.tsx`
- [Not Found](https://github.com/saran-ex/baymax-bloom/blob/main/src/pages/NotFound.tsx): fallback page · 404 route handler · `src/pages/NotFound.tsx`
- [Baymax Scene](https://github.com/saran-ex/baymax-bloom/blob/main/src/components/BaymaxScene.tsx): animated UI · Character-driven visual scene · `src/components/BaymaxScene.tsx`
- [Baymax Face](https://github.com/saran-ex/baymax-bloom/blob/main/src/components/BaymaxFace.tsx): character UI · Character facial presentation · `src/components/BaymaxFace.tsx`
- [Nav Link](https://github.com/saran-ex/baymax-bloom/blob/main/src/components/NavLink.tsx): nav component · Reusable navigation element · `src/components/NavLink.tsx`
- [UI Primitives](https://github.com/saran-ex/baymax-bloom/blob/main/src/components/ui/button.tsx): shadcn library · Reusable component kit · `src/components/ui/button.tsx`
- [Hooks](https://github.com/saran-ex/baymax-bloom/blob/main/src/hooks/use-mobile.tsx): client hooks · Shared client behavior · `src/hooks/use-mobile.tsx`
- [Utils](https://github.com/saran-ex/baymax-bloom/blob/main/src/lib/utils.ts): client helpers · Shared frontend utilities · `src/lib/utils.ts`
- [Video Asset](https://github.com/saran-ex/baymax-bloom/blob/main/public/videos/baymax-bg.mp4): static media · Background animation media · `public/videos/baymax-bg.mp4`

### Backend

Node API and LLM orchestration

- [Server](https://github.com/saran-ex/baymax-bloom/blob/main/backend/server.js): node bootstrap · Backend process entry · `backend/server.js`
- [API App](https://github.com/saran-ex/baymax-bloom/blob/main/backend/src/app.js): server composition · Builds the backend application · `backend/src/app.js`
- [Chat Routes](https://github.com/saran-ex/baymax-bloom/blob/main/backend/src/routes/chatRoutes.js): api routes · Chat endpoint wiring · `backend/src/routes/chatRoutes.js`
- [Chat Controller](https://github.com/saran-ex/baymax-bloom/blob/main/backend/src/controllers/chatController.js): request handler · Handles chat requests · `backend/src/controllers/chatController.js`
- [Gemini Client](https://github.com/saran-ex/baymax-bloom/blob/main/backend/src/config/gemini.js): llm integration · Model provider integration · `backend/src/config/gemini.js`
- [Prompts](https://github.com/saran-ex/baymax-bloom/blob/main/backend/src/prompts/stellaPrompt.js): prompt assets · System and topic prompts · `backend/src/prompts/stellaPrompt.js`
- [Logger](https://github.com/saran-ex/baymax-bloom/blob/main/backend/src/utils/logger.js): server logging · Centralized backend logging · `backend/src/utils/logger.js`

## Connections

- Entry → App: mounts · Bootstraps the root app
- App → Pages: navigates · Selects page views
- Pages → Home: includes · Landing route
- Pages → Login: includes · Auth route
- Pages → Not Found: includes · Fallback route
- Home → Baymax Scene: uses · Composes the character scene
- Baymax Scene → Baymax Face: renders · Character face component
- Home → Nav Link: uses · Navigation links
- Home → UI Primitives: builds with · Uses shared UI primitives
- App → Hooks: uses · Shared client behavior
- App → Utils: uses · Utility helpers
- Baymax Scene → Video Asset: plays · Background media asset
- Server → API App: starts · Loads backend app
- API App → Chat Routes: registers · Attaches chat routes
- Chat Routes → Chat Controller: dispatches · Forwards chat requests
- Chat Controller → Prompts: assembles · Builds prompt context
- Chat Controller → Gemini Client: calls · Invokes the model provider
- Chat Controller → Logger: logs · Records server activity
- App → Chat Controller: requests AI · Frontend chat flow reaches backend API