# sabbirkhanoni/3d-web-application architecture

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

- Interactive diagram: https://gitdiagram.com/sabbirkhanoni/3d-web-application
- Repository: https://github.com/sabbirkhanoni/3d-web-application

## Overview

1. **Overall shape**
   - This is a two-part full-stack app: a **React/Vite frontend** and an **Express/MongoDB backend**.
   - The frontend handles the 3D editing experience and user-facing flows; the backend owns authentication, scene persistence, and premium subscription/payment state.

2. **Frontend boundary**
   - `frontend/src` is organized around **pages**, **layouts**, **contexts**, and reusable **components**.
   - Route-level pages cover landing, auth, password reset, scene view, and payment result states.
   - `AuthContext` and `SceneContext` are the main client-side state boundaries: auth state drives access control, while scene state drives the 3D editor and sidebar controls.

3. **3D scene subsystem**
   - The core product experience lives in `frontend/src/components/scene/SceneRoom.jsx`.
   - It uses the GLB assets in `frontend/public/models` and likely Three.js helpers to render a room, add furniture, and manipulate object positions.
   - Supporting UI in `frontend/src/components/dashboard/*` manages selected object details, object lists, and add-object dialogs, which form the editor’s control surface around the canvas.

4. **Scene data flow**
   - The scene editor maintains a list of objects with IDs, model types, and positions.
   - User actions in the 3D canvas update the scene state in the frontend, then the scene can be saved to the backend.
   - On load, the app restores the saved scene for the authenticated user, so the persisted scene is the source of truth across sessions.

5. **Authentication subsystem**
   - Auth is session-based, not token-based: the backend uses `express-session` and HTTP-only cookies.
   - `backend/controllers/auth.controller.js`, `backend/services/auth.service.js`, and `backend/routes/auth.route.js` separate HTTP handling, business logic, and routing.
   - The frontend uses protected routes via `frontend/src/layouts/ProtectRoute.jsx` and auth state from `AuthContext` to gate access to the dashboard and scene editor.

6. **Password reset and email flow**
   - Password recovery is OTP-based.
   - The backend generates and stores a temporary OTP on the user record, sends it through Resend using `backend/config/sendEmail.js` and `backend/utils/OTPSendingTemplate.js`, then validates it before allowing password reset.
   - This is a distinct backend flow from login/signup and is isolated in the auth controller/service layer.

7. **Scene persistence subsystem**
   - Scenes are stored in MongoDB through `backend/models/scene.model.js`.
   - The scene API in `backend/controllers/scene.controller.js` and `backend/services/scene.service.js` implements save/load/delete for a single user-owned scene.
   - The model structure is intentionally simple: one scene per user, with an array of object descriptors rather than a full physics or scene graph engine persisted server-side.

8. **Premium subscription subsystem**
   - Premium access is handled by SSLCommerz integration in `backend/controllers/SSLCommerzPayment.controller.js` and `backend/services/SSLCommerzPayment.service.js`.
   - Payment state is tracked in `backend/models/payment.model.js`, while `backend/validation/validationSSLCommerzPayment.js` validates gateway payloads.
   - The flow includes initiation, redirect to the gateway, success/failure/cancel callbacks, and IPN verification, with user subscription status updated in MongoDB.

9. **Backend layering and boundaries**
   - The backend is split into:
     - **routes**: request mapping,
     - **controllers**: HTTP orchestration,
     - **services**: business rules and external calls,
     - **models**: MongoDB schemas,
     - **middleware**: auth protection,
     - **config/utils/validation**: DB connection, email sending, templates, and input checks.
   - `backend/middleware/isAuthenticated.js` is the key enforcement point for protected APIs such as scene persistence and subscription initiation.

10. **External dependencies and runtime**
   - MongoDB Atlas is the persistence layer for users, scenes, and payments.
   - Resend is used for OTP email delivery.
   - SSLCommerz is the payment provider for subscription upgrades.
   - Deployment is set up for Vercel on both sides, with separate `vercel.json` files and environment-driven base URLs to connect the frontend to the backend.

11. **Client-server interaction model**
   - The frontend talks to the backend over HTTP via Axios, with credentials included so the session cookie is sent automatically.
   - Protected requests depend on that cookie; when the session is absent or invalid, the frontend route guard and backend middleware both enforce access boundaries.
   - Payment redirects and callback pages are split between backend endpoints and frontend result pages, so the browser can move between the gateway, backend validation, and user-facing status screens.

12. **Important architectural takeaway**
   - The architecture centers on a **stateful authenticated user experience**: login establishes a session, the scene editor reads/writes a per-user scene document, and subscription status changes user capabilities.
   - The 3D editor, auth system, and payment system are separate subsystems, but they converge through the user record and session identity in MongoDB.

