# jihadul021/bookshare architecture

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

## Overview

1. **System shape**
   - BookShare is a two-tier full-stack app: a React/Vite single-page frontend in `client/` and an Express/MongoDB backend in `server/`.
   - The frontend calls the backend over HTTP for most operations, while chat uses a Socket.io real-time channel.
   - Data is persisted primarily in MongoDB through Mongoose models; uploaded book images are stored on the server under `server/uploads`.

2. **Frontend application shell**
   - The client entry points are `client/src/main.jsx` and `client/src/App.jsx`, which likely establish global layout and route switching.
   - Shared site chrome lives in components like `Navbar`, `Footer`, `Banner`, `Categories`, `HowItWorks`, and `FloatingChat`.
   - Styling is a mix of CSS modules/files and Tailwind configuration, with Vite as the build tool.

3. **Frontend feature areas**
   - The UI is organized by business domain rather than by generic widgets: authentication pages (`LoginPage`, `RegisterPage`, `ForgotPasswordPage`, `VerifyEmailPage`), catalog browsing (`BookGrid`, `SearchFilters`, `SearchResults`, `ProductDetails`), and user commerce flows (`CartPage`, `WishlistPage`, `Checkout`, `PaymentPage`, `Congratulations`).
   - There are dedicated seller and admin surfaces: `SellerProfile`, `SellerOrderManagement`, `MyBooksPage`, plus admin screens for books, coupons, dashboard, orders, and users.
   - Messaging has its own UI set: `ChatWindow`, `Inbox`, and the floating chat launcher.

4. **Client-server boundary**
   - `client/src/api.js` and `client/src/utils/apiUrl.js` centralize backend communication and base URL handling.
   - `client/src/socket.js` isolates the realtime client connection, separating chat transport from standard REST calls.
   - `getImageUrl.js` suggests a small adapter layer for rendering uploaded media from backend paths.

5. **Backend API layer**
   - The server is organized in classic Express MVC style: `routes/` define endpoints, `controllers/` contain business logic, `models/` define MongoDB entities, and `middleware/` handles cross-cutting concerns.
   - Separate route modules exist for auth, books, cart, orders, wishlist, addresses, coupons, messages, payments, and admin functions.
   - This structure implies domain-specific APIs rather than one monolithic controller.

6. **Core data model boundaries**
   - The MongoDB models map directly to product domains: `User`, `Book`, `Cart`, `Order`, `Wishlist`, `Address`, `Coupon`, `Conversation`, and `Message`.
   - `Conversation` and `Message` form the chat subsystem, distinct from commerce records.
   - Orders, cart, and wishlist are separate collections, which suggests the app treats browse/save/buy states independently.

7. **Authentication and authorization**
   - JWT-based auth is implemented through `authController` and `authMiddleware`.
   - `adminMiddleware` enforces elevated access for the admin dashboard and management endpoints.
   - The presence of `VerifyEmailPage` and `ForgotPasswordPage` plus `emailService.js` indicates account lifecycle flows beyond simple login/signup.

8. **Commerce and fulfillment flow**
   - The buying path likely runs from catalog/product pages into cart, then checkout, payment, and order confirmation.
   - `orderController`, `cartController`, `addressController`, and `couponController` split responsibilities for shipping, discounts, and order creation.
   - Seller-side order handling is exposed separately from buyer-side order history, indicating distinct workflows for different roles.

9. **Payments**
   - Stripe is integrated on the backend via `paymentRoutes` and surfaced in the frontend through `PaymentPage`.
   - The README indicates support for both cash on delivery and card payments, so checkout branches into multiple payment methods.
   - Stripe is test-mode friendly, which suggests payment intent handling is present but isolated from product data.

10. **Real-time chat**
   - Chat uses Socket.io on the client and message-related backend controllers/routes/models.
   - The README states messages are AES-encrypted before storage, so the message subsystem has a security boundary distinct from normal CRUD data.
   - `FloatingChat`, `ChatWindow`, and `Inbox` imply both inline conversations and a persistent inbox view.

