# kandarpvyas2591/digital-rosca architecture

> Architecture diagram of the GitHub repository kandarpvyas2591/digital-rosca, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kandarpvyas2591/digital-rosca
- Repository: https://github.com/kandarpvyas2591/digital-rosca

## Overview

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: [`Backend/src/app.js`](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/app.js) (App wiring), [`Backend/src/controllers/loanOffer.controller.js`](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/controllers/loanOffer.controller.js) (Offer controller), [`Frontend/src/services/apiROSCAgroup.js`](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Frontend/src/services/apiROSCAgroup.js) (API service), [`Backend/src/controllers/user.controller.js`](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/controllers/user.controller.js) (User controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_be_server(("Server<br/>process entrypoint<br/>[server.js]"))
  node_be_app["App wiring<br/>express app<br/>[app.js]"]
  node_be_db[("Mongo DB<br/>database bootstrap<br/>[index.js]")]
  node_be_routes_user["User routes<br/>api routes<br/>[user.routes.js]"]
  node_be_routes_group["Group routes<br/>api routes"]
  node_be_routes_offer["Offer routes<br/>api routes"]
  node_be_routes_tx["Tx routes<br/>api routes"]
  node_be_ctrl_user["User controller<br/>request handlers<br/>[user.controller.js]"]
  node_be_ctrl_group["Group controller<br/>domain logic"]
  node_be_ctrl_offer["Offer controller<br/>domain logic"]
  node_be_ctrl_agreement["Agreement controller<br/>domain logic"]
  node_be_ctrl_tx["Transaction controller<br/>domain logic"]
  node_be_mw_auth{{"Auth middleware<br/>request guard<br/>[auth.middleware.js]"}}
  node_be_mw_lender{{"Lender guard<br/>role guard<br/>[lenderVerify.js]"}}
  node_be_mw_upload{{"Upload middleware<br/>file upload"}}
  node_be_models[("Domain models<br/>mongoose models<br/>[user.model.js]")]
  node_be_utils["Shared utils<br/>helpers<br/>[asyncHandler.js]"]
  node_be_email_views["Email templates<br/>pug views<br/>[baseEmail.pug]"]
end

subgraph group_frontend["Frontend"]
  node_fe_app(("App shell<br/>react entry<br/>[App.jsx]"))
  node_fe_layout["Layout<br/>[AppLayout.jsx]"]
  node_fe_service["API service<br/>http client<br/>[apiROSCAgroup.js]"]
  node_fe_pages["Pages<br/>page views<br/>[Dashboard.jsx]"]
  node_fe_components["Components<br/>[Header.jsx]"]
end

node_be_server -->|"boots"| node_be_app
node_be_app -->|"connects"| node_be_db
node_be_app -->|"mounts"| node_be_routes_user
node_be_app -->|"mounts"| node_be_routes_group
node_be_app -->|"mounts"| node_be_routes_offer
node_be_app -->|"mounts"| node_be_routes_tx
node_be_routes_user -->|"dispatches"| node_be_ctrl_user
node_be_routes_group -->|"dispatches"| node_be_ctrl_group
node_be_routes_offer -->|"dispatches"| node_be_ctrl_offer
node_be_routes_offer -->|"dispatches"| node_be_ctrl_agreement
node_be_routes_tx -->|"dispatches"| node_be_ctrl_tx
node_be_ctrl_user -->|"uses"| node_be_mw_auth
node_be_ctrl_group -->|"uses"| node_be_mw_auth
node_be_ctrl_offer -->|"uses"| node_be_mw_auth
node_be_ctrl_offer -->|"uses"| node_be_mw_lender
node_be_ctrl_group -->|"reads/writes"| node_be_models
node_be_ctrl_user -->|"reads/writes"| node_be_models
node_be_ctrl_offer -->|"reads/writes"| node_be_models
node_be_ctrl_tx -->|"reads/writes"| node_be_models
node_be_ctrl_offer -->|"uses"| node_be_utils
node_be_ctrl_user -->|"uses"| node_be_utils
node_be_utils -->|"renders"| node_be_email_views
node_fe_app -->|"wraps"| node_fe_layout
node_fe_layout -->|"hosts"| node_fe_pages
node_fe_pages -->|"composes"| node_fe_components
node_fe_pages -->|"calls"| node_fe_service
node_fe_service -.->|"HTTP API"| node_be_routes_user
node_fe_service -.->|"HTTP API"| node_be_routes_group
node_fe_service -.->|"HTTP API"| node_be_routes_offer
node_fe_service -.->|"HTTP API"| node_be_routes_tx

click node_be_server "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/server.js"
click node_be_app "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/app.js"
click node_be_db "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/db/index.js"
click node_be_routes_user "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/routes/user.routes.js"
click node_be_routes_group "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/routes/roscaGroup.routes.js"
click node_be_routes_offer "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/routes/loanOffer.routes.js"
click node_be_routes_tx "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/routes/transaction.routes.js"
click node_be_ctrl_user "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/controllers/user.controller.js"
click node_be_ctrl_group "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/controllers/roscaGroup.controller.js"
click node_be_ctrl_offer "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/controllers/loanOffer.controller.js"
click node_be_ctrl_agreement "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/controllers/loanAgreement.controller.js"
click node_be_ctrl_tx "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/controllers/transaction.controller.js"
click node_be_mw_auth "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/middlewares/auth.middleware.js"
click node_be_mw_lender "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/middlewares/lenderVerify.js"
click node_be_mw_upload "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/middlewares/multer.middleware.js"
click node_be_models "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/models/user.model.js"
click node_be_utils "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/utils/asyncHandler.js"
click node_be_email_views "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/views/email/baseEmail.pug"
click node_fe_app "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Frontend/src/App.jsx"
click node_fe_layout "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Frontend/src/layouts/AppLayout.jsx"
click node_fe_service "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Frontend/src/services/apiROSCAgroup.js"
click node_fe_pages "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Frontend/src/pages/Dashboard.jsx"
click node_fe_components "https://github.com/kandarpvyas2591/digital-rosca/blob/master/Frontend/src/components/Header.jsx"

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_be_server,node_be_app,node_be_db,node_be_routes_user,node_be_routes_group,node_be_routes_offer,node_be_routes_tx,node_be_ctrl_user,node_be_ctrl_group,node_be_ctrl_offer,node_be_ctrl_agreement,node_be_ctrl_tx,node_be_mw_auth,node_be_mw_lender,node_be_mw_upload,node_be_models,node_be_utils,node_be_email_views toneBlue
class node_fe_app,node_fe_layout,node_fe_service,node_fe_pages,node_fe_components toneAmber
```

## Components

### Backend

Node.js/Express API, domain logic, persistence, and notifications

- [Server](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/server.js): process entrypoint · Starts the API process · `Backend/src/server.js`
- [App wiring](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/app.js): express app · Configures middleware and routes · `Backend/src/app.js`
- [Mongo DB](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/db/index.js): database bootstrap · Connects the application to MongoDB · `Backend/src/db/index.js`
- [User routes](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/routes/user.routes.js): api routes · Account and auth endpoints · `Backend/src/routes/user.routes.js`
- [Group routes](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/routes/roscaGroup.routes.js): api routes · ROSCA group endpoints · `Backend/src/routes/roscaGroup.routes.js`
- [Offer routes](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/routes/loanOffer.routes.js): api routes · Loan offer endpoints · `Backend/src/routes/loanOffer.routes.js`
- [Tx routes](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/routes/transaction.routes.js): api routes · Transaction endpoints · `Backend/src/routes/transaction.routes.js`
- [User controller](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/controllers/user.controller.js): request handlers · Account logic and auth flows · `Backend/src/controllers/user.controller.js`
- [Group controller](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/controllers/roscaGroup.controller.js): domain logic · Group lifecycle and membership logic · `Backend/src/controllers/roscaGroup.controller.js`
- [Offer controller](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/controllers/loanOffer.controller.js): domain logic · Loan request and offer workflow · `Backend/src/controllers/loanOffer.controller.js`
- [Agreement controller](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/controllers/loanAgreement.controller.js): domain logic · Final loan agreement handling · `Backend/src/controllers/loanAgreement.controller.js`
- [Transaction controller](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/controllers/transaction.controller.js): domain logic · Payment recording and history · `Backend/src/controllers/transaction.controller.js`
- [Auth middleware](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/middlewares/auth.middleware.js): request guard · Protects private API endpoints · `Backend/src/middlewares/auth.middleware.js`
- [Lender guard](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/middlewares/lenderVerify.js): role guard · Checks lender eligibility or privileges · `Backend/src/middlewares/lenderVerify.js`
- [Upload middleware](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/middlewares/multer.middleware.js): file upload · Handles multipart uploads · `Backend/src/middlewares/multer.middleware.js`
- [Domain models](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/models/user.model.js): mongoose models · User, group, offer, agreement, and transaction schemas · `Backend/src/models/user.model.js`
- [Shared utils](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/utils/asyncHandler.js): helpers · Async wrapping, responses, errors, storage, and email · `Backend/src/utils/asyncHandler.js`
- [Email templates](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Backend/src/views/email/baseEmail.pug): pug views · Templated notification emails · `Backend/src/views/email/baseEmail.pug`

### Frontend

React/Vite UI for ROSCA and lending workflows

- [App shell](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Frontend/src/App.jsx): react entry · Bootstraps the UI and layout · `Frontend/src/App.jsx`
- [Layout](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Frontend/src/layouts/AppLayout.jsx): ui layout · Shared application frame · `Frontend/src/layouts/AppLayout.jsx`
- [API service](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Frontend/src/services/apiROSCAgroup.js): http client · Frontend boundary for backend calls · `Frontend/src/services/apiROSCAgroup.js`
- [Pages](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Frontend/src/pages/Dashboard.jsx): page views · Authentication, dashboard, groups, and loan screens · `Frontend/src/pages/Dashboard.jsx`
- [Components](https://github.com/kandarpvyas2591/digital-rosca/blob/master/Frontend/src/components/Header.jsx): ui components · Reusable dashboard and modal widgets · `Frontend/src/components/Header.jsx`

## Connections

- 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