How kandarpvyas2591/digital-rosca works
1. This repo is a two-tier application: a Node.js/Express backend in Backend/ and a React/Vite frontend in Frontend/. The frontend talks to the backend through HTTP API calls, while the backend owns authentication, business rules, persistence, and notifications.
2. The backend is organized in a standard layered shape:
- routes/ defines API endpoints,
- controllers/ contains request handlers and domain logic,
- middlewares/ enforces auth and request preprocessing,
- models/ defines MongoDB data models,
- utils/ holds reusable infrastructure helpers,
- views/ contains email templates.
src/app.js is likely the Express app wiring, and src/server.js is the process entrypoint.
3. The core domain is digital ROSCA management. The backend models show four main business entities:
- user
- roscaGroup
- loanOffer
- loanAgreement
- transaction
These indicate the system tracks membership, group savings activity, lending requests/offers, finalized loan contracts, and payment history.
4. The main functional boundaries on the backend appear to be:
- user/account management,
- ROSCA group creation and participation,
- loan offers and agreement lifecycle,
- transaction recording and history.
The separate controllers and routes for these areas suggest each is treated as its own subsystem rather than one monolithic flow.
5. Authentication and authorization are central. auth.middleware.js likely protects private endpoints with JWT-based identity checks, while lenderVerify.js suggests an additional role- or eligibility-based gate for lending actions. This implies the API distinguishes ordinary members from users allowed to lend or approve loans.
6. Persistence is MongoDB-backed, via src/db/index.js and the Mongoose-style model files. The architecture is database-first on the backend: controllers operate on models, and the database is the source of truth for groups, users, loan state, and transactions.
7. Notification and document-generation concerns are separated from core request handling. utils/email.js and views/email/*.pug indicate templated emails, including a loan request email flow. utils/cloudinary.js and middlewares/multer.middleware.js imply file upload support, probably for user or loan-related documents/images, with Cloudinary as external storage.
8. Error handling is standardized with shared helpers: ApiResponse, apiError, and asyncHandler. That points to a consistent API contract and centralized async error wrapping across controllers, which matters for drawing the backend boundary and understanding that route handlers are thin wrappers around reusable response logic.
9. On the frontend, the app is split by page-level workflows rather than by technical layers. Key pages include:
- authentication: Sign-in, Sign-up
- group management: Savings-Circles, GroupCreation, CreateLoan
- loan workflows: LoanOffers, LoanAgreement
- user views: Dashboard, Profile, Home
These pages map closely to the backend domain entities and are the main UI entry points.
10. The frontend component tree is built from reusable UI blocks and domain widgets. Components like Header, SideBar, AuthModal, TransactionModal, TransactionHistory, CreatedGroup, JoinedGroup, LoanGiven, and LoanTaken suggest the UI is organized around dashboards and operational views rather than a generic component library.
11. The frontend has a small service layer in src/services/apiROSCAgroup.js, which is the likely boundary where UI code calls backend endpoints. That means the architecture separates presentation concerns from API integration, making the data flow: page/component → service → backend route/controller → model/database.
12. Overall, the system is a community finance platform with two major flows:
- ROSCA group lifecycle: users authenticate, create/join groups, and view group status and contributions.
- Lending lifecycle: users request/offers/approve loans, the backend records agreements and transactions, and email notifications are sent for key events.
The architecture is intentionally domain-centric, with backend subsystems mirroring these finance workflows and the frontend pages reflecting them one-to-one.
Main entry points: app.js App wiring · loanOffer.controller.js Offer controller · apiROSCAgroup.js API service · user.controller.js User controller
Components 23
Backend
Node.js/Express API, domain logic, persistence, and notifications
- Server · Starts the API process
Backend/src/server.js - App wiring · Configures middleware and routes
Backend/src/app.js - Mongo DB · Connects the application to MongoDB
Backend/src/db/index.js - User routes · Account and auth endpoints
Backend/src/routes/user.routes.js - Group routes · ROSCA group endpoints
Backend/src/routes/roscaGroup.routes.js - Offer routes · Loan offer endpoints
Backend/src/routes/loanOffer.routes.js - Tx routes · Transaction endpoints
Backend/src/routes/transaction.routes.js - User controller · Account logic and auth flows
Backend/src/controllers/user.controller.js - Group controller · Group lifecycle and membership logic
Backend/src/controllers/roscaGroup.controller.js - Offer controller · Loan request and offer workflow
Backend/src/controllers/loanOffer.controller.js - Agreement controller · Final loan agreement handling
Backend/src/controllers/loanAgreement.controller.js - Transaction controller · Payment recording and history
Backend/src/controllers/transaction.controller.js - Auth middleware · Protects private API endpoints
Backend/src/middlewares/auth.middleware.js - Lender guard · Checks lender eligibility or privileges
Backend/src/middlewares/lenderVerify.js - Upload middleware · Handles multipart uploads
Backend/src/middlewares/multer.middleware.js - Domain models · User, group, offer, agreement, and transaction schemas
Backend/src/models/user.model.js - Shared utils · Async wrapping, responses, errors, storage, and email
Backend/src/utils/asyncHandler.js - Email templates · Templated notification emails
Backend/src/views/email/baseEmail.pug
Frontend
React/Vite UI for ROSCA and lending workflows
- App shell · Bootstraps the UI and layout
Frontend/src/App.jsx - Layout · Shared application frame
Frontend/src/layouts/AppLayout.jsx - API service · Frontend boundary for backend calls
Frontend/src/services/apiROSCAgroup.js - Pages · Authentication, dashboard, groups, and loan screens
Frontend/src/pages/Dashboard.jsx - Components · Reusable dashboard and modal widgets
Frontend/src/components/Header.jsx
Connections 30
- Server → App wiring: boots · Server starts the Express app
- App wiring → Mongo DB: connects · App initializes database access
- App wiring → User routes: mounts · Registers account routes
- App wiring → Group routes: mounts · Registers group routes
- App wiring → Offer routes: mounts · Registers loan offer routes
- App wiring → Tx routes: mounts · Registers transaction routes
- User routes → User controller: dispatches · Routes hand off to user handlers
- Group routes → Group controller: dispatches · Routes hand off to group handlers
- Offer routes → Offer controller: dispatches · Routes hand off to offer handlers
- Offer routes → Agreement controller: dispatches · Agreement endpoints share the loan flow
- Tx routes → Transaction controller: dispatches · Routes hand off to transaction handlers
- User controller → Auth middleware: uses · Protected account actions require auth
- Group controller → Auth middleware: uses · Group actions are auth-protected
- Offer controller → Auth middleware: uses · Loan actions require authenticated users
- Offer controller → Lender guard: uses · Lender-only actions require extra checks
- Group controller → Domain models: reads/writes · Controllers persist group state through models
- User controller → Domain models: reads/writes · Controllers persist user state through models
- Offer controller → Domain models: reads/writes · Controllers persist loan offer and agreement state
- Transaction controller → Domain models: reads/writes · Controllers persist transaction history
- Offer controller → Shared utils: uses · Emails, uploads, and response helpers support loan flows
- User controller → Shared utils: uses · Standard API responses and async error wrapping
- Shared utils → Email templates: renders · Email helper renders templated notifications
- App shell → Layout: wraps · App is composed into the shared layout
- Layout → Pages: hosts · Layout presents page-level workflows
- Pages → Components: composes · Pages assemble reusable widgets and modals
- Pages → API service: calls · Pages invoke backend API integration layer
- API service → User routes: HTTP API · Frontend calls backend account endpoints
- API service → Group routes: HTTP API · Frontend calls backend group endpoints
- API service → Offer routes: HTTP API · Frontend calls backend loan endpoints
- API service → Tx routes: HTTP API · Frontend calls backend transaction endpoints