# ajgour-hue/velix architecture

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

- Interactive diagram: https://gitdiagram.com/ajgour-hue/velix
- Repository: https://github.com/ajgour-hue/velix

## Overview

1. This repository is split into two deployable halves: a Node/Express backend under `backend/` and a React/Vite frontend under `frontend/`. The architecture is a classic API-driven SPA: the frontend owns the UI and state, while the backend exposes JSON endpoints and persists data.

2. The backend entrypoint is `backend/server.js`, which boots the Express app defined in `backend/src/app.js`. Configuration is separated into `backend/src/config/` with one file for app/env config and one for database connection, so startup concerns are isolated from request handling.

3. Backend request handling is layered by responsibility:
   - `routes/` defines endpoint groups
   - `middleware/` adds cross-cutting concerns like auth protection
   - `validator/` validates request payloads
   - `controller/` contains HTTP-level handlers
   - `dao/` and `service/` encapsulate persistence or external integration
   - `models/` define the database schema objects

4. The data model suggests a MongoDB/Mongoose-style backend. The presence of `user.model.js`, `product.model.js`, `cart.model.js`, and `price.schema.js` indicates document-based entities with embedded price details. That structure is likely central to the product and cart flows.

5. The auth subsystem is isolated in `auth.routes.js`, `auth.controller.js`, `auth.validator.js`, and `auth.middleware.js`. This makes auth a separate boundary from commerce features. The frontend also has a `ContinueWithGoogle` component, so the auth flow likely includes a Google sign-in path in addition to local login/register.

6. The product subsystem is the most feature-rich backend area. It has its own controller, route, validator, DAO, and a `storage.service.js`, which strongly suggests product creation/editing can involve file upload or image storage. The frontend product pages reinforce this: home/catalog, product detail, seller detail, create product, and dashboard.

7. The cart subsystem is similarly isolated with its own controller, routes, validator, and model. That separation implies cart operations are user-scoped and API-driven, probably reading/writing the authenticated user’s cart state against the database.

8. On the frontend, the app is organized by feature rather than by technical type. Each domain area has its own `service/`, `state/`, `hook/`, and `pages/` directories under `features/auth`, `features/cart`, and `features/product`. That structure makes the UI diagram straightforward: each feature owns its API calls, Redux slice, and page-level screens.

9. `frontend/src/app/` provides the shell: `App.jsx`, `AppLayout.jsx`, `app.routes.jsx`, and `app.store.js`. This is the composition layer that wires routing, global layout, and the Redux store together. `shared/Nav.jsx` is a reusable navigation component used across pages.

10. The frontend data flow is Redux-centered. Page components call feature hooks, hooks coordinate UI logic and dispatch actions, service modules talk to backend API endpoints, and feature slices store server results and UI state. That means most server interaction is normalized through the store rather than directly embedded in page components.

11. Route protection exists on the client side as well. `features/auth/component/Protected.jsx` suggests route guards or conditional rendering based on auth state, so authenticated routes like cart, product creation, or seller dashboard are likely gated in the UI before requests are even made.

12. The overall end-to-end flow is: user action in a page → feature hook → API service → backend route → validator/middleware → controller → DAO/model/storage → response back to frontend slice → UI update. This layered pipeline is the main architecture boundary worth drawing.

13. In infrastructure terms, the runtime split is Node.js for the API server and React/Vite for the browser app. The backend likely connects to a database service and possibly a storage provider for product assets, while the frontend communicates with the backend only through HTTP APIs.

14. If you are drawing the architecture diagram, the key subsystems to show are: Auth, Products, Cart, shared backend config/database, and the frontend shell with feature slices. The main external dependency to highlight is the database, plus any storage/OAuth integration implied by product uploads and Google sign-in.

