# akash-design-prog/dice-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/akash-design-prog/dice-simulator
- Repository: https://github.com/akash-design-prog/dice-simulator

## Overview

1. **Repository shape**
   - This is a monorepo with two runtime boundaries: a **Node/Express backend** in `backend/` and a **React/Vite frontend** in `frontend/`.
   - Root-level `vercel.json` ties them together for deployment, serving the frontend build and routing API requests to the backend.

2. **Primary architecture**
   - The product is a **browser-based dice simulator**.
   - The frontend owns the visual experience and user interaction.
   - The backend owns the source of randomness, which the README explicitly positions as the trust boundary for “server-side truth.”

3. **Backend subsystem**
   - `backend/server.js` is the server entrypoint.
   - It is a lightweight Node.js/Express service whose main architectural role is to produce dice results that cannot be tampered with in the browser.
   - There is no database or long-lived persistence in the current tree, so the backend appears stateless.

4. **Frontend application**
   - `frontend/src/` contains the React app.
   - `App.jsx` is the top-level UI/scene composition layer; `main.jsx` mounts it into the page.
   - The frontend is built with Vite and styled with Tailwind CSS, with local CSS files for app-specific layout and polish.

5. **3D rendering and simulation boundary**
   - The README says the dice are rendered with **Three.js / React Three Fiber**.
   - That means the dice animation and scene lighting are fully client-side WebGL concerns, separate from the server’s randomness logic.
   - The backend does not render graphics; it only supplies the roll outcome that the client then visualizes.

6. **Roll flow**
   - User interaction starts in the browser.
   - The frontend requests a new roll from the backend.
   - The backend returns the result.
   - The frontend uses that result to drive the 3D animation and final face selection, creating the “fair roll” experience.

7. **Visual and material system**
   - The README describes dynamic face textures generated with **HTML5 Canvas**, so dice faces are created at runtime rather than shipped as many static image assets.
   - The dice appearance uses `meshStandardMaterial` with tuned roughness/metalness, and scene lighting is handled in the frontend to create the acrylic/polished look.
   - This is a client-only rendering concern and does not affect the backend.

8. **Audio asset path**
   - `frontend/public/sounds_roll.ogg` is a browser-delivered asset used for roll sound effects.
   - Because it lives under `public/`, it is served statically by the frontend build and consumed directly by the UI during the roll interaction.

9. **Build and tooling boundaries**
   - The frontend uses **Vite** for development and production bundling.
   - Tailwind config, PostCSS config, and ESLint config indicate the frontend has its own build/tooling stack independent of the backend.
   - The backend has its own `package.json` and lockfile, so it is separately installable and runnable.

10. **Deployment model**
   - `vercel.json` suggests a deployment where the frontend is built to static files and the backend is exposed as serverless/route-backed Node code.
   - This matters architecturally because the same repo contains both a static SPA and an API service, but they are deployed through different Vercel targets.

11. **State and future expansion**
   - The current system is intentionally minimal: no visible storage layer, auth layer, or analytics pipeline.
   - The TODO in the README mentions future MongoDB support for global statistics, which would add a new persistence subsystem if implemented.
   - For now, the architecture is best understood as **stateless API + client-side simulation**.

12. **How to diagram it**
   - Draw two main boxes: **Browser frontend** and **Node backend**.
   - Inside the browser box, separate **React UI**, **Three.js/WebGL scene**, and **static assets/audio**.
   - Between browser and backend, show a **roll request / random result** flow.
   - Around both, note the **Vercel monorepo deployment boundary** that serves the SPA and routes API traffic.

