# divya-jain07/stacksmith architecture

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

## Overview

1. **Two-app split with a clear client/server boundary**
   - The repo is organized into a `backend` API server and a `frontend` React client.
   - The frontend does not talk to MongoDB directly; all business data flows through backend REST endpoints under `/api`, plus Socket.IO for chat.

2. **Backend runtime and startup path**
   - `backend/src/index.js` is the entry point that starts the server.
   - `backend/src/app.js` configures the Express app, middleware pipeline, and route mounting.
   - `backend/src/config/db.js` handles the MongoDB connection through Mongoose.
   - The backend also shares the HTTP server with Socket.IO so the same process serves REST and real-time chat.

3. **Backend is organized by domain controllers and routes**
   - Each major feature area has its own controller and route module: auth, admin, books, borrowing, members, fines, reports, reservations, and chat.
   - Routes are mounted under `/api/*`, and controllers implement the actual business rules.
   - This is a classic layered Express structure: routes → controllers → models/utils.

4. **Core domain model is MongoDB/Mongoose-based**
   - Data entities are modeled in `backend/src/models` and represent the library workflow:
     - `User`, `Member`, `LibrarianStaff`
     - `Book`, `BookCopy`, `BookReservation`
     - `BorrowingHistory`, `Fine`
     - `Conversation`, `Message`
   - These models imply a separation between bibliographic records (`Book`) and physical inventory (`BookCopy`), which is important for diagramming the system correctly.

5. **Authentication and authorization are central cross-cutting concerns**
   - JWT-based auth is used for login/session handling.
   - Backend middleware enforces authorization, and the frontend uses protected routes to block unauthorized navigation.
   - Roles are explicitly modeled around `SuperAdmin`, `Admin`, `Librarian`, and `Member`.
   - The backend also includes a `tenant.middleware.js`, suggesting some requests may be scoped by tenant or organizational context.

6. **Library operations flow through a few major business subsystems**
   - **Catalog/inventory:** books and physical copies, including bulk CSV import via Multer.
   - **Circulation:** issue, renew, return, and request approval flows.
   - **Membership:** member account management and member data access.
   - **Fines:** calculation, payment, and waiver handling, with shared logic in `utils/fineCalculator.js`.
   - **Reporting:** aggregated operational and dashboard metrics.

7. **Real-time helpdesk chat is a separate channel from REST**
   - Chat uses Socket.IO for live communication between members and staff.
   - The persistent chat data is represented by `Conversation` and `Message` models, while the realtime layer handles delivery/updates.
   - This means chat is dual-path: REST likely manages history/conversation records, and WebSockets handle live messaging.

8. **Backend middleware pipeline handles the system-wide concerns**
   - `auth.middleware.js` protects API routes.
   - `error.middleware.js` centralizes API error handling.
   - `logger.middleware.js` provides request logging.
   - `tenant.middleware.js` likely applies tenant scoping or contextual request data.
   - Utility helpers such as `ApiError`, `catchAsync`, and `validation` keep controllers thin.

9. **Frontend is a role-driven React application**
   - The client uses Vite + React Router with separate dashboard areas for Admin, Librarian, Member, and SuperAdmin.
   - Public pages include a landing page and login page.
   - Protected routes and role-aware navigation are enforced in `components/auth/ProtectedRoute.jsx`.
   - `DashboardLayout.jsx` provides the shared authenticated shell for dashboard pages.

10. **Frontend state and service boundaries are explicit**
   - `frontend/src/services/api.js` is the REST client boundary to the backend.
   - `frontend/src/services/socket.js` is the Socket.IO client boundary for chat.
   - Context providers manage cross-cutting UI/auth state:
     - `AuthContext` for identity and session
     - `ThemeContext` for theming
     - `DialogContext` for modal/dialog state

11. **Frontend screens mirror backend domains**
   - Admin pages cover catalog, staff/member management, counter operations, fines, and chat.
   - Member pages cover catalog browsing, chat, borrowing history, and dashboard/home views.
   - This one-to-one mapping between dashboards and backend domains makes the architecture straightforward to diagram.

12. **Deployment and environment shape the runtime topology**
   - Backend expects MongoDB, a JWT secret, and a port configuration.
   - Frontend uses `VITE_API_URL`; when unset, the Vite dev server proxies `/api` to the local backend.
   - Production is a separated frontend build with the backend running independently and serving the API/WebSocket endpoint.