Main entry points: [`frontend/src/routes/route.jsx`](https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/routes/route.jsx) (Routes), [`backend/services/auth.service.js`](https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/services/auth.service.js) (Auth service), [`frontend/src/layouts/ProtectRoute.jsx`](https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/layouts/ProtectRoute.jsx) (Protected route), [`frontend/src/components/scene/SceneRoom.jsx`](https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/components/scene/SceneRoom.jsx) (Scene room)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>react-app<br/>[main.jsx]"]
  node_frontend_routes["Routes<br/>page routing<br/>[route.jsx]"]
  node_frontend_auth(("Auth state<br/>context<br/>[AuthContext.jsx]"))
  node_frontend_scene_state(("Scene state<br/>context<br/>[SceneContext.jsx]"))
  node_frontend_protect{{"Protected route<br/>guard<br/>[ProtectRoute.jsx]"}}
  node_frontend_dashboard["Dashboard shell<br/>layout<br/>[Dashboard.jsx]"]
  node_frontend_landing["Landing page<br/>[LandingPage.jsx]"]
  node_frontend_login["Login flow<br/>auth pages<br/>[LoginPage.jsx]"]
  node_frontend_scene_page["Scene page<br/>editor page"]
  node_frontend_payment_pages["Payment states<br/>result pages"]
  node_frontend_scene_room["Scene room<br/>3d editor<br/>[SceneRoom.jsx]"]
  node_frontend_dashboard_ui["Editor controls<br/>sidebar ui"]
  node_frontend_assets["GLB assets<br/>3d models<br/>[home.glb]"]
end

subgraph group_backend["Backend"]
  node_backend_server["API server<br/>express app<br/>[index.js]"]
  node_backend_auth_api["Auth API<br/>auth controller<br/>[auth.controller.js]"]
  node_backend_scene_api["Scene API<br/>scene controller"]
  node_backend_payment_api["Payment API<br/>payment controller"]
  node_backend_auth_service["Auth service<br/>[auth.service.js]"]
  node_backend_scene_service["Scene service<br/>[scene.service.js]"]
  node_backend_payment_service["Payment service"]
  node_backend_auth_mw{{"Auth middleware<br/>session guard<br/>[isAuthenticated.js]"}}
  node_backend_user_model[("User model<br/>mongoose model<br/>[user.model.js]")]
  node_backend_scene_model[("Scene model<br/>mongoose model<br/>[scene.model.js]")]
  node_backend_payment_model[("Payment model<br/>mongoose model<br/>[payment.model.js]")]
end

subgraph group_storage["External data"]
  node_backend_db[("MongoDB<br/>database")]
  node_backend_email["Resend email<br/>email provider<br/>[sendEmail.js]"]
  node_backend_gateway(("SSLCommerz<br/>payment gateway"))
end

node_frontend_app -->|"boots"| node_frontend_routes
node_frontend_routes -->|"public"| node_frontend_landing
node_frontend_routes -->|"auth pages"| node_frontend_login
node_frontend_routes -->|"gates"| node_frontend_protect
node_frontend_protect -->|"allows"| node_frontend_dashboard
node_frontend_protect -->|"allows"| node_frontend_scene_page
node_frontend_dashboard -->|"hosts"| node_frontend_scene_room
node_frontend_scene_page -->|"renders"| node_frontend_scene_room
node_frontend_scene_room -->|"reads/writes"| node_frontend_scene_state
node_frontend_dashboard -->|"controls"| node_frontend_dashboard_ui
node_frontend_scene_room -->|"uses"| node_frontend_assets
node_frontend_auth -->|"drives"| node_frontend_protect
node_frontend_auth -->|"sessions"| node_backend_auth_api
node_frontend_scene_state -->|"syncs"| node_backend_scene_api
node_frontend_payment_pages -->|"receives callbacks"| node_backend_payment_api
node_backend_server -->|"routes"| node_backend_auth_api
node_backend_server -->|"routes"| node_backend_scene_api
node_backend_server -->|"routes"| node_backend_payment_api
node_backend_auth_api -->|"delegates"| node_backend_auth_service
node_backend_scene_api -->|"delegates"| node_backend_scene_service
node_backend_payment_api -->|"delegates"| node_backend_payment_service
node_backend_auth_service -->|"protects"| node_backend_auth_mw
node_backend_auth_service -->|"updates"| node_backend_user_model
node_backend_scene_service -->|"persists"| node_backend_scene_model
node_backend_payment_service -->|"persists"| node_backend_payment_model
node_backend_auth_mw -->|"validates"| node_backend_user_model
node_backend_user_model -->|"stored in"| node_backend_db
node_backend_scene_model -->|"stored in"| node_backend_db
node_backend_payment_model -->|"stored in"| node_backend_db
node_backend_auth_service -->|"sends OTP"| node_backend_email
node_backend_payment_service -->|"charges via"| node_backend_gateway