11. **Admin and moderation boundary**
   - Admin pages and controllers manage users, books, orders, and coupons from a centralized dashboard.
   - This is a separate operational surface from normal buyer/seller interactions, likely with stricter access checks and broader visibility into system data.

12. **Media and infrastructure**
   - Book images are uploaded via middleware and stored under `server/uploads`, so the app handles file upload in addition to JSON APIs.
   - Email delivery is handled by `server/utils/emailService.js`, likely for verification, password reset, and transactional notifications.
   - The backend depends on environment variables for MongoDB, JWT, chat encryption, SMTP, client origin, and port configuration.

13. **High-level data flow**
   - A typical request path is: React page/component -> API or Socket.io client -> Express route -> controller -> Mongoose model -> MongoDB.
   - For user-facing actions like checkout or messaging, the backend may also involve Stripe, SMTP, or encryption utilities before persisting or responding.
   - For architecture diagrams, the cleanest boundaries are: presentation layer, REST API layer, realtime chat layer, persistence layer, and external services (MongoDB, Stripe, SMTP).

Main entry points: [`client/src/App.jsx`](https://github.com/jihadul021/bookshare/blob/main/client/src/App.jsx) (Storefront UI), [`server/controllers/authController.js`](https://github.com/jihadul021/bookshare/blob/main/server/controllers/authController.js) (Controllers), [`client/src/api.js`](https://github.com/jihadul021/bookshare/blob/main/client/src/api.js) (API client), [`server/routes/authRoutes.js`](https://github.com/jihadul021/bookshare/blob/main/server/routes/authRoutes.js) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_client_app["App shell<br/>React SPA<br/>[main.jsx]"]
  node_client_ui["Storefront UI<br/>React views<br/>[App.jsx]"]
  node_client_auth["Auth pages<br/>account UI<br/>[LoginPage.jsx]"]
  node_client_catalog["Catalog views<br/>browse UI<br/>[BookGrid.jsx]"]
  node_client_checkout["Shopping flow<br/>commerce UI<br/>[CartPage.jsx]"]
  node_client_seller["Seller area<br/>seller UI<br/>[SellerProfile.jsx]"]
  node_client_admin["Admin console<br/>admin UI<br/>[AdminDashboard.jsx]"]
  node_client_chat["Chat UI<br/>realtime UI<br/>[FloatingChat.jsx]"]
  node_client_api["API client<br/>REST adapter<br/>[api.js]"]
  node_client_socket["Socket client<br/>realtime adapter<br/>[socket.js]"]
end

subgraph group_server["Server"]
  node_server_app["Express app<br/>backend entry<br/>[index.js]"]
  node_server_routes["API routes<br/>route layer<br/>[authRoutes.js]"]
  node_server_ctrl["Controllers<br/>business logic<br/>[authController.js]"]
  node_server_mw["Middleware<br/>cross-cutting<br/>[authMiddleware.js]"]
  node_server_models[("Data models<br/>Mongo schemas<br/>[User.js]")]
  node_server_utils["Email service<br/>[emailService.js]"]
end

subgraph group_data["Data & services"]
  node_mongo[("MongoDB<br/>database")]
  node_stripe["Stripe<br/>payment gateway"]
  node_smtp["SMTP<br/>email service"]
end

node_client_app -->|"renders"| node_client_ui
node_client_ui -->|"routes"| node_client_auth
node_client_ui -->|"routes"| node_client_catalog
node_client_ui -->|"routes"| node_client_checkout
node_client_ui -->|"routes"| node_client_seller
node_client_ui -->|"routes"| node_client_admin
node_client_ui -->|"shows"| node_client_chat
node_client_catalog -->|"fetches"| node_client_api
node_client_checkout -->|"fetches"| node_client_api
node_client_auth -->|"fetches"| node_client_api
node_client_chat -->|"connects"| node_client_socket
node_client_api -->|"http"| node_server_app
node_client_socket -->|"socket.io"| node_server_app
node_server_app -->|"mounts"| node_server_routes
node_server_routes -->|"delegates"| node_server_ctrl
node_server_ctrl -->|"uses"| node_server_mw
node_server_ctrl -->|"reads/writes"| node_server_models
node_server_models -->|"persists"| node_mongo
node_server_ctrl -->|"emails"| node_server_utils
node_server_utils -->|"delivers"| node_smtp
node_server_routes -->|"payments"| node_stripe

click node_client_app "https://github.com/jihadul021/bookshare/blob/main/client/src/main.jsx"
click node_client_ui "https://github.com/jihadul021/bookshare/blob/main/client/src/App.jsx"
click node_client_auth "https://github.com/jihadul021/bookshare/blob/main/client/src/components/LoginPage.jsx"
click node_client_catalog "https://github.com/jihadul021/bookshare/blob/main/client/src/components/BookGrid.jsx"
click node_client_checkout "https://github.com/jihadul021/bookshare/blob/main/client/src/components/CartPage.jsx"
click node_client_seller "https://github.com/jihadul021/bookshare/blob/main/client/src/components/SellerProfile.jsx"
click node_client_admin "https://github.com/jihadul021/bookshare/blob/main/client/src/components/AdminDashboard.jsx"
click node_client_chat "https://github.com/jihadul021/bookshare/blob/main/client/src/components/FloatingChat.jsx"
click node_client_api "https://github.com/jihadul021/bookshare/blob/main/client/src/api.js"
click node_client_socket "https://github.com/jihadul021/bookshare/blob/main/client/src/socket.js"
click node_server_app "https://github.com/jihadul021/bookshare/blob/main/server/index.js"
click node_server_routes "https://github.com/jihadul021/bookshare/blob/main/server/routes/authRoutes.js"
click node_server_ctrl "https://github.com/jihadul021/bookshare/blob/main/server/controllers/authController.js"
click node_server_mw "https://github.com/jihadul021/bookshare/blob/main/server/middleware/authMiddleware.js"
click node_server_models "https://github.com/jihadul021/bookshare/blob/main/server/models/User.js"
click node_server_utils "https://github.com/jihadul021/bookshare/blob/main/server/utils/emailService.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_client_app,node_client_ui,node_client_auth,node_client_catalog,node_client_checkout,node_client_seller,node_client_admin,node_client_chat,node_client_api,node_client_socket toneBlue
class node_server_app,node_server_routes,node_server_ctrl,node_server_mw,node_server_models,node_server_utils toneAmber
class node_mongo,node_stripe,node_smtp toneMint
```

## Components

### Client

React/Vite frontend and browser-side integration

- [App shell](https://github.com/jihadul021/bookshare/blob/main/client/src/main.jsx): React SPA · Bootstraps the frontend and route/layout switching · `client/src/main.jsx`
- [Storefront UI](https://github.com/jihadul021/bookshare/blob/main/client/src/App.jsx): React views · Navigation, landing content, catalog browsing, and core pages · `client/src/App.jsx`
- [Auth pages](https://github.com/jihadul021/bookshare/blob/main/client/src/components/LoginPage.jsx): account UI · Login, register, password recovery, and email verification · `client/src/components/LoginPage.jsx`
- [Catalog views](https://github.com/jihadul021/bookshare/blob/main/client/src/components/BookGrid.jsx): browse UI · Search, grid, filters, and product detail browsing · `client/src/components/BookGrid.jsx`
- [Shopping flow](https://github.com/jihadul021/bookshare/blob/main/client/src/components/CartPage.jsx): commerce UI · Cart, wishlist, checkout, payment, and order confirmation · `client/src/components/CartPage.jsx`
- [Seller area](https://github.com/jihadul021/bookshare/blob/main/client/src/components/SellerProfile.jsx): seller UI · Seller profile, owned books, and seller order handling · `client/src/components/SellerProfile.jsx`
- [Admin console](https://github.com/jihadul021/bookshare/blob/main/client/src/components/AdminDashboard.jsx): admin UI · Dashboards and management screens for books, orders, users, and coupons · `client/src/components/AdminDashboard.jsx`
- [Chat UI](https://github.com/jihadul021/bookshare/blob/main/client/src/components/FloatingChat.jsx): realtime UI · Floating launcher, inbox, and conversation window · `client/src/components/FloatingChat.jsx`
- [API client](https://github.com/jihadul021/bookshare/blob/main/client/src/api.js): REST adapter · Central HTTP client and backend URL helpers · `client/src/api.js`
- [Socket client](https://github.com/jihadul021/bookshare/blob/main/client/src/socket.js): realtime adapter · Socket.io connection for chat transport · `client/src/socket.js`

### Server

Express API, realtime chat, and data access

- [Express app](https://github.com/jihadul021/bookshare/blob/main/server/index.js): backend entry · Wires routes, middleware, realtime, and server startup · `server/index.js`
- [API routes](https://github.com/jihadul021/bookshare/blob/main/server/routes/authRoutes.js): route layer · Domain endpoints for auth, books, cart, orders, wishlist, addresses, coupons, messages, payments, and admin · `server/routes/authRoutes.js`
- [Controllers](https://github.com/jihadul021/bookshare/blob/main/server/controllers/authController.js): business logic · Domain logic for auth, books, cart, orders, wishlist, addresses, coupons, messages, and admin · `server/controllers/authController.js`
- [Middleware](https://github.com/jihadul021/bookshare/blob/main/server/middleware/authMiddleware.js): cross-cutting · Auth checks, admin gating, and upload handling · `server/middleware/authMiddleware.js`
- [Data models](https://github.com/jihadul021/bookshare/blob/main/server/models/User.js): Mongo schemas · User, book, cart, order, wishlist, address, coupon, conversation, and message entities · `server/models/User.js`
- [Email service](https://github.com/jihadul021/bookshare/blob/main/server/utils/emailService.js): utility · Transactional email delivery for verification and recovery flows · `server/utils/emailService.js`

### Data & services

Persistence and external service boundaries

- **MongoDB**: database · Primary persistent store for commerce and chat data
- **Stripe**: payment gateway · Card payment processing for checkout
- **SMTP**: email service · Outbound email delivery for account lifecycle notifications

## Connections

- App shell → Storefront UI: renders · Application shell composes the main site experience
- Storefront UI → Auth pages: routes · Front-end route/view transitions into auth flows
- Storefront UI → Catalog views: routes · Front-end route/view transitions into browsing flows
- Storefront UI → Shopping flow: routes · Front-end route/view transitions into purchase flows
- Storefront UI → Seller area: routes · Front-end route/view transitions into seller flows
- Storefront UI → Admin console: routes · Front-end route/view transitions into admin flows
- Storefront UI → Chat UI: shows · Shared layout exposes chat entry points
- Catalog views → API client: fetches · Catalog pages query backend APIs
- Shopping flow → API client: fetches · Cart, checkout, and order pages call REST endpoints
- Auth pages → API client: fetches · Account pages submit auth and recovery requests
- Chat UI → Socket client: connects · Chat UI uses realtime socket transport
- API client → Express app: http · REST requests target the Express backend
- Socket client → Express app: socket.io · Realtime chat channel terminates on the backend
- Express app → API routes: mounts · Express app mounts domain route modules
- API routes → Controllers: delegates · Routes hand off to controller logic
- Controllers → Middleware: uses · Controllers depend on auth, admin, and upload concerns
- Controllers → Data models: reads/writes · Business logic persists through Mongoose models
- Data models → MongoDB: persists · MongoDB stores the application collections
- Controllers → Email service: emails · Account and transactional flows send email notifications
- Email service → SMTP: delivers · Email service sends outbound mail through SMTP
- API routes → Stripe: payments · Payment routes integrate with Stripe for checkout