akash-design-prog/dice-simulator

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.