# arifictedge/gadgethub architecture

> Architecture diagram of the GitHub repository arifictedge/gadgethub, 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/arifictedge/gadgethub
- Repository: https://github.com/arifictedge/gadgethub

## Overview

1. **Repo shape / deployment boundary**  
   GadgetHub is split into three runtime areas: `frontend/` for the React client, `backend/` for the Express + MongoDB API, and `api/` plus `vercel.json` for Vercel/serverless deployment glue. This is a decoupled frontend-backend architecture rather than a single monolith.

2. **Client application shell**  
   The React app is Vite-based and starts in `frontend/src/main.jsx`, with `App.jsx` handling top-level routing and composition. Global styling comes from Tailwind (`tailwind.config.js`, `index.css`), and the app is organized around pages plus reusable layout/product components.

3. **Frontend presentation layer**  
   The UI is split into reusable layout pieces (`Navbar`, `Footer`, `Layout`, `MobileBottomNav`, `FloatingActions`) and domain components like `ProductCard`. This suggests the visual shell is shared across pages, while product and commerce views are composed from smaller widgets.

4. **Client-side state boundaries**  
   `AuthContext` and `CartContext` are the main client-wide state containers. Authentication and cart state are not kept inside individual pages; they are lifted into context so product listing, checkout, navbar, dashboard, and admin views can all read/update them consistently.

5. **Frontend feature pages**  
   The pages map directly to commerce flows: browsing (`Home`, `Products`, `Categories`, `ProductDetail`, `Compare`), transaction flow (`Cart`, `Checkout`), auth (`Login`, `Register`), account (`UserDashboard`), and admin operations (`AdminDashboard`, `AdminProducts`, `AdminOrders`, `AdminUsers`). This gives a clear separation between customer-facing and staff-facing areas.

6. **API access pattern**  
   `frontend/src/lib/api.js` is the client’s dedicated API boundary. All server communication should flow through this helper rather than being scattered across components, which centralizes base URL handling and request behavior.

7. **Backend request pipeline**  
   The backend is a conventional Express service with `src/index.js` as the entry point and `src/app.js` as the app wiring layer. Routing is separated from business logic: route files dispatch to controllers, and controllers implement the actual product, order, auth, and user operations.

8. **Backend domain model layer**  
   MongoDB data is modeled with Mongoose in `src/models/` for `Product`, `User`, and `Order`. Those three models define the core commerce entities and are the main persistence boundary for the system.

9. **Security and cross-cutting middleware**  
   `authMiddleware.js` guards protected routes, especially for authenticated user and admin operations. `errorMiddleware.js` centralizes API error handling, which keeps controller logic cleaner and makes the backend behavior more uniform.

10. **Operational scripts and data hygiene**  
   `seed.js` supports initial database population, and `migrateSlugs.js` exists for SEO-friendly product URL maintenance. The README’s mention of JWT, bcrypt, CORS, and rate limiting indicates the backend also handles stateless auth and API hardening as first-class concerns.

11. **Main data flow**  
   A typical request path is: user action in the React page → shared UI/context state → `api.js` request → Express route → controller → Mongoose model → MongoDB → JSON response back to the client. Authentication adds a JWT check in middleware before sensitive order/user/admin endpoints are processed.

