# princes1-hash/impactlink architecture

> Architecture diagram of the GitHub repository princes1-hash/impactlink, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/princes1-hash/impactlink
- Repository: https://github.com/princes1-hash/impactlink

## Overview

1. **Overall shape**  
   This is a monolithic **Node.js + Express** application with a **server-rendered EJS UI** and a **MongoDB-backed data layer**. The app centers on an NGO/volunteer marketplace called **ImpactLink**.

2. **Request entry and routing**  
   `app.js` is the main composition point. It wires the HTTP server to the route modules under `routes/`, which split the app into functional areas: **auth**, **admin**, **NGO**, **volunteers**, **opportunities**, **applications**, and **impact**.

3. **Auth and role boundaries**  
   Authentication appears to be token-based, with `utils/generateToken.js` and `middlewares/authmiddleware.js` enforcing access control. The app has clearly separated roles: **admin**, **NGO**, and **volunteer**, each with its own dashboard and route surface.

4. **Controller layer**  
   Controllers are organized by domain and act as the application’s orchestration layer:
   - `authcontroller.js` handles login/register/onboarding flows.
   - `adminController.js` supports admin dashboard and oversight.
   - `ngoController.js`, `volunteerController.js`, `opportunitiesController.js`, `applicationController.js`, and `impactController.js` handle the core feature areas.
   - `projectController.js` suggests NGO/project creation flows alongside opportunities.

5. **Data model boundaries**  
   MongoDB collections are represented by models in `models/`:
   - `User`
   - `NGO`
   - `Volunteer`
   - `Opportunity`
   - `Application`
   - `ImpactLog`  
   These model the main business entities and the relationships between users, opportunities, applications, and impact reporting.

6. **Core business flow**  
   The main loop is: **NGO creates opportunities/projects → volunteers discover and apply → applications are stored and reviewed → impact is logged**. This is the primary data flow that drives the app’s dashboards and summary pages.

7. **Matching and discovery**  
   `services/matchEngine.js` is a distinct business-service boundary. It likely scores or ranks opportunities for volunteers and powers the **discover** experience and recommendation-like behavior rather than keeping that logic inside controllers.

8. **Presentation layer**  
   The UI is entirely server-rendered with EJS templates in `views/`. Key pages include:
   - landing/home and login/register/onboard
   - dashboard/profile
   - discover and opportunity details
   - NGO and volunteer dashboards
   - leaderboard and error pages  
   `views/partials/navbar.ejs` provides shared layout/navigation.

9. **Admin and reporting surfaces**  
   `views/leaderboard.ejs` plus `controllers/impactController.js` and `models/ImpactLog.js` indicate a reporting/recognition subsystem. The admin layer likely oversees seeded demo accounts, platform status, and aggregate impact/engagement views.

10. **Bootstrapping and demo data**  
   `seeds/seed.js` creates the demo environment described in the README: one admin, multiple NGOs, multiple volunteers, and many opportunities. This means the repository is designed to be runnable as a **demo system** with realistic sample data.

11. **Operational scripts and artifacts**  
   `scripts/add_leaderboard_demo.js` and `scripts/check_routes.js` are support utilities for demo content and route validation. The `cookies_*.txt` files appear to be saved browser/session artifacts for the sample accounts, useful for demoing authenticated roles.

12. **Infrastructure dependency**  
   MongoDB is the only external infrastructure explicitly required. The README notes that if MongoDB is unavailable, the server can still start, but data-driven pages become limited—so persistence is a core dependency, while the HTTP app itself is a separate runtime boundary.

