# gokul99400/app architecture

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

- Interactive diagram: https://gitdiagram.com/gokul99400/app
- Repository: https://github.com/gokul99400/app

## Overview

1. **Project type and runtime**
   - This is a **TanStack Start** application: a React app with **file-based routing** and built-in **server-side rendering**.
   - The source app runs from `src/`, while deployable artifacts are emitted into `.output/` and a static `dist/` bundle.

2. **Top-level app structure**
   - `src/routes/__root.tsx` is the app shell for all routes.
   - `src/routes/index.tsx` is the main page served at `/`.
   - `src/routeTree.gen.ts` is generated route metadata used by TanStack Router and should be treated as build output, not hand-edited.

3. **Routing and navigation boundary**
   - Routing is entirely file-driven under `src/routes/`.
   - `src/router.tsx` wires the router into the app.
   - This separation makes route-level composition distinct from the game domain: routes decide page structure, while the game logic lives elsewhere.

4. **Game domain subsystem**
   - The core interactive experience is concentrated in `src/game/`.
   - `game.tsx` appears to be the orchestration layer for the game flow.
   - `board.tsx`, `Dice.tsx`, `QuestionModal.tsx`, `EventToast.tsx`, and `choiceModel.tsx` are focused UI/domain components that represent the board, dice interaction, modal prompts, transient events, and choice handling.

5. **Game state and content**
   - `src/lib/game-data.ts` likely contains the static or semi-static game content: questions, events, board data, or rules tables.
   - `choiceModel.tsx` suggests a data model for player decisions, implying the game flow is driven by structured content rather than ad hoc UI state.

6. **Shared UI component layer**
   - `src/components/ui/` contains reusable design-system style controls such as `button.tsx` and `dialog.tsx`.
   - These are low-level presentation primitives used by the game screens, especially modal and interaction surfaces.
   - The repo uses **Radix UI** under the hood, consistent with accessible dialog behavior and headless UI composition.

7. **Styling and visual system**
   - `src/styles.css` is the main global stylesheet.
   - The presence of `tailwind-merge`, `class-variance-authority`, and `clsx` in the build output indicates a utility-class-based styling approach with variant management.
   - The app likely combines Tailwind-style utilities with component variants rather than custom CSS architecture.

8. **Client-side utilities and platform support**
   - `src/hooks/use-mobile.tsx` provides responsive/device-aware behavior.
   - `src/lib/utils.ts` centralizes shared helper logic, likely class-name composition or small app utilities.
   - These are supporting utilities rather than business logic boundaries.

9. **Error handling and reporting**
   - `src/lib/error-capture.ts`, `src/lib/error-page.ts`, and `src/lib/lovable-error-reporting.ts` form the app’s error boundary/reporting layer.
   - This is a separate concern from the game flow: runtime failures are captured, rendered, and potentially reported through a dedicated path.

10. **Server and SSR entrypoints**
    - `src/server.ts` and `src/start.ts` are the backend/bootstrap entry points for TanStack Start.
    - The `.output/server/` tree shows the SSR/server runtime bundle, including router and renderer chunks.
    - This means the app is not purely client-rendered; the server participates in rendering and route delivery.

11. **Build and deployment outputs**
    - `dist/` contains static client assets and `index.html`.
    - `.output/` contains the full server bundle, generated manifests, and deployment-specific metadata such as `wrangler.json`.
    - `.wrangler/deploy/` indicates Cloudflare-oriented deployment tooling, so the app is likely intended to run on Cloudflare Workers or a similar edge runtime.

12. **Dependency stack that matters architecturally**
    - **TanStack Router**: route composition and navigation.
    - **TanStack Query**: data-fetching/cache layer, though this repo appears more UI/game-state driven than API-heavy.
    - **Radix UI**: accessible primitive UI components.
    - **Lucide React**: iconography.
    - These libraries shape the component and interaction architecture more than the backend does.

13. **Likely data flow**
    - User enters the root route → TanStack Start renders the app shell → the main route mounts the game container.
    - Game components consume shared game data and local interaction state.
    - User actions such as rolling dice, making choices, or acknowledging a question/event propagate through `game.tsx` into modal/toast/board components.
    - SSR and client hydration bridge the initial render with interactive gameplay.

14. **Key architectural boundaries for a diagram**
    - Keep **routing**, **game domain**, **shared UI primitives**, **error/reporting**, and **server/SSR runtime** as separate blocks.
    - Treat `.output/` and `dist/` as generated deployment artifacts, not source subsystems.
    - The most important application boundary is between the **route shell** and the **game engine UI/state layer**.

