# nasablueberry/alo architecture

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

## Overview

1. **Overall shape**
   - This is a two-tier MERN system: a **Node/Express backend** exposes JSON APIs, and a **React/Vite frontend** consumes them.
   - The domain is scholarship aid management for Bangladesh: student intake, provider programs, application review, disbursement, and admin oversight.

2. **Backend boundary**
   - The backend is the system of record and contains the business rules.
   - It is organized into `controllers` for request handling, `routes` for API wiring, `middleware` for auth/validation/error handling, `services` for domain logic, and `models` for MongoDB persistence via Mongoose.

3. **Frontend boundary**
   - The client is a single-page app with role-specific pages for **student**, **provider**, and **admin** users.
   - Shared UI shells, dashboards, and context providers handle auth state, theme, and language; the app is not server-rendered.

4. **Identity and role model**
   - Authentication is JWT-based and role-aware: student, provider, and admin.
   - Protected routes on the backend rely on auth middleware; the frontend likely gates navigation using `AuthContext`.
   - Separate registration flows exist for students and providers, with admin accounts created via a script or seed data.

5. **Core domain data**
   - MongoDB collections model the main entities: `User`, `StudentProfile`, `AidProvider`, `ScholarshipProgram`, `Application`, `Disbursement`, `Notification`, `AuditLog`, and withdrawal-related records.
   - This separation indicates a clean domain boundary between identity, profile data, program data, application workflow, and financial actions.

6. **Student intake and document handling**
   - Student registration includes academic and regional information plus document upload.
   - File uploads are handled by `multer`, and uploaded PDFs are stored locally under `backend/uploads`, which means document persistence is filesystem-based rather than object storage-based.

7. **Program and provider workflow**
   - Providers can create, update, and close scholarship programs with eligibility criteria and fund allocation.
   - The provider-facing pages cover dashboard, program creation, application review, rejected applicants, and provider profile management.
   - Program management is a major bounded context separate from student application management.

8. **Application review pipeline**
   - Applications move through an eligibility and ranking pipeline before approval/rejection.
   - Services such as `eligibility`, `applicantRanking`, `financialNeedScore`, and `duplicateDetection` indicate that review is not purely manual; the backend computes decision support and conflict warnings.
   - The application route set supports applying, listing personal applications, viewing program applicants, and reviewing submissions.

9. **Admin operations**
   - Admin functionality is broader than CRUD: it includes student verification, at-risk analysis, fraud/rejection review, fund utilization visibility, and report generation.
   - The admin dashboard pages mirror these operational concerns and are backed by dedicated admin/analytics controllers.

10. **Risk, fraud, and auditability**
   - The presence of `dropoutRisk`, `duplicateDetection`, and `auditLog` services shows that the system actively evaluates student risk and aid conflicts.
   - Audit logging is an important cross-cutting concern, likely triggered by sensitive operations such as approval, disbursement, and verification.

11. **Notifications and email**
   - Notifications are modeled in the database and exposed through a dedicated API.
   - Email delivery is handled through utility code and likely uses SMTP via Nodemailer, making notification delivery a side effect of important workflow events.

12. **Reporting and analytics**
   - There is a distinct analytics/reporting slice with regional impact aggregation and report generation.
   - Backend report utilities suggest exported formats such as CSV/PDF, which are operational outputs rather than user-facing pages.

13. **Main request flow**
   - Typical flow: user authenticates → frontend stores token and role → API requests hit protected routes → controllers invoke services → Mongoose models persist changes → notifications/audit logs are written as side effects.
   - This separation keeps HTTP handling, business rules, and persistence distinct.

14. **Operational tooling and deployment**
   - The repo includes seed/admin scripts for populating development data and creating an admin account.
   - `render.yaml` and `vercel.json` indicate deployment targets for backend and frontend respectively, reinforcing the split runtime model.

