saran-ex/baymax-bloom

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.