Main entry points: [`src/game/game.tsx`](https://github.com/gokul99400/app/blob/master/src/game/game.tsx) (Game Flow), [`src/server.ts`](https://github.com/gokul99400/app/blob/master/src/server.ts) (Server Entry), [`src/routes/__root.tsx`](https://github.com/gokul99400/app/blob/master/src/routes/__root.tsx) (App Shell), [`src/components/ui/button.tsx`](https://github.com/gokul99400/app/blob/master/src/components/ui/button.tsx) (Button)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_routes["Routing"]
  node_src_routes_root["App Shell<br/>route shell<br/>[__root.tsx]"]
  node_src_routes_index["Home Page<br/>route page<br/>[index.tsx]"]
  node_src_router["Router<br/>[router.tsx]"]
  node_src_route_tree["Route Tree<br/>generated routes<br/>[routeTree.gen.ts]"]
end

subgraph group_group_game["Game Domain"]
  node_src_game_game["Game Flow<br/>orchestrator<br/>[game.tsx]"]
  node_src_game_board["Board<br/>[board.tsx]"]
  node_src_game_dice["Dice<br/>interaction control<br/>[Dice.tsx]"]
  node_src_game_modal["Question Modal<br/>prompt ui<br/>[QuestionModal.tsx]"]
  node_src_game_toast["Event Toast<br/>feedback ui<br/>[EventToast.tsx]"]
  node_src_game_choice["Choice Model<br/>domain model<br/>[choiceModel.tsx]"]
  node_src_game_data["Game Data<br/>content data<br/>[game-data.ts]"]
end

subgraph group_group_ui["Shared UI"]
  node_src_ui_button["Button<br/>ui primitive<br/>[button.tsx]"]
  node_src_ui_dialog["Dialog<br/>ui primitive<br/>[dialog.tsx]"]
  node_src_styles["Styles<br/>global css<br/>[styles.css]"]
end

subgraph group_group_support["Support"]
  node_src_hooks_mobile["Mobile Hook<br/>responsive hook<br/>[use-mobile.tsx]"]
  node_src_lib_utils["Utils<br/>shared helpers<br/>[utils.ts]"]
  node_src_lib_error_capture["Capture<br/>error handling<br/>[error-capture.ts]"]
  node_src_lib_error_page["Error Page<br/>error ui<br/>[error-page.ts]"]
  node_src_lib_reporting["Reporting"]
end

subgraph group_group_runtime["Runtime"]
  node_src_server["Server Entry<br/>ssr bootstrap<br/>[server.ts]"]
  node_src_start["Start Entry<br/>app bootstrap<br/>[start.ts]"]
  node_dist_output["Static Build<br/>generated client<br/>[index.html]"]
  node_output_server["SSR Bundle<br/>generated server<br/>[index.mjs]"]
end

node_src_router -->|"uses"| node_src_route_tree
node_src_routes_root -->|"hosts"| node_src_game_game
node_src_routes_index -->|"renders"| node_src_game_game
node_src_game_game -->|"drives"| node_src_game_board
node_src_game_game -->|"drives"| node_src_game_dice
node_src_game_game -->|"triggers"| node_src_game_modal
node_src_game_game -->|"emits"| node_src_game_toast
node_src_game_game -->|"uses"| node_src_game_choice
node_src_game_game -->|"loads"| node_src_game_data
node_src_game_modal -->|"builds on"| node_src_ui_dialog
node_src_game_dice -->|"uses"| node_src_ui_button
node_src_game_board -->|"uses"| node_src_ui_button
node_src_ui_dialog -->|"uses"| node_src_lib_utils
node_src_ui_button -->|"uses"| node_src_lib_utils
node_src_routes_root -->|"styled by"| node_src_styles
node_src_game_game -->|"adapts"| node_src_hooks_mobile
node_src_lib_error_page -->|"pairs with"| node_src_lib_error_capture
node_src_lib_error_capture -->|"reports to"| node_src_lib_reporting
node_src_server -->|"builds"| node_output_server
node_src_start -->|"builds"| node_dist_output
node_src_start -->|"boots"| node_src_router
node_src_server -->|"serves"| node_src_routes_root
node_src_server -->|"renders"| node_src_game_game

click node_src_routes_root "https://github.com/gokul99400/app/blob/master/src/routes/__root.tsx"
click node_src_routes_index "https://github.com/gokul99400/app/blob/master/src/routes/index.tsx"
click node_src_router "https://github.com/gokul99400/app/blob/master/src/router.tsx"
click node_src_route_tree "https://github.com/gokul99400/app/blob/master/src/routeTree.gen.ts"
click node_src_game_game "https://github.com/gokul99400/app/blob/master/src/game/game.tsx"
click node_src_game_board "https://github.com/gokul99400/app/blob/master/src/game/board.tsx"
click node_src_game_dice "https://github.com/gokul99400/app/blob/master/src/game/Dice.tsx"
click node_src_game_modal "https://github.com/gokul99400/app/blob/master/src/game/QuestionModal.tsx"
click node_src_game_toast "https://github.com/gokul99400/app/blob/master/src/game/EventToast.tsx"
click node_src_game_choice "https://github.com/gokul99400/app/blob/master/src/game/choiceModel.tsx"
click node_src_game_data "https://github.com/gokul99400/app/blob/master/src/lib/game-data.ts"
click node_src_ui_button "https://github.com/gokul99400/app/blob/master/src/components/ui/button.tsx"
click node_src_ui_dialog "https://github.com/gokul99400/app/blob/master/src/components/ui/dialog.tsx"
click node_src_styles "https://github.com/gokul99400/app/blob/master/src/styles.css"
click node_src_hooks_mobile "https://github.com/gokul99400/app/blob/master/src/hooks/use-mobile.tsx"
click node_src_lib_utils "https://github.com/gokul99400/app/blob/master/src/lib/utils.ts"
click node_src_lib_error_capture "https://github.com/gokul99400/app/blob/master/src/lib/error-capture.ts"
click node_src_lib_error_page "https://github.com/gokul99400/app/blob/master/src/lib/error-page.ts"
click node_src_lib_reporting "https://github.com/gokul99400/app/blob/master/src/lib/lovable-error-reporting.ts"
click node_src_server "https://github.com/gokul99400/app/blob/master/src/server.ts"
click node_src_start "https://github.com/gokul99400/app/blob/master/src/start.ts"
click node_dist_output "https://github.com/gokul99400/app/blob/master/dist/index.html"
click node_output_server "https://github.com/gokul99400/app/blob/master/.output/server/index.mjs"

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_src_routes_root,node_src_routes_index,node_src_router,node_src_route_tree toneBlue
class node_src_game_game,node_src_game_board,node_src_game_dice,node_src_game_modal,node_src_game_toast,node_src_game_choice,node_src_game_data toneAmber
class node_src_ui_button,node_src_ui_dialog,node_src_styles toneMint
class node_src_hooks_mobile,node_src_lib_utils,node_src_lib_error_capture,node_src_lib_error_page,node_src_lib_reporting toneRose
class node_src_server,node_src_start,node_dist_output,node_output_server toneIndigo
```

## Components

### Routing

File-based routes and router wiring for the TanStack Start app.

- [App Shell](https://github.com/gokul99400/app/blob/master/src/routes/__root.tsx): route shell · Root route wrapper shared by all pages. · `src/routes/__root.tsx`
- [Home Page](https://github.com/gokul99400/app/blob/master/src/routes/index.tsx): route page · Main route mounted at /. · `src/routes/index.tsx`
- [Router](https://github.com/gokul99400/app/blob/master/src/router.tsx): router setup · Wires TanStack Router into the app. · `src/router.tsx`
- [Route Tree](https://github.com/gokul99400/app/blob/master/src/routeTree.gen.ts): generated routes · Generated route metadata used by the router. · `src/routeTree.gen.ts`

### Game Domain

Interactive game flow, board, prompts, and choice handling.

- [Game Flow](https://github.com/gokul99400/app/blob/master/src/game/game.tsx): orchestrator · Coordinates the interactive game experience. · `src/game/game.tsx`
- [Board](https://github.com/gokul99400/app/blob/master/src/game/board.tsx): game board · Renders the board and core play surface. · `src/game/board.tsx`
- [Dice](https://github.com/gokul99400/app/blob/master/src/game/Dice.tsx): interaction control · Handles dice rolling and related interaction. · `src/game/Dice.tsx`
- [Question Modal](https://github.com/gokul99400/app/blob/master/src/game/QuestionModal.tsx): prompt ui · Modal prompt for questions and player decisions. · `src/game/QuestionModal.tsx`
- [Event Toast](https://github.com/gokul99400/app/blob/master/src/game/EventToast.tsx): feedback ui · Transient event and status feedback. · `src/game/EventToast.tsx`
- [Choice Model](https://github.com/gokul99400/app/blob/master/src/game/choiceModel.tsx): domain model · Structured decision logic for game choices. · `src/game/choiceModel.tsx`
- [Game Data](https://github.com/gokul99400/app/blob/master/src/lib/game-data.ts): content data · Static game content, rules, and scenario data. · `src/lib/game-data.ts`

### Shared UI

Reusable UI primitives and styling foundation.

- [Button](https://github.com/gokul99400/app/blob/master/src/components/ui/button.tsx): ui primitive · Reusable interaction control. · `src/components/ui/button.tsx`
- [Dialog](https://github.com/gokul99400/app/blob/master/src/components/ui/dialog.tsx): ui primitive · Accessible dialog foundation from Radix UI. · `src/components/ui/dialog.tsx`
- [Styles](https://github.com/gokul99400/app/blob/master/src/styles.css): global css · Global stylesheet and visual baseline. · `src/styles.css`

### Support

Utility, responsive, and error/reporting concerns.

- [Mobile Hook](https://github.com/gokul99400/app/blob/master/src/hooks/use-mobile.tsx): responsive hook · Responsive/device-aware client utility. · `src/hooks/use-mobile.tsx`
- [Utils](https://github.com/gokul99400/app/blob/master/src/lib/utils.ts): shared helpers · Common helper logic such as class composition. · `src/lib/utils.ts`
- [Capture](https://github.com/gokul99400/app/blob/master/src/lib/error-capture.ts): error handling · Captures runtime errors for reporting. · `src/lib/error-capture.ts`
- [Error Page](https://github.com/gokul99400/app/blob/master/src/lib/error-page.ts): error ui · Renders the user-facing failure state. · `src/lib/error-page.ts`
- [Reporting](https://github.com/gokul99400/app/blob/master/src/lib/lovable-error-reporting.ts): error reporting · Error reporting integration and transport. · `src/lib/lovable-error-reporting.ts`

### Runtime

SSR/server bootstrap and generated deployment artifacts.

- [Server Entry](https://github.com/gokul99400/app/blob/master/src/server.ts): ssr bootstrap · Server-side entrypoint for TanStack Start. · `src/server.ts`
- [Start Entry](https://github.com/gokul99400/app/blob/master/src/start.ts): app bootstrap · Client/server startup bootstrap. · `src/start.ts`
- [Static Build](https://github.com/gokul99400/app/blob/master/dist/index.html): generated client · Deployable client bundle and HTML output. · `dist/index.html`
- [SSR Bundle](https://github.com/gokul99400/app/blob/master/.output/server/index.mjs): generated server · Generated server runtime and deployment artifacts. · `.output/server/index.mjs`

## Connections

- Router → Route Tree: uses · Router consumes generated route metadata.
- App Shell → Game Flow: hosts · Root shell mounts the main game experience.
- Home Page → Game Flow: renders · Home route presents the game container.
- Game Flow → Board: drives · Game flow coordinates the board.
- Game Flow → Dice: drives · Game flow manages dice interaction.
- Game Flow → Question Modal: triggers · Game flow opens question and choice prompts.
- Game Flow → Event Toast: emits · Game flow surfaces transient event feedback.
- Game Flow → Choice Model: uses · Game flow relies on structured choice logic.
- Game Flow → Game Data: loads · Game flow consumes the game content and rules.
- Question Modal → Dialog: builds on · Modal uses the shared dialog primitive.
- Dice → Button: uses · Dice interaction is exposed through button-like control.
- Board → Button: uses · Board interactions use shared controls.
- Dialog → Utils: uses · Shared primitives rely on common helpers.
- Button → Utils: uses · Class composition and helpers are shared.
- App Shell → Styles: styled by · App shell is shaped by global styles.
- Game Flow → Mobile Hook: adapts · Game UI responds to device form factor.
- Error Page → Capture: pairs with · Error page is driven by captured failures.
- Capture → Reporting: reports to · Captured errors can be sent through reporting.
- Server Entry → SSR Bundle: builds · Server entry compiles into SSR output.
- Start Entry → Static Build: builds · App bootstrap produces the static client bundle.
- Start Entry → Router: boots · Startup wires the router into the app.
- Server Entry → App Shell: serves · Server runtime delivers the route shell.
- Server Entry → Game Flow: renders · SSR includes the interactive game on initial load.