Main entry points: [`frontend/src/App.jsx`](https://github.com/arifictedge/gadgethub/blob/main/frontend/src/App.jsx) (App shell), [`frontend/src/lib/api.js`](https://github.com/arifictedge/gadgethub/blob/main/frontend/src/lib/api.js) (API client), [`frontend/src/components/layout/Layout.jsx`](https://github.com/arifictedge/gadgethub/blob/main/frontend/src/components/layout/Layout.jsx) (Layout shell), [`backend/src/app.js`](https://github.com/arifictedge/gadgethub/blob/main/backend/src/app.js) (App wiring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_main["Main entry<br/>Vite bootstrap<br/>[main.jsx]"]
  node_frontend_app["App shell<br/>routing shell<br/>[App.jsx]"]
  node_frontend_layout["Layout shell<br/>shared chrome<br/>[Layout.jsx]"]
  node_frontend_navbar["Navbar<br/>header component<br/>[Navbar.jsx]"]
  node_frontend_footer["Footer<br/>layout component<br/>[Footer.jsx]"]
  node_frontend_mobile_nav["Mobile nav<br/>navigation component"]
  node_frontend_product_card["Product card<br/>catalog widget<br/>[ProductCard.jsx]"]
  node_frontend_auth_context["Auth state<br/>React context<br/>[AuthContext.jsx]"]
  node_frontend_cart_context["Cart state<br/>React context<br/>[CartContext.jsx]"]
  node_frontend_api["API client<br/>request helper<br/>[api.js]"]
  node_frontend_pages["Customer pages<br/>feature pages"]
  node_frontend_admin_pages["Admin pages<br/>staff pages"]
end

subgraph group_backend["Backend"]
  node_backend_index["Server entry<br/>Express bootstrap<br/>[index.js]"]
  node_backend_app["App wiring<br/>Express app<br/>[app.js]"]
  node_backend_routes["Routes<br/>HTTP routing"]
  node_backend_controllers["Controllers<br/>business logic"]
  node_backend_models[("Data models<br/>Mongoose models")]
  node_backend_auth_mw["Auth guard<br/>middleware<br/>[authMiddleware.js]"]
  node_backend_error_mw["Error handler<br/>middleware<br/>[errorMiddleware.js]"]
  node_backend_db[("MongoDB<br/>database<br/>[db.js]")]
end

subgraph group_deployment["Deployment"]
  node_deployment_api["Vercel API<br/>serverless entry<br/>[index.js]"]
  node_deployment_config["Vercel config<br/>deployment config<br/>[vercel.json]"]
end

node_frontend_main -->|"bootstraps"| node_frontend_app
node_frontend_app -->|"uses"| node_frontend_layout
node_frontend_layout -->|"contains"| node_frontend_navbar
node_frontend_layout -->|"contains"| node_frontend_footer
node_frontend_layout -->|"contains"| node_frontend_mobile_nav
node_frontend_app -->|"routes"| node_frontend_pages
node_frontend_app -->|"routes"| node_frontend_admin_pages
node_frontend_app -->|"reads"| node_frontend_auth_context
node_frontend_app -->|"reads"| node_frontend_cart_context
node_frontend_pages -->|"composes"| node_frontend_product_card
node_frontend_pages -->|"calls"| node_frontend_api
node_frontend_admin_pages -->|"calls"| node_frontend_api
node_frontend_auth_context -->|"auth flow"| node_frontend_api
node_frontend_cart_context -->|"cart flow"| node_frontend_api
node_frontend_api -->|"requests"| node_deployment_api
node_deployment_api -->|"uses"| node_deployment_config
node_deployment_api -->|"invokes"| node_backend_index
node_backend_index -->|"starts"| node_backend_app
node_backend_app -->|"mounts"| node_backend_routes
node_backend_routes -->|"dispatches"| node_backend_controllers
node_backend_controllers -->|"reads/writes"| node_backend_models
node_backend_models -->|"persists"| node_backend_db
node_backend_routes -->|"protects"| node_backend_auth_mw
node_backend_app -->|"handles"| node_backend_error_mw
node_backend_app -->|"connects"| node_backend_db

click node_frontend_main "https://github.com/arifictedge/gadgethub/blob/main/frontend/src/main.jsx"
click node_frontend_app "https://github.com/arifictedge/gadgethub/blob/main/frontend/src/App.jsx"
click node_frontend_layout "https://github.com/arifictedge/gadgethub/blob/main/frontend/src/components/layout/Layout.jsx"
click node_frontend_navbar "https://github.com/arifictedge/gadgethub/blob/main/frontend/src/components/layout/Navbar.jsx"
click node_frontend_footer "https://github.com/arifictedge/gadgethub/blob/main/frontend/src/components/layout/Footer.jsx"
click node_frontend_mobile_nav "https://github.com/arifictedge/gadgethub/blob/main/frontend/src/components/layout/MobileBottomNav.jsx"
click node_frontend_product_card "https://github.com/arifictedge/gadgethub/blob/main/frontend/src/components/product/ProductCard.jsx"
click node_frontend_auth_context "https://github.com/arifictedge/gadgethub/blob/main/frontend/src/context/AuthContext.jsx"
click node_frontend_cart_context "https://github.com/arifictedge/gadgethub/blob/main/frontend/src/context/CartContext.jsx"
click node_frontend_api "https://github.com/arifictedge/gadgethub/blob/main/frontend/src/lib/api.js"
click node_backend_index "https://github.com/arifictedge/gadgethub/blob/main/backend/src/index.js"
click node_backend_app "https://github.com/arifictedge/gadgethub/blob/main/backend/src/app.js"
click node_backend_auth_mw "https://github.com/arifictedge/gadgethub/blob/main/backend/src/middlewares/authMiddleware.js"
click node_backend_error_mw "https://github.com/arifictedge/gadgethub/blob/main/backend/src/middlewares/errorMiddleware.js"
click node_backend_db "https://github.com/arifictedge/gadgethub/blob/main/backend/src/config/db.js"
click node_deployment_api "https://github.com/arifictedge/gadgethub/blob/main/api/index.js"
click node_deployment_config "https://github.com/arifictedge/gadgethub/blob/main/vercel.json"

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_main,node_frontend_app,node_frontend_layout,node_frontend_navbar,node_frontend_footer,node_frontend_mobile_nav,node_frontend_product_card,node_frontend_auth_context,node_frontend_cart_context,node_frontend_api,node_frontend_pages,node_frontend_admin_pages toneBlue
class node_backend_index,node_backend_app,node_backend_routes,node_backend_controllers,node_backend_models,node_backend_auth_mw,node_backend_error_mw,node_backend_db toneAmber
class node_deployment_api,node_deployment_config toneMint
```

## Components

### Frontend

React client, shared UI, and commerce pages

- [Main entry](https://github.com/arifictedge/gadgethub/blob/main/frontend/src/main.jsx): Vite bootstrap · Starts the React client and mounts the app · `frontend/src/main.jsx`
- [App shell](https://github.com/arifictedge/gadgethub/blob/main/frontend/src/App.jsx): routing shell · Defines top-level routing and composition · `frontend/src/App.jsx`
- [Layout shell](https://github.com/arifictedge/gadgethub/blob/main/frontend/src/components/layout/Layout.jsx): shared chrome · Shared navigation, footer, and responsive action UI · `frontend/src/components/layout/Layout.jsx`
- [Navbar](https://github.com/arifictedge/gadgethub/blob/main/frontend/src/components/layout/Navbar.jsx): header component · Top navigation and session/cart entry points · `frontend/src/components/layout/Navbar.jsx`
- [Footer](https://github.com/arifictedge/gadgethub/blob/main/frontend/src/components/layout/Footer.jsx): layout component · Bottom page chrome and site links · `frontend/src/components/layout/Footer.jsx`
- [Mobile nav](https://github.com/arifictedge/gadgethub/blob/main/frontend/src/components/layout/MobileBottomNav.jsx): navigation component · Bottom navigation for small screens · `frontend/src/components/layout/MobileBottomNav.jsx`
- [Product card](https://github.com/arifictedge/gadgethub/blob/main/frontend/src/components/product/ProductCard.jsx): catalog widget · Reusable product presentation component · `frontend/src/components/product/ProductCard.jsx`
- [Auth state](https://github.com/arifictedge/gadgethub/blob/main/frontend/src/context/AuthContext.jsx): React context · Client-wide authentication and session state · `frontend/src/context/AuthContext.jsx`
- [Cart state](https://github.com/arifictedge/gadgethub/blob/main/frontend/src/context/CartContext.jsx): React context · Client-wide shopping cart state and actions · `frontend/src/context/CartContext.jsx`
- [API client](https://github.com/arifictedge/gadgethub/blob/main/frontend/src/lib/api.js): request helper · Central browser-side boundary for server requests · `frontend/src/lib/api.js`
- **Customer pages**: feature pages · Browse, compare, cart, checkout, and account flows
- **Admin pages**: staff pages · Administrative dashboards for products, orders, and users

### Backend

Express API, request pipeline, and MongoDB persistence

- [Server entry](https://github.com/arifictedge/gadgethub/blob/main/backend/src/index.js): Express bootstrap · Starts the API process and launches the service · `backend/src/index.js`
- [App wiring](https://github.com/arifictedge/gadgethub/blob/main/backend/src/app.js): Express app · Configures middleware and mounts routes · `backend/src/app.js`
- **Routes**: HTTP routing · Endpoint layer for auth, products, orders, and users
- **Controllers**: business logic · Implements request handling for commerce and account operations
- **Data models**: Mongoose models · Core MongoDB entities for products, users, and orders
- [Auth guard](https://github.com/arifictedge/gadgethub/blob/main/backend/src/middlewares/authMiddleware.js): middleware · Protects authenticated and admin-only API routes · `backend/src/middlewares/authMiddleware.js`
- [Error handler](https://github.com/arifictedge/gadgethub/blob/main/backend/src/middlewares/errorMiddleware.js): middleware · Centralizes API error responses and failure handling · `backend/src/middlewares/errorMiddleware.js`
- [MongoDB](https://github.com/arifictedge/gadgethub/blob/main/backend/src/config/db.js): database · Persistent store for commerce data · `backend/src/config/db.js`

### Deployment

Serverless entrypoints and hosting glue

- [Vercel API](https://github.com/arifictedge/gadgethub/blob/main/api/index.js): serverless entry · Deployment entrypoint for serverless API handling · `api/index.js`
- [Vercel config](https://github.com/arifictedge/gadgethub/blob/main/vercel.json): deployment config · Hosting and routing configuration for deployment · `vercel.json`

## Connections

- Main entry → App shell: bootstraps · Mounts the application shell and route tree
- App shell → Layout shell: uses · Wraps pages in shared UI chrome
- Layout shell → Navbar: contains · Includes the primary site navigation
- Layout shell → Footer: contains · Includes the shared footer
- Layout shell → Mobile nav: contains · Includes mobile navigation affordances
- App shell → Customer pages: routes · Directs customer traffic to feature pages
- App shell → Admin pages: routes · Directs staff traffic to admin pages
- App shell → Auth state: reads · Uses authentication state across the app
- App shell → Cart state: reads · Uses cart state across the app
- Customer pages → Product card: composes · Builds catalog views from reusable product cards
- Customer pages → API client: calls · Fetches products, cart, auth, and order data
- Admin pages → API client: calls · Performs administrative API operations
- Auth state → API client: auth flow · Coordinates login and session-related requests
- Cart state → API client: cart flow · Syncs cart-related requests with the backend
- API client → Vercel API: requests · Sends client traffic to the deployed API surface
- Vercel API → Vercel config: uses · Follows deployment routing and runtime rules
- Vercel API → Server entry: invokes · Serverless entrypoint forwards into the API server
- Server entry → App wiring: starts · Launches the Express application
- App wiring → Routes: mounts · Attaches route modules to the app
- Routes → Controllers: dispatches · Routes requests into domain handlers
- Controllers → Data models: reads/writes · Applies business logic through data models
- Data models → MongoDB: persists · Stores commerce entities in MongoDB
- Routes → Auth guard: protects · Applies auth checks to sensitive endpoints
- App wiring → Error handler: handles · Converts failures into consistent API responses
- App wiring → MongoDB: connects · Initializes database connectivity