Main entry points: [`backend/src/app.js`](https://github.com/ajgour-hue/velix/blob/main/backend/src/app.js) (Express App), [`frontend/src/app/App.jsx`](https://github.com/ajgour-hue/velix/blob/main/frontend/src/app/App.jsx) (App Shell), [`frontend/src/features/auth/pages/Login.jsx`](https://github.com/ajgour-hue/velix/blob/main/frontend/src/features/auth/pages/Login.jsx) (Auth UI), [`backend/src/routes/product.routes.js`](https://github.com/ajgour-hue/velix/blob/main/backend/src/routes/product.routes.js) (Product Stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_server["Server<br/>entrypoint<br/>[server.js]"]
  node_backend_app["Express App<br/>app shell<br/>[app.js]"]
  node_backend_config["Config<br/>[config.js]"]
  node_backend_db["DB Connect<br/>database setup<br/>[db.js]"]
  node_backend_auth["Auth Stack<br/>api feature<br/>[auth.routes.js]"]
  node_backend_product["Product Stack<br/>api feature<br/>[product.routes.js]"]
  node_backend_cart["Cart Stack<br/>api feature<br/>[cart.routes.js]"]
  node_backend_models[("Models<br/>mongo schemas<br/>[product.model.js]")]
  node_backend_storage["Storage<br/>asset service<br/>[storage.service.js]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_shell["App Shell<br/>spa shell<br/>[App.jsx]"]
  node_frontend_nav["Nav<br/>shared UI<br/>[Nav.jsx]"]
  node_frontend_auth["Auth UI<br/>feature stack<br/>[Login.jsx]"]
  node_frontend_auth_guard["Route Guard<br/>auth ui<br/>[Protected.jsx]"]
  node_frontend_cart["Cart UI<br/>feature stack<br/>[Cart.jsx]"]
  node_frontend_product["Product UI<br/>feature stack<br/>[Home.jsx]"]
end

subgraph group_external["External"]
  node_external_db[("Database<br/>mongo backend")]
  node_external_oauth(("Google Auth<br/>oauth provider"))
  node_external_storage[("File Storage<br/>asset backend")]
end

node_backend_server -->|"boots"| node_backend_app
node_backend_app -->|"loads"| node_backend_config
node_backend_app -->|"connects"| node_backend_db
node_backend_app -->|"mounts"| node_backend_auth
node_backend_app -->|"mounts"| node_backend_product
node_backend_app -->|"mounts"| node_backend_cart
node_backend_auth -->|"reads user"| node_backend_models
node_backend_product -->|"reads products"| node_backend_models
node_backend_product -->|"uploads"| node_backend_storage
node_backend_cart -->|"reads cart"| node_backend_models
node_backend_db -->|"uses"| node_external_db
node_backend_storage -->|"uses"| node_external_storage
node_frontend_shell -->|"composes"| node_frontend_nav
node_frontend_shell -->|"routes"| node_frontend_auth
node_frontend_shell -->|"routes"| node_frontend_cart
node_frontend_shell -->|"routes"| node_frontend_product
node_frontend_auth -->|"uses"| node_frontend_auth_guard
node_frontend_auth -->|"signs in"| node_external_oauth
node_frontend_cart -->|"calls api"| node_backend_cart
node_frontend_product -->|"calls api"| node_backend_product
node_frontend_auth -->|"calls api"| node_backend_auth

click node_backend_server "https://github.com/ajgour-hue/velix/blob/main/backend/server.js"
click node_backend_app "https://github.com/ajgour-hue/velix/blob/main/backend/src/app.js"
click node_backend_config "https://github.com/ajgour-hue/velix/blob/main/backend/src/config/config.js"
click node_backend_db "https://github.com/ajgour-hue/velix/blob/main/backend/src/config/db.js"
click node_backend_auth "https://github.com/ajgour-hue/velix/blob/main/backend/src/routes/auth.routes.js"
click node_backend_product "https://github.com/ajgour-hue/velix/blob/main/backend/src/routes/product.routes.js"
click node_backend_cart "https://github.com/ajgour-hue/velix/blob/main/backend/src/routes/cart.routes.js"
click node_backend_models "https://github.com/ajgour-hue/velix/blob/main/backend/src/models/product.model.js"
click node_backend_storage "https://github.com/ajgour-hue/velix/blob/main/backend/src/service/storage.service.js"
click node_frontend_shell "https://github.com/ajgour-hue/velix/blob/main/frontend/src/app/App.jsx"
click node_frontend_nav "https://github.com/ajgour-hue/velix/blob/main/frontend/src/features/shared/Nav.jsx"
click node_frontend_auth "https://github.com/ajgour-hue/velix/blob/main/frontend/src/features/auth/pages/Login.jsx"
click node_frontend_auth_guard "https://github.com/ajgour-hue/velix/blob/main/frontend/src/features/auth/component/Protected.jsx"
click node_frontend_cart "https://github.com/ajgour-hue/velix/blob/main/frontend/src/features/cart/pages/Cart.jsx"
click node_frontend_product "https://github.com/ajgour-hue/velix/blob/main/frontend/src/features/product/pages/Home.jsx"

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_backend_server,node_backend_app,node_backend_config,node_backend_db,node_backend_auth,node_backend_product,node_backend_cart,node_backend_models,node_backend_storage toneBlue
class node_frontend_shell,node_frontend_nav,node_frontend_auth,node_frontend_auth_guard,node_frontend_cart,node_frontend_product toneAmber
class node_external_db,node_external_oauth,node_external_storage toneMint
```

## Components

### Backend

Node/Express API and persistence layer

- [Server](https://github.com/ajgour-hue/velix/blob/main/backend/server.js): entrypoint · Starts the backend process · `backend/server.js`
- [Express App](https://github.com/ajgour-hue/velix/blob/main/backend/src/app.js): app shell · Express middleware and route wiring · `backend/src/app.js`
- [Config](https://github.com/ajgour-hue/velix/blob/main/backend/src/config/config.js): env/db config · Runtime settings and database bootstrap · `backend/src/config/config.js`
- [DB Connect](https://github.com/ajgour-hue/velix/blob/main/backend/src/config/db.js): database setup · Database connection initialization · `backend/src/config/db.js`
- [Auth Stack](https://github.com/ajgour-hue/velix/blob/main/backend/src/routes/auth.routes.js): api feature · Auth routes, controller, validation, and middleware · `backend/src/routes/auth.routes.js`
- [Product Stack](https://github.com/ajgour-hue/velix/blob/main/backend/src/routes/product.routes.js): api feature · Product routes, controller, validation, and DAO · `backend/src/routes/product.routes.js`
- [Cart Stack](https://github.com/ajgour-hue/velix/blob/main/backend/src/routes/cart.routes.js): api feature · Cart routes, controller, and validation · `backend/src/routes/cart.routes.js`
- [Models](https://github.com/ajgour-hue/velix/blob/main/backend/src/models/product.model.js): mongo schemas · User, product, cart, and price documents · `backend/src/models/product.model.js`
- [Storage](https://github.com/ajgour-hue/velix/blob/main/backend/src/service/storage.service.js): asset service · Product asset upload or file storage integration · `backend/src/service/storage.service.js`

### Frontend

React/Vite SPA and feature state

- [App Shell](https://github.com/ajgour-hue/velix/blob/main/frontend/src/app/App.jsx): spa shell · Root app composition, routes, layout, and store · `frontend/src/app/App.jsx`
- [Nav](https://github.com/ajgour-hue/velix/blob/main/frontend/src/features/shared/Nav.jsx): shared UI · Reusable navigation component · `frontend/src/features/shared/Nav.jsx`
- [Auth UI](https://github.com/ajgour-hue/velix/blob/main/frontend/src/features/auth/pages/Login.jsx): feature stack · Login, register, auth hook, service, and state · `frontend/src/features/auth/pages/Login.jsx`
- [Route Guard](https://github.com/ajgour-hue/velix/blob/main/frontend/src/features/auth/component/Protected.jsx): auth ui · Client-side protected route gating and Google sign-in · `frontend/src/features/auth/component/Protected.jsx`
- [Cart UI](https://github.com/ajgour-hue/velix/blob/main/frontend/src/features/cart/pages/Cart.jsx): feature stack · Cart page, hook, service, and state · `frontend/src/features/cart/pages/Cart.jsx`
- [Product UI](https://github.com/ajgour-hue/velix/blob/main/frontend/src/features/product/pages/Home.jsx): feature stack · Catalog, detail, create, dashboard, and seller views · `frontend/src/features/product/pages/Home.jsx`

### External

Runtime dependencies and integrations

- **Database**: mongo backend · Persistent document store
- **Google Auth**: oauth provider · Google sign-in integration
- **File Storage**: asset backend · External asset storage for product uploads

## Connections

- Server → Express App: boots · Server starts the Express app
- Express App → Config: loads · App reads runtime configuration
- Express App → DB Connect: connects · App initializes database connectivity
- Express App → Auth Stack: mounts · Auth routes are registered on the app
- Express App → Product Stack: mounts · Product routes are registered on the app
- Express App → Cart Stack: mounts · Cart routes are registered on the app
- Auth Stack → Models: reads user · Auth logic persists or checks user records
- Product Stack → Models: reads products · Product flows use document models
- Product Stack → Storage: uploads · Product creation can use storage integration
- Cart Stack → Models: reads cart · Cart flows persist user cart documents
- DB Connect → Database: uses · Database connection targets the external store
- Storage → File Storage: uses · Storage service delegates to an external backend
- App Shell → Nav: composes · Shell includes shared navigation
- App Shell → Auth UI: routes · App routes render auth screens
- App Shell → Cart UI: routes · App routes render cart screens
- App Shell → Product UI: routes · App routes render product screens
- Auth UI → Route Guard: uses · Auth feature includes protected UI and Google sign-in
- Auth UI → Google Auth: signs in · Google login is an external auth path
- Cart UI → Cart Stack: calls api · Cart UI talks to cart endpoints
- Product UI → Product Stack: calls api · Product UI talks to product endpoints
- Auth UI → Auth Stack: calls api · Auth UI talks to auth endpoints