Main entry points: [`client/src/App.jsx`](https://github.com/nasablueberry/alo/blob/main/client/src/App.jsx) (SPA App), [`backend/src/index.js`](https://github.com/nasablueberry/alo/blob/main/backend/src/index.js) (API Server), [`backend/src/controllers/application.controller.js`](https://github.com/nasablueberry/alo/blob/main/backend/src/controllers/application.controller.js) (Application Ctrl), [`backend/src/models/User.model.js`](https://github.com/nasablueberry/alo/blob/main/backend/src/models/User.model.js) (Domain Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_server["API Server<br/>express-app<br/>[index.js]"]
  node_backend_auth_routes["Auth API<br/>routes<br/>[auth.routes.js]"]
  node_backend_app_routes["Application API<br/>routes"]
  node_backend_program_routes["Program API<br/>routes<br/>[program.routes.js]"]
  node_backend_admin_routes["Admin API<br/>routes<br/>[admin.routes.js]"]
  node_backend_student_ctrl["Student Ctrl<br/>controller"]
  node_backend_provider_ctrl["Provider Ctrl<br/>controller"]
  node_backend_admin_ctrl["Admin Ctrl<br/>controller"]
  node_backend_application_ctrl["Application Ctrl<br/>controller"]
  node_backend_program_ctrl["Program Ctrl<br/>controller"]
  node_backend_services{{"Decision Services<br/>domain-services"}}
  node_backend_models[("Domain Models<br/>mongoose-models<br/>[User.model.js]")]
  node_backend_uploads["Local Uploads<br/>filesystem"]
  node_backend_notifications["Notify & Audit<br/>side-effects<br/>[email.js]"]
end

subgraph group_client["Frontend"]
  node_client_app["SPA App<br/>react-spa<br/>[App.jsx]"]
  node_client_auth(("Auth State<br/>context<br/>[AuthContext.jsx]"))
  node_client_shell["UI Shell<br/>layout<br/>[Layout.jsx]"]
  node_client_student_pages["Student Area<br/>pages"]
  node_client_provider_pages["Provider Area<br/>pages"]
  node_client_admin_pages["Admin Area<br/>pages<br/>[AdminDashboard.jsx]"]
  node_client_program_pages["Public Programs<br/>pages<br/>[ProgramsList.jsx]"]
end

node_client_app -->|"session"| node_client_auth
node_client_app -->|"layout"| node_client_shell
node_client_app -->|"student routes"| node_client_student_pages
node_client_app -->|"provider routes"| node_client_provider_pages
node_client_app -->|"admin routes"| node_client_admin_pages
node_client_app -->|"browse/apply"| node_client_program_pages
node_client_app -.->|"API calls"| node_backend_server
node_backend_server -->|"mounts"| node_backend_auth_routes
node_backend_server -->|"mounts"| node_backend_app_routes
node_backend_server -->|"mounts"| node_backend_program_routes
node_backend_server -->|"mounts"| node_backend_admin_routes
node_backend_auth_routes -->|"register student"| node_backend_student_ctrl
node_backend_auth_routes -->|"register provider"| node_backend_provider_ctrl
node_backend_app_routes -->|"orchestrates"| node_backend_application_ctrl
node_backend_program_routes -->|"orchestrates"| node_backend_program_ctrl
node_backend_admin_routes -->|"orchestrates"| node_backend_admin_ctrl
node_backend_application_ctrl -->|"scores/reviews"| node_backend_services
node_backend_admin_ctrl -->|"risk checks"| node_backend_services
node_backend_student_ctrl -->|"persists"| node_backend_models
node_backend_provider_ctrl -->|"persists"| node_backend_models
node_backend_application_ctrl -->|"persists"| node_backend_models
node_backend_program_ctrl -->|"persists"| node_backend_models
node_backend_application_ctrl -->|"stores docs"| node_backend_uploads
node_backend_admin_ctrl -->|"side effects"| node_backend_notifications
node_backend_application_ctrl -->|"side effects"| node_backend_notifications
node_backend_program_ctrl -->|"side effects"| node_backend_notifications

click node_client_app "https://github.com/nasablueberry/alo/blob/main/client/src/App.jsx"
click node_client_auth "https://github.com/nasablueberry/alo/blob/main/client/src/context/AuthContext.jsx"
click node_client_shell "https://github.com/nasablueberry/alo/blob/main/client/src/components/Layout.jsx"
click node_client_student_pages "https://github.com/nasablueberry/alo/blob/main/client/src/pages/StudentDashboard.jsx"
click node_client_provider_pages "https://github.com/nasablueberry/alo/blob/main/client/src/pages/ProviderDashboard.jsx"
click node_client_admin_pages "https://github.com/nasablueberry/alo/blob/main/client/src/pages/AdminDashboard.jsx"
click node_client_program_pages "https://github.com/nasablueberry/alo/blob/main/client/src/pages/ProgramsList.jsx"
click node_backend_server "https://github.com/nasablueberry/alo/blob/main/backend/src/index.js"
click node_backend_auth_routes "https://github.com/nasablueberry/alo/blob/main/backend/src/routes/auth.routes.js"
click node_backend_app_routes "https://github.com/nasablueberry/alo/blob/main/backend/src/routes/application.routes.js"
click node_backend_program_routes "https://github.com/nasablueberry/alo/blob/main/backend/src/routes/program.routes.js"
click node_backend_admin_routes "https://github.com/nasablueberry/alo/blob/main/backend/src/routes/admin.routes.js"
click node_backend_student_ctrl "https://github.com/nasablueberry/alo/blob/main/backend/src/controllers/student.controller.js"
click node_backend_provider_ctrl "https://github.com/nasablueberry/alo/blob/main/backend/src/controllers/provider.controller.js"
click node_backend_admin_ctrl "https://github.com/nasablueberry/alo/blob/main/backend/src/controllers/admin.controller.js"
click node_backend_application_ctrl "https://github.com/nasablueberry/alo/blob/main/backend/src/controllers/application.controller.js"
click node_backend_program_ctrl "https://github.com/nasablueberry/alo/blob/main/backend/src/controllers/program.controller.js"
click node_backend_services "https://github.com/nasablueberry/alo/blob/main/backend/src/services/eligibility.service.js"
click node_backend_models "https://github.com/nasablueberry/alo/blob/main/backend/src/models/User.model.js"
click node_backend_uploads "https://github.com/nasablueberry/alo/tree/main/backend/uploads"
click node_backend_notifications "https://github.com/nasablueberry/alo/blob/main/backend/src/utils/email.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_backend_server,node_backend_auth_routes,node_backend_app_routes,node_backend_program_routes,node_backend_admin_routes,node_backend_student_ctrl,node_backend_provider_ctrl,node_backend_admin_ctrl,node_backend_application_ctrl,node_backend_program_ctrl,node_backend_services,node_backend_models,node_backend_uploads,node_backend_notifications toneBlue
class node_client_app,node_client_auth,node_client_shell,node_client_student_pages,node_client_provider_pages,node_client_admin_pages,node_client_program_pages toneAmber
```

## Components

### Backend

Node/Express API and domain logic

- [API Server](https://github.com/nasablueberry/alo/blob/main/backend/src/index.js): express-app · Express bootstrap and route mounting · `backend/src/index.js`
- [Auth API](https://github.com/nasablueberry/alo/blob/main/backend/src/routes/auth.routes.js): routes · Login and registration endpoints · `backend/src/routes/auth.routes.js`
- [Application API](https://github.com/nasablueberry/alo/blob/main/backend/src/routes/application.routes.js): routes · Apply, list, and review applications · `backend/src/routes/application.routes.js`
- [Program API](https://github.com/nasablueberry/alo/blob/main/backend/src/routes/program.routes.js): routes · Provider program management endpoints · `backend/src/routes/program.routes.js`
- [Admin API](https://github.com/nasablueberry/alo/blob/main/backend/src/routes/admin.routes.js): routes · Verification, fraud, disbursement, and oversight endpoints · `backend/src/routes/admin.routes.js`
- [Student Ctrl](https://github.com/nasablueberry/alo/blob/main/backend/src/controllers/student.controller.js): controller · Student profile and intake handling · `backend/src/controllers/student.controller.js`
- [Provider Ctrl](https://github.com/nasablueberry/alo/blob/main/backend/src/controllers/provider.controller.js): controller · Provider profile and program ownership · `backend/src/controllers/provider.controller.js`
- [Admin Ctrl](https://github.com/nasablueberry/alo/blob/main/backend/src/controllers/admin.controller.js): controller · Administrative review and operations · `backend/src/controllers/admin.controller.js`
- [Application Ctrl](https://github.com/nasablueberry/alo/blob/main/backend/src/controllers/application.controller.js): controller · Application submission and review orchestration · `backend/src/controllers/application.controller.js`
- [Program Ctrl](https://github.com/nasablueberry/alo/blob/main/backend/src/controllers/program.controller.js): controller · Scholarship program CRUD and status changes · `backend/src/controllers/program.controller.js`
- [Decision Services](https://github.com/nasablueberry/alo/blob/main/backend/src/services/eligibility.service.js): domain-services · Eligibility, ranking, need, risk, and duplicate checks · `backend/src/services/eligibility.service.js`
- [Domain Models](https://github.com/nasablueberry/alo/blob/main/backend/src/models/User.model.js): mongoose-models · Users, profiles, programs, applications, disbursements, notifications, audits · `backend/src/models/User.model.js`
- [Local Uploads](https://github.com/nasablueberry/alo/tree/main/backend/uploads): filesystem · Stored PDF documents for applications and verification · `backend/uploads`
- [Notify & Audit](https://github.com/nasablueberry/alo/blob/main/backend/src/utils/email.js): side-effects · Email, notifications, and audit logging · `backend/src/utils/email.js`

### Frontend

React/Vite SPA for role-based users

- [SPA App](https://github.com/nasablueberry/alo/blob/main/client/src/App.jsx): react-spa · Client entry and route composition · `client/src/App.jsx`
- [Auth State](https://github.com/nasablueberry/alo/blob/main/client/src/context/AuthContext.jsx): context · Token, role, and session state · `client/src/context/AuthContext.jsx`
- [UI Shell](https://github.com/nasablueberry/alo/blob/main/client/src/components/Layout.jsx): layout · Shared layout, header, footer, dashboard shell · `client/src/components/Layout.jsx`
- [Student Area](https://github.com/nasablueberry/alo/blob/main/client/src/pages/StudentDashboard.jsx): pages · Student dashboard, applications, profile, withdraw flow · `client/src/pages/StudentDashboard.jsx`
- [Provider Area](https://github.com/nasablueberry/alo/blob/main/client/src/pages/ProviderDashboard.jsx): pages · Provider dashboard, program creation, review, rejections · `client/src/pages/ProviderDashboard.jsx`
- [Admin Area](https://github.com/nasablueberry/alo/blob/main/client/src/pages/AdminDashboard.jsx): pages · Admin dashboard and oversight screens · `client/src/pages/AdminDashboard.jsx`
- [Public Programs](https://github.com/nasablueberry/alo/blob/main/client/src/pages/ProgramsList.jsx): pages · Program listing and application entry points · `client/src/pages/ProgramsList.jsx`

## Connections

- SPA App → Auth State: session · App reads auth state for role-aware navigation
- SPA App → UI Shell: layout · Routes render inside shared shell
- SPA App → Student Area: student routes · Student-facing pages are mounted in the SPA
- SPA App → Provider Area: provider routes · Provider-facing pages are mounted in the SPA
- SPA App → Admin Area: admin routes · Admin-facing pages are mounted in the SPA
- SPA App → Public Programs: browse/apply · Public program browsing and application entry
- SPA App → API Server: API calls · Frontend consumes backend JSON endpoints
- API Server → Auth API: mounts · Authentication routes are registered on the server
- API Server → Application API: mounts · Application routes are registered on the server
- API Server → Program API: mounts · Program routes are registered on the server
- API Server → Admin API: mounts · Admin routes are registered on the server
- Auth API → Student Ctrl: register student · Student signup flows through student controller
- Auth API → Provider Ctrl: register provider · Provider signup flows through provider controller
- Application API → Application Ctrl: orchestrates · Application route handlers delegate to application controller
- Program API → Program Ctrl: orchestrates · Program route handlers delegate to program controller
- Admin API → Admin Ctrl: orchestrates · Admin route handlers delegate to admin controller
- Application Ctrl → Decision Services: scores/reviews · Eligibility, ranking, need, and duplicate checks support decisions
- Admin Ctrl → Decision Services: risk checks · Admin review uses risk and conflict analysis
- Student Ctrl → Domain Models: persists · Student data is stored in MongoDB models
- Provider Ctrl → Domain Models: persists · Provider data is stored in MongoDB models
- Application Ctrl → Domain Models: persists · Applications, disbursements, and audit-related records are stored in models
- Program Ctrl → Domain Models: persists · Scholarship programs and provider-owned records are stored in models
- Application Ctrl → Local Uploads: stores docs · Uploaded PDF documents are saved locally
- Admin Ctrl → Notify & Audit: side effects · Sensitive actions trigger notifications, email, and audit logging
- Application Ctrl → Notify & Audit: side effects · Application events emit notifications and audit entries
- Program Ctrl → Notify & Audit: side effects · Program changes can notify stakeholders