click node_frontend_app "https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/main.jsx"
click node_frontend_routes "https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/routes/route.jsx"
click node_frontend_auth "https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/context/AuthContext.jsx"
click node_frontend_scene_state "https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/context/SceneContext.jsx"
click node_frontend_protect "https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/layouts/ProtectRoute.jsx"
click node_frontend_dashboard "https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/layouts/Dashboard.jsx"
click node_frontend_landing "https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/pages/LandingPage.jsx"
click node_frontend_login "https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/pages/LoginPage.jsx"
click node_frontend_scene_page "https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/pages/SceneViewRoomPage.jsx"
click node_frontend_payment_pages "https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/pages/PaymentSuccessPage.jsx"
click node_frontend_scene_room "https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/components/scene/SceneRoom.jsx"
click node_frontend_dashboard_ui "https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/components/dashboard/SceneObjectsList.jsx"
click node_frontend_assets "https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/public/models/home.glb"
click node_backend_server "https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/index.js"
click node_backend_auth_api "https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/controllers/auth.controller.js"
click node_backend_scene_api "https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/controllers/scene.controller.js"
click node_backend_payment_api "https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/controllers/SSLCommerzPayment.controller.js"
click node_backend_auth_service "https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/services/auth.service.js"
click node_backend_scene_service "https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/services/scene.service.js"
click node_backend_payment_service "https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/services/SSLCommerzPayment.service.js"
click node_backend_auth_mw "https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/middleware/isAuthenticated.js"
click node_backend_user_model "https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/models/user.model.js"
click node_backend_scene_model "https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/models/scene.model.js"
click node_backend_payment_model "https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/models/payment.model.js"
click node_backend_email "https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/config/sendEmail.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_frontend_app,node_frontend_routes,node_frontend_auth,node_frontend_scene_state,node_frontend_protect,node_frontend_dashboard,node_frontend_landing,node_frontend_login,node_frontend_scene_page,node_frontend_payment_pages,node_frontend_scene_room,node_frontend_dashboard_ui,node_frontend_assets toneBlue
class node_backend_server,node_backend_auth_api,node_backend_scene_api,node_backend_payment_api,node_backend_auth_service,node_backend_scene_service,node_backend_payment_service,node_backend_auth_mw,node_backend_user_model,node_backend_scene_model,node_backend_payment_model toneAmber
class node_backend_db,node_backend_email,node_backend_gateway toneMint
```

## Components

### Frontend

React/Vite client for landing, auth, scene editing, and payment result views.

- [App shell](https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/main.jsx): react-app · Root client bootstrap and app wiring. · `frontend/src/main.jsx`
- [Routes](https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/routes/route.jsx): page routing · Top-level page and navigation composition. · `frontend/src/routes/route.jsx`
- [Auth state](https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/context/AuthContext.jsx): context · Session-driven auth state and client-side access control. · `frontend/src/context/AuthContext.jsx`
- [Scene state](https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/context/SceneContext.jsx): context · In-memory scene editor state shared across the UI. · `frontend/src/context/SceneContext.jsx`
- [Protected route](https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/layouts/ProtectRoute.jsx): guard · Route guard for authenticated areas. · `frontend/src/layouts/ProtectRoute.jsx`
- [Dashboard shell](https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/layouts/Dashboard.jsx): layout · Authenticated workspace frame around the editor. · `frontend/src/layouts/Dashboard.jsx`
- [Landing page](https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/pages/LandingPage.jsx): page · Public marketing and entry page. · `frontend/src/pages/LandingPage.jsx`
- [Login flow](https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/pages/LoginPage.jsx): auth pages · Sign-in, signup, OTP, and password reset views. · `frontend/src/pages/LoginPage.jsx`
- [Scene page](https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/pages/SceneViewRoomPage.jsx): editor page · Authenticated 3D scene editor entry point. · `frontend/src/pages/SceneViewRoomPage.jsx`
- [Payment states](https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/pages/PaymentSuccessPage.jsx): result pages · Success, failure, and cancel screens after gateway redirects. · `frontend/src/pages/PaymentSuccessPage.jsx`
- [Scene room](https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/components/scene/SceneRoom.jsx): 3d editor · Core 3D room and object manipulation experience. · `frontend/src/components/scene/SceneRoom.jsx`
- [Editor controls](https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/src/components/dashboard/SceneObjectsList.jsx): sidebar ui · Object lists, selection details, and add-object dialogs. · `frontend/src/components/dashboard/SceneObjectsList.jsx`
- [GLB assets](https://github.com/sabbirkhanoni/3d-web-application/blob/main/frontend/public/models/home.glb): 3d models · Furniture and room assets consumed by the scene editor. · `frontend/public/models/home.glb`

### Backend

Express API for auth, scene persistence, and subscription payments.

- [API server](https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/index.js): express app · Backend runtime and route mounting. · `backend/index.js`
- [Auth API](https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/controllers/auth.controller.js): auth controller · Login, signup, session, and password-reset orchestration. · `backend/controllers/auth.controller.js`
- [Scene API](https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/controllers/scene.controller.js): scene controller · Save, load, and delete the per-user scene document. · `backend/controllers/scene.controller.js`
- [Payment API](https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/controllers/SSLCommerzPayment.controller.js): payment controller · SSLCommerz initiation and callback handling. · `backend/controllers/SSLCommerzPayment.controller.js`
- [Auth service](https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/services/auth.service.js): auth service · Business logic for sessions, OTP, and user updates. · `backend/services/auth.service.js`
- [Scene service](https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/services/scene.service.js): scene service · Scene persistence rules and user-scene coordination. · `backend/services/scene.service.js`
- [Payment service](https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/services/SSLCommerzPayment.service.js): payment service · Gateway integration and subscription state changes. · `backend/services/SSLCommerzPayment.service.js`
- [Auth middleware](https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/middleware/isAuthenticated.js): session guard · Protects private APIs using the session cookie. · `backend/middleware/isAuthenticated.js`
- [User model](https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/models/user.model.js): mongoose model · User record with session, OTP, and subscription fields. · `backend/models/user.model.js`
- [Scene model](https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/models/scene.model.js): mongoose model · Single saved scene per user with object descriptors. · `backend/models/scene.model.js`
- [Payment model](https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/models/payment.model.js): mongoose model · Subscription and transaction state storage. · `backend/models/payment.model.js`

### External data

Persistent and third-party systems used by the app.

- **MongoDB**: database · Persistent store for users, scenes, and payments.
- [Resend email](https://github.com/sabbirkhanoni/3d-web-application/blob/main/backend/config/sendEmail.js): email provider · OTP delivery for password recovery. · `backend/config/sendEmail.js`
- **SSLCommerz**: payment gateway · External payment provider for premium subscription flows.

## Connections

- App shell → Routes: boots · App renders the client route structure.
- Routes → Landing page: public · Landing page is available to unauthenticated users.
- Routes → Login flow: auth pages · Route set includes login, signup, OTP, and reset pages.
- Routes → Protected route: gates · Protected routes wrap private app areas.
- Protected route → Dashboard shell: allows · Authenticated users enter the dashboard shell.
- Protected route → Scene page: allows · Scene editor is behind auth protection.
- Dashboard shell → Scene room: hosts · Dashboard contains the main 3D editor surface.
- Scene page → Scene room: renders · Scene page mounts the room editor.
- Scene room → Scene state: reads/writes · Canvas interactions update shared scene state.
- Dashboard shell → Editor controls: controls · Sidebar controls manage selected objects and adding items.
- Scene room → GLB assets: uses · Room and furniture models are loaded into the scene.
- Auth state → Protected route: drives · Auth state determines access to private routes.
- Auth state → Auth API: sessions · Client authenticates against the backend session flow.
- Scene state → Scene API: syncs · Saved scene data is exchanged with the scene API.
- Payment states → Payment API: receives callbacks · Browser lands on payment result pages after gateway flow.
- API server → Auth API: routes · Server mounts auth endpoints.
- API server → Scene API: routes · Server mounts scene endpoints.
- API server → Payment API: routes · Server mounts payment endpoints.
- Auth API → Auth service: delegates · Controller pushes auth business logic into the service layer.
- Scene API → Scene service: delegates · Controller pushes scene operations into the service layer.
- Payment API → Payment service: delegates · Controller pushes gateway work into the service layer.
- Auth service → Auth middleware: protects · Auth-related protected endpoints rely on session checks.
- Auth service → User model: updates · User record holds session and OTP-related state.
- Scene service → Scene model: persists · Scene documents are stored per user.
- Payment service → Payment model: persists · Payment and subscription state are recorded.
- Auth middleware → User model: validates · Middleware resolves the active user from the session.
- User model → MongoDB: stored in · User data lives in MongoDB.
- Scene model → MongoDB: stored in · Scene documents live in MongoDB.
- Payment model → MongoDB: stored in · Payment documents live in MongoDB.
- Auth service → Resend email: sends OTP · Password reset OTPs are delivered by email.
- Payment service → SSLCommerz: charges via · Subscription checkout is handled by SSLCommerz.