Main entry points: [`app.js`](https://github.com/princes1-hash/impactlink/blob/main/app.js) (app.js), [`controllers/authcontroller.js`](https://github.com/princes1-hash/impactlink/blob/main/controllers/authcontroller.js) (Auth controller), [`controllers/volunteerController.js`](https://github.com/princes1-hash/impactlink/blob/main/controllers/volunteerController.js) (Volunteer controller), [`controllers/impactController.js`](https://github.com/princes1-hash/impactlink/blob/main/controllers/impactController.js) (Impact controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app["app.js<br/>Express entry<br/>[app.js]"]
  node_auth_mw["Auth guard<br/>middleware<br/>[authmiddleware.js]"]
  node_token_util["Token util<br/>jwt helper<br/>[generateToken.js]"]
end

subgraph group_domain["Domain"]
  node_auth_routes["Auth routes<br/>route module<br/>[auth.js]"]
  node_admin_routes["Admin routes<br/>route module<br/>[admin.js]"]
  node_ngo_routes["NGO routes<br/>route module<br/>[ngo.js]"]
  node_vol_routes["Volunteer routes<br/>route module<br/>[volunteers.js]"]
  node_opp_routes["Opportunity routes<br/>route module<br/>[opportunities.js]"]
  node_app_routes["Applications<br/>route module<br/>[applications.js]"]
  node_impact_routes["Impact routes<br/>route module<br/>[impact.js]"]
  node_auth_ctrl["Auth controller<br/>[authcontroller.js]"]
  node_ngo_ctrl["NGO controller<br/>[ngoController.js]"]
  node_vol_ctrl["Volunteer controller"]
  node_opp_ctrl["Opportunity controller"]
  node_app_ctrl["Application controller"]
  node_impact_ctrl["Impact controller"]
  node_match_engine{{"Match engine<br/>[matchEngine.js]"}}
  node_models[("Mongo models<br/>data models")]
end

subgraph group_ui["UI"]
  node_views["EJS views<br/>server-rendered UI"]
end

subgraph group_ops["Ops"]
  node_seed["Seed data<br/>demo bootstrap<br/>[seed.js]"]
  node_scripts["Demo scripts<br/>maintenance scripts"]
end

node_app -->|"mounts"| node_auth_routes
node_app -->|"mounts"| node_admin_routes
node_app -->|"mounts"| node_ngo_routes
node_app -->|"mounts"| node_vol_routes
node_app -->|"mounts"| node_opp_routes
node_app -->|"mounts"| node_app_routes
node_app -->|"mounts"| node_impact_routes
node_auth_routes -->|"uses"| node_auth_ctrl
node_admin_routes -->|"protects"| node_auth_mw
node_admin_routes -->|"uses"| node_impact_ctrl
node_ngo_routes -->|"protects"| node_auth_mw
node_ngo_routes -->|"uses"| node_ngo_ctrl
node_vol_routes -->|"protects"| node_auth_mw
node_vol_routes -->|"uses"| node_vol_ctrl
node_opp_routes -->|"uses"| node_opp_ctrl
node_app_routes -->|"uses"| node_app_ctrl
node_impact_routes -->|"uses"| node_impact_ctrl
node_auth_ctrl -->|"creates"| node_token_util
node_vol_ctrl -->|"scores"| node_match_engine
node_ngo_ctrl -->|"reads/writes"| node_models
node_vol_ctrl -->|"reads/writes"| node_models
node_opp_ctrl -->|"reads/writes"| node_models
node_app_ctrl -->|"reads/writes"| node_models
node_impact_ctrl -->|"reads/writes"| node_models
node_auth_ctrl -->|"reads/writes"| node_models
node_app -->|"renders"| node_views
node_auth_ctrl -->|"renders"| node_views
node_vol_ctrl -->|"renders"| node_views
node_ngo_ctrl -->|"renders"| node_views
node_impact_ctrl -->|"renders"| node_views
node_seed -->|"populates"| node_models
node_scripts -->|"supports"| node_seed

click node_app "https://github.com/princes1-hash/impactlink/blob/main/app.js"
click node_auth_mw "https://github.com/princes1-hash/impactlink/blob/main/middlewares/authmiddleware.js"
click node_token_util "https://github.com/princes1-hash/impactlink/blob/main/utils/generateToken.js"
click node_auth_routes "https://github.com/princes1-hash/impactlink/blob/main/routes/auth.js"
click node_admin_routes "https://github.com/princes1-hash/impactlink/blob/main/routes/admin.js"
click node_ngo_routes "https://github.com/princes1-hash/impactlink/blob/main/routes/ngo.js"
click node_vol_routes "https://github.com/princes1-hash/impactlink/blob/main/routes/volunteers.js"
click node_opp_routes "https://github.com/princes1-hash/impactlink/blob/main/routes/opportunities.js"
click node_app_routes "https://github.com/princes1-hash/impactlink/blob/main/routes/applications.js"
click node_impact_routes "https://github.com/princes1-hash/impactlink/blob/main/routes/impact.js"
click node_auth_ctrl "https://github.com/princes1-hash/impactlink/blob/main/controllers/authcontroller.js"
click node_ngo_ctrl "https://github.com/princes1-hash/impactlink/blob/main/controllers/ngoController.js"
click node_vol_ctrl "https://github.com/princes1-hash/impactlink/blob/main/controllers/volunteerController.js"
click node_opp_ctrl "https://github.com/princes1-hash/impactlink/blob/main/controllers/opportunitiesController.js"
click node_app_ctrl "https://github.com/princes1-hash/impactlink/blob/main/controllers/applicationController.js"
click node_impact_ctrl "https://github.com/princes1-hash/impactlink/blob/main/controllers/impactController.js"
click node_match_engine "https://github.com/princes1-hash/impactlink/blob/main/services/matchEngine.js"
click node_seed "https://github.com/princes1-hash/impactlink/blob/main/seeds/seed.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_app,node_auth_mw,node_token_util toneBlue
class node_auth_routes,node_admin_routes,node_ngo_routes,node_vol_routes,node_opp_routes,node_app_routes,node_impact_routes,node_auth_ctrl,node_ngo_ctrl,node_vol_ctrl,node_opp_ctrl,node_app_ctrl,node_impact_ctrl,node_match_engine,node_models toneAmber
class node_views toneMint
class node_seed,node_scripts toneRose
```

## Components

### Runtime

Express app composition and cross-cutting request handling

- [app.js](https://github.com/princes1-hash/impactlink/blob/main/app.js): Express entry · Main server composition and route wiring · `app.js`
- [Auth guard](https://github.com/princes1-hash/impactlink/blob/main/middlewares/authmiddleware.js): middleware · Token-based access control for protected routes · `middlewares/authmiddleware.js`
- [Token util](https://github.com/princes1-hash/impactlink/blob/main/utils/generateToken.js): jwt helper · Creates authentication tokens · `utils/generateToken.js`

### Domain

Feature routes, controllers, services, and data models

- [Auth routes](https://github.com/princes1-hash/impactlink/blob/main/routes/auth.js): route module · Login, register, and onboarding endpoints · `routes/auth.js`
- [Admin routes](https://github.com/princes1-hash/impactlink/blob/main/routes/admin.js): route module · Admin dashboard and oversight endpoints · `routes/admin.js`
- [NGO routes](https://github.com/princes1-hash/impactlink/blob/main/routes/ngo.js): route module · NGO dashboard and project flows · `routes/ngo.js`
- [Volunteer routes](https://github.com/princes1-hash/impactlink/blob/main/routes/volunteers.js): route module · Volunteer profile and discovery endpoints · `routes/volunteers.js`
- [Opportunity routes](https://github.com/princes1-hash/impactlink/blob/main/routes/opportunities.js): route module · Opportunity discovery and detail endpoints · `routes/opportunities.js`
- [Applications](https://github.com/princes1-hash/impactlink/blob/main/routes/applications.js): route module · Volunteer application submission and review endpoints · `routes/applications.js`
- [Impact routes](https://github.com/princes1-hash/impactlink/blob/main/routes/impact.js): route module · Impact reporting and leaderboard endpoints · `routes/impact.js`
- [Auth controller](https://github.com/princes1-hash/impactlink/blob/main/controllers/authcontroller.js): controller · Authentication and onboarding orchestration · `controllers/authcontroller.js`
- [NGO controller](https://github.com/princes1-hash/impactlink/blob/main/controllers/ngoController.js): controller · NGO dashboard and project management · `controllers/ngoController.js`
- [Volunteer controller](https://github.com/princes1-hash/impactlink/blob/main/controllers/volunteerController.js): controller · Volunteer profile and discovery orchestration · `controllers/volunteerController.js`
- [Opportunity controller](https://github.com/princes1-hash/impactlink/blob/main/controllers/opportunitiesController.js): controller · Opportunity browsing and detail logic · `controllers/opportunitiesController.js`
- [Application controller](https://github.com/princes1-hash/impactlink/blob/main/controllers/applicationController.js): controller · Application lifecycle and review logic · `controllers/applicationController.js`
- [Impact controller](https://github.com/princes1-hash/impactlink/blob/main/controllers/impactController.js): controller · Impact aggregation and leaderboard data · `controllers/impactController.js`
- [Match engine](https://github.com/princes1-hash/impactlink/blob/main/services/matchEngine.js): service · Ranks or matches opportunities for volunteers · `services/matchEngine.js`
- **Mongo models**: data models · Core entities for users, NGOs, volunteers, opportunities, applications, and impact logs

### UI

Server-rendered EJS pages and shared presentation

- **EJS views**: server-rendered UI · Pages for home, auth, dashboards, discovery, profile, and leaderboard

### Ops

Demo data and maintenance scripts

- [Seed data](https://github.com/princes1-hash/impactlink/blob/main/seeds/seed.js): demo bootstrap · Creates demo admin, NGOs, volunteers, and opportunities · `seeds/seed.js`
- **Demo scripts**: maintenance scripts · Route checks and leaderboard demo helpers

## Connections

- app.js → Auth routes: mounts · Registers authentication routes
- app.js → Admin routes: mounts · Registers admin routes
- app.js → NGO routes: mounts · Registers NGO routes
- app.js → Volunteer routes: mounts · Registers volunteer routes
- app.js → Opportunity routes: mounts · Registers opportunity routes
- app.js → Applications: mounts · Registers application routes
- app.js → Impact routes: mounts · Registers impact routes
- Auth routes → Auth controller: uses · Delegates auth flows to controller
- Admin routes → Auth guard: protects · Restricts admin access
- Admin routes → Impact controller: uses · Admin oversight and reporting
- NGO routes → Auth guard: protects · Requires authenticated NGO access
- NGO routes → NGO controller: uses · Delegates NGO dashboard actions
- Volunteer routes → Auth guard: protects · Requires authenticated volunteer access
- Volunteer routes → Volunteer controller: uses · Delegates volunteer flows
- Opportunity routes → Opportunity controller: uses · Delegates discovery and detail handling
- Applications → Application controller: uses · Delegates application workflow
- Impact routes → Impact controller: uses · Delegates impact reporting
- Auth controller → Token util: creates · Issues auth tokens
- Volunteer controller → Match engine: scores · Supports discover and recommendation behavior
- NGO controller → Mongo models: reads/writes · Persists NGOs, projects, and related data
- Volunteer controller → Mongo models: reads/writes · Persists volunteer profile data
- Opportunity controller → Mongo models: reads/writes · Persists and retrieves opportunities
- Application controller → Mongo models: reads/writes · Stores applications and status changes
- Impact controller → Mongo models: reads/writes · Stores and aggregates impact logs
- Auth controller → Mongo models: reads/writes · Creates and authenticates users
- app.js → EJS views: renders · Serves EJS pages
- Auth controller → EJS views: renders · Login, register, and onboard screens
- Volunteer controller → EJS views: renders · Discovery, profile, and dashboard pages
- NGO controller → EJS views: renders · NGO dashboard and project form pages
- Impact controller → EJS views: renders · Leaderboard and reporting pages
- Seed data → Mongo models: populates · Seeds demo entities into MongoDB
- Demo scripts → Seed data: supports · Maintenance and demo setup tasks