Overall, the system is a role-based library management platform with a REST-first backend, MongoDB persistence, and a small realtime chat subsystem layered on top of the same server. The most important diagram boundaries are: frontend vs backend, REST vs Socket.IO, auth/authorization as a cross-cutting layer, and the separation between catalog, circulation, fines, reporting, and chat domains.

Main entry points: [`backend/src/routes/index.js`](https://github.com/divya-jain07/stacksmith/blob/main/backend/src/routes/index.js) (API routes), [`frontend/src/App.jsx`](https://github.com/divya-jain07/stacksmith/blob/main/frontend/src/App.jsx) (App shell), [`frontend/src/pages/dashboards/admin`](https://github.com/divya-jain07/stacksmith/tree/main/frontend/src/pages/dashboards/admin) (Admin views), [`backend/src/models`](https://github.com/divya-jain07/stacksmith/tree/main/backend/src/models) (Domain models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_index["Server entry<br/>express bootstrap<br/>[index.js]"]
  node_backend_app["App config<br/>express app<br/>[app.js]"]
  node_backend_db[("MongoDB<br/>mongoose connection<br/>[db.js]")]
  node_backend_routes["API routes<br/>route composition<br/>[index.js]"]
  node_backend_auth["Auth API<br/>auth controller/routes<br/>[auth.controller.js]"]
  node_backend_books["Catalog API<br/>book controller/routes<br/>[book.controller.js]"]
  node_backend_borrow["Circulation API<br/>borrow controller/routes"]
  node_backend_members["Members API<br/>member controller/routes"]
  node_backend_fines["Fines API<br/>fine controller/routes<br/>[fine.controller.js]"]
  node_backend_reports["Reports API<br/>report controller/routes"]
  node_backend_admin["Admin API<br/>admin controller/routes"]
  node_backend_chat["Chat API<br/>chat controller/routes<br/>[chat.controller.js]"]
  node_backend_models[("Domain models<br/>mongoose models")]
  node_backend_middleware["Middleware<br/>cross-cutting layer"]
  node_backend_utils["Utils<br/>shared helpers"]
  node_backend_socket(("Socket.IO<br/>realtime chat"))
end

subgraph group_frontend["Frontend"]
  node_frontend_main["Client entry<br/>react bootstrap<br/>[main.jsx]"]
  node_frontend_app["App shell<br/>route shell<br/>[App.jsx]"]
  node_frontend_context["App context<br/>react context"]
  node_frontend_layout["Dashboard layout<br/>ui shell"]
  node_frontend_protect["Protected route<br/>route guard<br/>[ProtectedRoute.jsx]"]
  node_frontend_api["REST client<br/>api service<br/>[api.js]"]
  node_frontend_socket(("Chat client<br/>socket service<br/>[socket.js]"))
  node_frontend_admin_dash["Admin views<br/>dashboard pages"]
  node_frontend_member_dash["Member views<br/>dashboard pages"]
end

node_backend_index -->|"starts"| node_backend_app
node_backend_index -->|"shares server"| node_backend_socket
node_backend_app -->|"uses"| node_backend_middleware
node_backend_app -->|"mounts"| node_backend_routes
node_backend_app -->|"connects"| node_backend_db
node_backend_routes -->|"routes to"| node_backend_auth
node_backend_routes -->|"routes to"| node_backend_admin
node_backend_routes -->|"routes to"| node_backend_books
node_backend_routes -->|"routes to"| node_backend_borrow
node_backend_routes -->|"routes to"| node_backend_members
node_backend_routes -->|"routes to"| node_backend_fines
node_backend_routes -->|"routes to"| node_backend_reports
node_backend_routes -->|"routes to"| node_backend_chat
node_backend_auth -->|"reads/writes"| node_backend_models
node_backend_books -->|"reads/writes"| node_backend_models
node_backend_borrow -->|"reads/writes"| node_backend_models
node_backend_members -->|"reads/writes"| node_backend_models
node_backend_fines -->|"reads/writes"| node_backend_models
node_backend_reports -->|"aggregates"| node_backend_models
node_backend_chat -->|"reads/writes"| node_backend_models
node_backend_fines -->|"uses"| node_backend_utils
node_backend_admin -->|"uses"| node_backend_utils
node_backend_middleware -->|"uses"| node_backend_utils
node_backend_socket -->|"supports"| node_backend_chat
node_frontend_main -->|"boots"| node_frontend_app
node_frontend_app -->|"provides"| node_frontend_context
node_frontend_app -->|"guards"| node_frontend_protect
node_frontend_app -->|"wraps"| node_frontend_layout
node_frontend_app -->|"routes to"| node_frontend_admin_dash
node_frontend_app -->|"routes to"| node_frontend_member_dash
node_frontend_context -->|"drives"| node_frontend_api
node_frontend_context -->|"drives"| node_frontend_socket
node_frontend_api -->|"calls"| node_backend_routes
node_frontend_socket -->|"connects"| node_backend_socket
node_frontend_admin_dash -->|"manages"| node_backend_admin
node_frontend_admin_dash -->|"uses"| node_backend_books
node_frontend_admin_dash -->|"uses"| node_backend_borrow
node_frontend_admin_dash -->|"uses"| node_backend_fines
node_frontend_admin_dash -->|"uses"| node_backend_chat
node_frontend_member_dash -->|"uses"| node_backend_books
node_frontend_member_dash -->|"uses"| node_backend_borrow
node_frontend_member_dash -->|"uses"| node_backend_chat
node_frontend_protect -->|"checks"| node_frontend_context

click node_backend_index "https://github.com/divya-jain07/stacksmith/blob/main/backend/src/index.js"
click node_backend_app "https://github.com/divya-jain07/stacksmith/blob/main/backend/src/app.js"
click node_backend_db "https://github.com/divya-jain07/stacksmith/blob/main/backend/src/config/db.js"
click node_backend_routes "https://github.com/divya-jain07/stacksmith/blob/main/backend/src/routes/index.js"
click node_backend_auth "https://github.com/divya-jain07/stacksmith/blob/main/backend/src/controllers/auth.controller.js"
click node_backend_books "https://github.com/divya-jain07/stacksmith/blob/main/backend/src/controllers/book.controller.js"
click node_backend_borrow "https://github.com/divya-jain07/stacksmith/blob/main/backend/src/controllers/borrow.controller.js"
click node_backend_members "https://github.com/divya-jain07/stacksmith/blob/main/backend/src/controllers/member.controller.js"
click node_backend_fines "https://github.com/divya-jain07/stacksmith/blob/main/backend/src/controllers/fine.controller.js"
click node_backend_reports "https://github.com/divya-jain07/stacksmith/blob/main/backend/src/controllers/report.controller.js"
click node_backend_admin "https://github.com/divya-jain07/stacksmith/blob/main/backend/src/controllers/admin.controller.js"
click node_backend_chat "https://github.com/divya-jain07/stacksmith/blob/main/backend/src/controllers/chat.controller.js"
click node_backend_models "https://github.com/divya-jain07/stacksmith/tree/main/backend/src/models"
click node_backend_middleware "https://github.com/divya-jain07/stacksmith/tree/main/backend/src/middlewares"
click node_backend_utils "https://github.com/divya-jain07/stacksmith/tree/main/backend/src/utils"
click node_backend_socket "https://github.com/divya-jain07/stacksmith/tree/main/backend/src/socket"
click node_frontend_main "https://github.com/divya-jain07/stacksmith/blob/main/frontend/src/main.jsx"
click node_frontend_app "https://github.com/divya-jain07/stacksmith/blob/main/frontend/src/App.jsx"
click node_frontend_context "https://github.com/divya-jain07/stacksmith/tree/main/frontend/src/context"
click node_frontend_layout "https://github.com/divya-jain07/stacksmith/blob/main/frontend/src/components/layout/DashboardLayout.jsx"
click node_frontend_protect "https://github.com/divya-jain07/stacksmith/blob/main/frontend/src/components/auth/ProtectedRoute.jsx"
click node_frontend_api "https://github.com/divya-jain07/stacksmith/blob/main/frontend/src/services/api.js"
click node_frontend_socket "https://github.com/divya-jain07/stacksmith/blob/main/frontend/src/services/socket.js"
click node_frontend_admin_dash "https://github.com/divya-jain07/stacksmith/tree/main/frontend/src/pages/dashboards/admin"
click node_frontend_member_dash "https://github.com/divya-jain07/stacksmith/tree/main/frontend/src/pages/dashboards/member"

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_index,node_backend_app,node_backend_db,node_backend_routes,node_backend_auth,node_backend_books,node_backend_borrow,node_backend_members,node_backend_fines,node_backend_reports,node_backend_admin,node_backend_chat,node_backend_models,node_backend_middleware,node_backend_utils,node_backend_socket toneBlue
class node_frontend_main,node_frontend_app,node_frontend_context,node_frontend_layout,node_frontend_protect,node_frontend_api,node_frontend_socket,node_frontend_admin_dash,node_frontend_member_dash toneAmber
```

## Components

### Backend

Express API, MongoDB models, middleware, and Socket.IO runtime.

- [Server entry](https://github.com/divya-jain07/stacksmith/blob/main/backend/src/index.js): express bootstrap · Starts the backend process and shares the HTTP server with realtime chat. · `backend/src/index.js`
- [App config](https://github.com/divya-jain07/stacksmith/blob/main/backend/src/app.js): express app · Configures middleware and mounts API routes. · `backend/src/app.js`
- [MongoDB](https://github.com/divya-jain07/stacksmith/blob/main/backend/src/config/db.js): mongoose connection · Connects the backend to MongoDB via Mongoose. · `backend/src/config/db.js`
- [API routes](https://github.com/divya-jain07/stacksmith/blob/main/backend/src/routes/index.js): route composition · Top-level route registration for the REST API. · `backend/src/routes/index.js`
- [Auth API](https://github.com/divya-jain07/stacksmith/blob/main/backend/src/controllers/auth.controller.js): auth controller/routes · Login and session-related REST flow. · `backend/src/controllers/auth.controller.js`
- [Catalog API](https://github.com/divya-jain07/stacksmith/blob/main/backend/src/controllers/book.controller.js): book controller/routes · Book and copy management, including inventory operations. · `backend/src/controllers/book.controller.js`
- [Circulation API](https://github.com/divya-jain07/stacksmith/blob/main/backend/src/controllers/borrow.controller.js): borrow controller/routes · Issue, renew, return, and borrowing workflow. · `backend/src/controllers/borrow.controller.js`
- [Members API](https://github.com/divya-jain07/stacksmith/blob/main/backend/src/controllers/member.controller.js): member controller/routes · Member account management and access to member data. · `backend/src/controllers/member.controller.js`
- [Fines API](https://github.com/divya-jain07/stacksmith/blob/main/backend/src/controllers/fine.controller.js): fine controller/routes · Fine calculation, payment, and waiver handling. · `backend/src/controllers/fine.controller.js`
- [Reports API](https://github.com/divya-jain07/stacksmith/blob/main/backend/src/controllers/report.controller.js): report controller/routes · Aggregated operational and dashboard metrics. · `backend/src/controllers/report.controller.js`
- [Admin API](https://github.com/divya-jain07/stacksmith/blob/main/backend/src/controllers/admin.controller.js): admin controller/routes · Staff and admin operations that span multiple library functions. · `backend/src/controllers/admin.controller.js`
- [Chat API](https://github.com/divya-jain07/stacksmith/blob/main/backend/src/controllers/chat.controller.js): chat controller/routes · Conversation history and chat-related REST endpoints. · `backend/src/controllers/chat.controller.js`
- [Domain models](https://github.com/divya-jain07/stacksmith/tree/main/backend/src/models): mongoose models · Library entities for users, members, books, circulation, fines, and chat. · `backend/src/models`
- [Middleware](https://github.com/divya-jain07/stacksmith/tree/main/backend/src/middlewares): cross-cutting layer · Auth, tenant scoping, logging, and centralized error handling. · `backend/src/middlewares`
- [Utils](https://github.com/divya-jain07/stacksmith/tree/main/backend/src/utils): shared helpers · Async wrapper, API errors, validation, and fine calculation logic. · `backend/src/utils`
- [Socket.IO](https://github.com/divya-jain07/stacksmith/tree/main/backend/src/socket): realtime chat · Realtime channel for live chat delivery on the same backend server. · `backend/src/socket`

### Frontend

React client with dashboards, state, and API/socket boundaries.

- [Client entry](https://github.com/divya-jain07/stacksmith/blob/main/frontend/src/main.jsx): react bootstrap · Bootstraps the React application and routing. · `frontend/src/main.jsx`
- [App shell](https://github.com/divya-jain07/stacksmith/blob/main/frontend/src/App.jsx): route shell · Top-level routing and application composition. · `frontend/src/App.jsx`
- [App context](https://github.com/divya-jain07/stacksmith/tree/main/frontend/src/context): react context · Auth, dialog, and theme state shared across the client. · `frontend/src/context`
- [Dashboard layout](https://github.com/divya-jain07/stacksmith/blob/main/frontend/src/components/layout/DashboardLayout.jsx): ui shell · Shared authenticated layout for dashboard pages. · `frontend/src/components/layout/DashboardLayout.jsx`
- [Protected route](https://github.com/divya-jain07/stacksmith/blob/main/frontend/src/components/auth/ProtectedRoute.jsx): route guard · Blocks unauthorized navigation and enforces role-based access. · `frontend/src/components/auth/ProtectedRoute.jsx`
- [REST client](https://github.com/divya-jain07/stacksmith/blob/main/frontend/src/services/api.js): api service · Frontend boundary for backend REST endpoints. · `frontend/src/services/api.js`
- [Chat client](https://github.com/divya-jain07/stacksmith/blob/main/frontend/src/services/socket.js): socket service · Frontend boundary for realtime chat over Socket.IO. · `frontend/src/services/socket.js`
- [Admin views](https://github.com/divya-jain07/stacksmith/tree/main/frontend/src/pages/dashboards/admin): dashboard pages · Admin-facing screens for catalog, staff, members, fines, and chat. · `frontend/src/pages/dashboards/admin`
- [Member views](https://github.com/divya-jain07/stacksmith/tree/main/frontend/src/pages/dashboards/member): dashboard pages · Member-facing screens for catalog, chat, history, and dashboard. · `frontend/src/pages/dashboards/member`

## Connections

- Server entry → App config: starts · Server entry initializes the Express application.
- Server entry → Socket.IO: shares server · Realtime chat runs on the same HTTP server process.
- App config → Middleware: uses · Express app wires in auth, tenant, logger, and error middleware.
- App config → API routes: mounts · API routes are mounted under the app.
- App config → MongoDB: connects · Application startup depends on MongoDB connectivity.
- API routes → Auth API: routes to · Mounts auth endpoints.
- API routes → Admin API: routes to · Mounts admin endpoints.
- API routes → Catalog API: routes to · Mounts book and copy endpoints.
- API routes → Circulation API: routes to · Mounts circulation endpoints.
- API routes → Members API: routes to · Mounts member endpoints.
- API routes → Fines API: routes to · Mounts fine endpoints.
- API routes → Reports API: routes to · Mounts reporting endpoints.
- API routes → Chat API: routes to · Mounts chat REST endpoints.
- Auth API → Domain models: reads/writes · Authentication works with user and role data.
- Catalog API → Domain models: reads/writes · Catalog operations persist books and copies.
- Circulation API → Domain models: reads/writes · Circulation uses borrowing history, reservations, and copies.
- Members API → Domain models: reads/writes · Member management uses user and member records.
- Fines API → Domain models: reads/writes · Fines are stored and updated in MongoDB.
- Reports API → Domain models: aggregates · Reporting summarizes library data across models.
- Chat API → Domain models: reads/writes · Chat history persists conversations and messages.
- Fines API → Utils: uses · Fine workflows share calculator and helper utilities.
- Admin API → Utils: uses · Admin operations rely on shared helpers and validation.
- Middleware → Utils: uses · Middleware and controllers share async/error utilities.
- Socket.IO → Chat API: supports · Socket.IO complements chat REST for live delivery.
- Client entry → App shell: boots · React entry renders the app shell.
- App shell → App context: provides · Top-level client state is supplied through context providers.
- App shell → Protected route: guards · Routing uses protected and role-aware access control.
- App shell → Dashboard layout: wraps · Authenticated dashboard pages share the dashboard shell.
- App shell → Admin views: routes to · Admin routes lead to admin dashboard screens.
- App shell → Member views: routes to · Member routes lead to member dashboard screens.
- App context → REST client: drives · Auth/session state feeds API access patterns.
- App context → Chat client: drives · Client chat state and identity support websocket use.
- REST client → API routes: calls · Frontend REST requests target backend API endpoints.
- Chat client → Socket.IO: connects · Frontend websocket client connects to backend Socket.IO.
- Admin views → Admin API: manages · Admin screens reflect admin backend capabilities.
- Admin views → Catalog API: uses · Catalog views depend on catalog endpoints.
- Admin views → Circulation API: uses · Counter operations depend on circulation endpoints.
- Admin views → Fines API: uses · Fines ledger depends on fine endpoints.
- Admin views → Chat API: uses · Admin chat hub uses chat history endpoints.
- Member views → Catalog API: uses · Member catalog browsing depends on catalog endpoints.
- Member views → Circulation API: uses · Borrowing history and circulation views depend on circulation data.
- Member views → Chat API: uses · Member chat hub uses chat endpoints.
- Protected route → App context: checks · Route protection uses auth and role context.
