How divya-jain07/stacksmith works
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: index.js API routes · App.jsx App shell · admin Admin views · models Domain models
Components 25
Backend
Express API, MongoDB models, middleware, and Socket.IO runtime.
- Server entry · Starts the backend process and shares the HTTP server with realtime chat.
backend/src/index.js - App config · Configures middleware and mounts API routes.
backend/src/app.js - MongoDB · Connects the backend to MongoDB via Mongoose.
backend/src/config/db.js - API routes · Top-level route registration for the REST API.
backend/src/routes/index.js - Auth API · Login and session-related REST flow.
backend/src/controllers/auth.controller.js - Catalog API · Book and copy management, including inventory operations.
backend/src/controllers/book.controller.js - Circulation API · Issue, renew, return, and borrowing workflow.
backend/src/controllers/borrow.controller.js - Members API · Member account management and access to member data.
backend/src/controllers/member.controller.js - Fines API · Fine calculation, payment, and waiver handling.
backend/src/controllers/fine.controller.js - Reports API · Aggregated operational and dashboard metrics.
backend/src/controllers/report.controller.js - Admin API · Staff and admin operations that span multiple library functions.
backend/src/controllers/admin.controller.js - Chat API · Conversation history and chat-related REST endpoints.
backend/src/controllers/chat.controller.js - Domain models · Library entities for users, members, books, circulation, fines, and chat.
backend/src/models - Middleware · Auth, tenant scoping, logging, and centralized error handling.
backend/src/middlewares - Utils · Async wrapper, API errors, validation, and fine calculation logic.
backend/src/utils - Socket.IO · 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 · Bootstraps the React application and routing.
frontend/src/main.jsx - App shell · Top-level routing and application composition.
frontend/src/App.jsx - App context · Auth, dialog, and theme state shared across the client.
frontend/src/context - Dashboard layout · Shared authenticated layout for dashboard pages.
frontend/src/components/layout/DashboardLayout.jsx - Protected route · Blocks unauthorized navigation and enforces role-based access.
frontend/src/components/auth/ProtectedRoute.jsx - REST client · Frontend boundary for backend REST endpoints.
frontend/src/services/api.js - Chat client · Frontend boundary for realtime chat over Socket.IO.
frontend/src/services/socket.js - Admin views · Admin-facing screens for catalog, staff, members, fines, and chat.
frontend/src/pages/dashboards/admin - Member views · Member-facing screens for catalog, chat, history, and dashboard.
frontend/src/pages/dashboards/member
Connections 43
- 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.