Main entry points: [`frontend/src/App.jsx`](https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/src/App.jsx) (App UI), [`frontend/package.json`](https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/package.json) (Frontend pkg), [`backend/server.js`](https://github.com/akash-design-prog/dice-simulator/blob/main/backend/server.js) (API server), [`vercel.json`](https://github.com/akash-design-prog/dice-simulator/blob/main/vercel.json) (Vercel config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Deployment"]
  node_vercel["Vercel config<br/>deploy routing<br/>[vercel.json]"]
  node_rootpkg["Root package<br/>monorepo scripts<br/>[package.json]"]
end

subgraph group_backend["Backend"]
  node_backendpkg["Backend pkg<br/>node service<br/>[package.json]"]
  node_server["API server<br/>express service<br/>[server.js]"]
end

subgraph group_browser["Browser App"]
  node_frontendpkg["Frontend pkg<br/>web app<br/>[package.json]"]
  node_vite["Vite build<br/>bundler<br/>[vite.config.js]"]
  node_tailwind["Tailwind<br/>styling system<br/>[tailwind.config.js]"]
  node_html["Index page<br/>spa shell<br/>[index.html]"]
  node_main["App mount<br/>react entry<br/>[main.jsx]"]
  node_app["App UI<br/>react scene<br/>[App.jsx]"]
  node_scene{{"3D scene<br/>webgl rendering<br/>[App.jsx]"}}
  node_styles["App styles<br/>css<br/>[App.css]"]
  node_basecss["Base styles<br/>css<br/>[index.css]"]
  node_sound["Roll sound<br/>static asset<br/>[sounds_roll.ogg]"]
end

node_rootpkg -->|"workspace install"| node_backendpkg
node_rootpkg -->|"workspace install"| node_frontendpkg
node_vercel -->|"serve SPA"| node_frontendpkg
node_vercel -->|"route API"| node_server
node_backendpkg -->|"runtime"| node_server
node_frontendpkg -->|"builds with"| node_vite
node_frontendpkg -->|"styles with"| node_tailwind
node_frontendpkg -->|"shell"| node_html
node_html -->|"loads"| node_main
node_main -->|"mounts"| node_app
node_app -->|"renders"| node_scene
node_app -->|"uses"| node_styles
node_app -->|"inherits"| node_basecss
node_app -->|"plays"| node_sound
node_app -->|"requests roll"| node_server
node_server -.->|"returns result"| node_scene

click node_vercel "https://github.com/akash-design-prog/dice-simulator/blob/main/vercel.json"
click node_rootpkg "https://github.com/akash-design-prog/dice-simulator/blob/main/package.json"
click node_backendpkg "https://github.com/akash-design-prog/dice-simulator/blob/main/backend/package.json"
click node_server "https://github.com/akash-design-prog/dice-simulator/blob/main/backend/server.js"
click node_frontendpkg "https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/package.json"
click node_vite "https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/vite.config.js"
click node_tailwind "https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/tailwind.config.js"
click node_html "https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/index.html"
click node_main "https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/src/main.jsx"
click node_app "https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/src/App.jsx"
click node_scene "https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/src/App.jsx"
click node_styles "https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/src/App.css"
click node_basecss "https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/src/index.css"
click node_sound "https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/public/sounds_roll.ogg"

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_vercel,node_rootpkg toneBlue
class node_backendpkg,node_server toneAmber
class node_frontendpkg,node_vite,node_tailwind,node_html,node_main,node_app,node_scene,node_styles,node_basecss,node_sound toneMint
```

## Components

### Deployment

Repo-level Vercel routing and build boundary

- [Vercel config](https://github.com/akash-design-prog/dice-simulator/blob/main/vercel.json): deploy routing · Routes the frontend build and API traffic for deployment · `vercel.json`
- [Root package](https://github.com/akash-design-prog/dice-simulator/blob/main/package.json): monorepo scripts · Top-level package entry for repo-wide install and orchestration · `package.json`

### Backend

Stateless Node/Express roll service

- [Backend pkg](https://github.com/akash-design-prog/dice-simulator/blob/main/backend/package.json): node service · Backend dependency boundary and runtime packaging · `backend/package.json`
- [API server](https://github.com/akash-design-prog/dice-simulator/blob/main/backend/server.js): express service · Node/Express entrypoint that returns tamper-resistant roll results · `backend/server.js`

### Browser App

React, WebGL, and static assets in the client

- [Frontend pkg](https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/package.json): web app · Frontend dependency boundary and build packaging · `frontend/package.json`
- [Vite build](https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/vite.config.js): bundler · Development server and production bundling for the SPA · `frontend/vite.config.js`
- [Tailwind](https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/tailwind.config.js): styling system · Utility styling pipeline for the frontend · `frontend/tailwind.config.js`
- [Index page](https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/index.html): spa shell · Static HTML entry used by the Vite app · `frontend/index.html`
- [App mount](https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/src/main.jsx): react entry · Mounts the React application into the page · `frontend/src/main.jsx`
- [App UI](https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/src/App.jsx): react scene · Top-level UI composition and roll interaction flow · `frontend/src/App.jsx`
- [3D scene](https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/src/App.jsx): webgl rendering · Client-side dice animation, lighting, and face selection · `frontend/src/App.jsx`
- [App styles](https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/src/App.css): css · App-specific layout and polish styles · `frontend/src/App.css`
- [Base styles](https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/src/index.css): css · Global frontend styling foundation · `frontend/src/index.css`
- [Roll sound](https://github.com/akash-design-prog/dice-simulator/blob/main/frontend/public/sounds_roll.ogg): static asset · Browser-delivered roll audio used during interaction · `frontend/public/sounds_roll.ogg`

## Connections

- Root package → Backend pkg: workspace install · Repo-level package management includes the backend runtime
- Root package → Frontend pkg: workspace install · Repo-level package management includes the frontend runtime
- Vercel config → Frontend pkg: serve SPA · Deployment serves the frontend build as the browser entry
- Vercel config → API server: route API · Deployment forwards API requests to the backend service
- Backend pkg → API server: runtime · Backend package defines the Express server runtime
- Frontend pkg → Vite build: builds with · Frontend uses Vite for dev and production bundling
- Frontend pkg → Tailwind: styles with · Frontend styling pipeline is driven by Tailwind
- Frontend pkg → Index page: shell · The SPA is bootstrapped from the HTML entry page
- Index page → App mount: loads · The index page loads the React entrypoint
- App mount → App UI: mounts · React entry mounts the top-level application
- App UI → 3D scene: renders · App composition drives the 3D dice experience
- App UI → App styles: uses · App-specific CSS shapes the UI layout
- App UI → Base styles: inherits · Global base styles support the application shell
- App UI → Roll sound: plays · Roll interaction uses the browser audio asset
- App UI → API server: requests roll · Frontend asks the backend for the authoritative dice result
- API server → 3D scene: returns result · Backend roll output drives the client-side animation and final face