# dharshancr/college-management-system architecture

> Architecture diagram of the GitHub repository dharshancr/college-management-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dharshancr/college-management-system
- Repository: https://github.com/dharshancr/college-management-system

## Overview

#### Purpose and entry points
NGI is a full-stack college-management system covering student, faculty, HR, and admissions workflows. The React SPA starts at `client/src/main.jsx`, with application state and view selection centralized in `client/src/App.jsx`. The Express API starts at `server/index.js`; root scripts in `package.json` coordinate client/server development and seeding.

#### Client application shell and access
`client/src/App.jsx` is the client-side orchestration boundary: it manages authentication/session state, selected module, API-backed data, and role-sensitive rendering. Shared navigation and global interactions are split across `client/src/components/Navbar.jsx`, `client/src/components/Sidebar.jsx`, `client/src/components/LoginModal.jsx`, and `client/src/components/NotificationDrawer.jsx`. The frontend is a Vite-built React 18 application with Tailwind CSS; production assets are emitted to `client/dist`.

#### Domain module views
Feature UI is organized as independently rendered page modules, while sharing the shell and central application state:
- Student dashboard, reminders, attendance, fees, grades: `client/src/pages/DashboardView.jsx`, `client/src/pages/RemindersView.jsx`, `client/src/pages/AttendanceView.jsx`.
- Academic scheduling and library circulation: `client/src/pages/TimetableScheduleView.jsx`, `client/src/pages/LibraryView.jsx`.
- Administrative workflows: `client/src/pages/AdmissionsView.jsx`, `client/src/pages/HRPayrollView.jsx`.
- Campus messaging/announcements: `client/src/pages/CommunicationView.jsx`.

These views represent the principal user-facing workflow boundary rather than separate client routes.

#### API, authorization, and workflow control
`server/index.js` is the single REST API surface for the ten functional areas. It owns request validation/control flow, JWT authentication, role-based authorization, and mutations such as attendance events, payments/receipts, grade publishing, admission stage changes, payroll actions, and messages. Browser requests reach it directly in deployed environments or through the Vite development proxy configured by `client/vite.config.js`. JWT, bcrypt, and CORS are material backend dependencies.

#### Persistence and lifecycle
`server/db.js` provides the persistent cross-platform JSON/SQLite-style database abstraction consumed by the API. Persisted data is represented in `server/college_db.json`; `server/seed.js` initializes or refreshes the demo dataset. This is the core infrastructure boundary: clients never access database records directly, and all durable state changes pass through API handlers and the DB layer.

#### Primary flows
1. Login or demo role selection in the client establishes an authenticated role context; subsequent API calls carry JWT authorization.
2. The app shell loads role-relevant records from Express, then dispatches them to module views.
3. User actions in a module invoke REST mutations; the server enforces permissions, persists through `server/db.js`, and returns updated data for UI state refresh.
4. Notifications/reminders cross-cut workflows and are surfaced globally through `client/src/components/NotificationDrawer.jsx`.
5. Build/deployment separates the static Vite bundle (`client/dist`) from Node runtime hosting; Express can optionally serve that bundle for a single-server deployment.

Main entry points: [`client/src/App.jsx`](https://github.com/dharshancr/college-management-system/blob/main/client/src/App.jsx) (Application shell), [`server/index.js`](https://github.com/dharshancr/college-management-system/blob/main/server/index.js) (Express REST API), [`package.json`](https://github.com/dharshancr/college-management-system/blob/main/package.json) (Root scripts), [`server/db.js`](https://github.com/dharshancr/college-management-system/blob/main/server/db.js) (Database abstraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_entry["SPA entry<br/>React bootstrap<br/>[main.jsx]"]
  node_app["Application shell<br/>state and view orchestration<br/>[App.jsx]"]
  node_navigation["Navigation<br/>shared UI<br/>[Sidebar.jsx]"]
  node_login["Login modal<br/>authentication UI<br/>[LoginModal.jsx]"]
  node_notifications["Notification drawer<br/>global workflow UI"]
  node_student["Student workflows<br/>dashboard, reminders, attendance<br/>[DashboardView.jsx]"]
  node_academics["Academic operations<br/>scheduling and library UI"]
  node_administration["Administrative workflows<br/>admissions and payroll UI<br/>[AdmissionsView.jsx]"]
  node_communications["Campus communications<br/>messaging and announcements UI"]
  node_vite_proxy["Vite dev proxy<br/>development API bridge<br/>[vite.config.js]"]
  node_bundle["Static bundle<br/>Vite production assets"]
end

subgraph group_api["Node API"]
  node_server["Express REST API<br/>request control and workflows<br/>[index.js]"]
end

subgraph group_data["Persistence"]
  node_db[("Database abstraction<br/>persistence adapter<br/>[db.js]")]
  node_records[("College records<br/>JSON database<br/>[college_db.json]")]
  node_seed["Demo data seeder<br/>dataset lifecycle<br/>[seed.js]"]
end

node_scripts["Root scripts<br/>package scripts<br/>[package.json]"]

node_scripts -->|"starts client"| node_entry
node_scripts -->|"starts API"| node_server
node_scripts -->|"runs"| node_seed
node_entry -->|"mounts"| node_app
node_app -->|"renders"| node_navigation
node_app -->|"establishes session"| node_login
node_app -->|"surfaces alerts"| node_notifications
node_app -->|"dispatches state"| node_student
node_app -->|"dispatches state"| node_academics
node_app -->|"dispatches state"| node_administration
node_app -->|"dispatches state"| node_communications
node_app -.->|"development requests"| node_vite_proxy
node_app -->|"JWT-authenticated REST"| node_server
node_vite_proxy -.->|"forwards in development"| node_server
node_server -->|"authorized reads and mutations"| node_db
node_db -->|"persists"| node_records
node_seed -->|"initializes or refreshes"| node_db
node_server -.->|"optionally serves"| node_bundle

click node_scripts "https://github.com/dharshancr/college-management-system/blob/main/package.json"
click node_entry "https://github.com/dharshancr/college-management-system/blob/main/client/src/main.jsx"
click node_app "https://github.com/dharshancr/college-management-system/blob/main/client/src/App.jsx"
click node_navigation "https://github.com/dharshancr/college-management-system/blob/main/client/src/components/Sidebar.jsx"
click node_login "https://github.com/dharshancr/college-management-system/blob/main/client/src/components/LoginModal.jsx"
click node_notifications "https://github.com/dharshancr/college-management-system/blob/main/client/src/components/NotificationDrawer.jsx"
click node_student "https://github.com/dharshancr/college-management-system/blob/main/client/src/pages/DashboardView.jsx"
click node_academics "https://github.com/dharshancr/college-management-system/blob/main/client/src/pages/TimetableScheduleView.jsx"
click node_administration "https://github.com/dharshancr/college-management-system/blob/main/client/src/pages/AdmissionsView.jsx"
click node_communications "https://github.com/dharshancr/college-management-system/blob/main/client/src/pages/CommunicationView.jsx"
click node_vite_proxy "https://github.com/dharshancr/college-management-system/blob/main/client/vite.config.js"
click node_bundle "https://github.com/dharshancr/college-management-system/tree/main/client/dist"
click node_server "https://github.com/dharshancr/college-management-system/blob/main/server/index.js"
click node_db "https://github.com/dharshancr/college-management-system/blob/main/server/db.js"
click node_records "https://github.com/dharshancr/college-management-system/blob/main/server/college_db.json"
click node_seed "https://github.com/dharshancr/college-management-system/blob/main/server/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_entry,node_app,node_navigation,node_login,node_notifications,node_student,node_academics,node_administration,node_communications,node_vite_proxy,node_bundle toneBlue
class node_server toneAmber
class node_db,node_records,node_seed toneMint
class node_scripts toneNeutral
```

## Components

### React client

Vite React SPA and workflow views.

- [SPA entry](https://github.com/dharshancr/college-management-system/blob/main/client/src/main.jsx): React bootstrap · `client/src/main.jsx`
- [Application shell](https://github.com/dharshancr/college-management-system/blob/main/client/src/App.jsx): state and view orchestration · Centralizes session, selected module, API data, and role-sensitive rendering. · `client/src/App.jsx`
- [Navigation](https://github.com/dharshancr/college-management-system/blob/main/client/src/components/Sidebar.jsx): shared UI · `client/src/components/Sidebar.jsx`
- [Login modal](https://github.com/dharshancr/college-management-system/blob/main/client/src/components/LoginModal.jsx): authentication UI · `client/src/components/LoginModal.jsx`
- [Notification drawer](https://github.com/dharshancr/college-management-system/blob/main/client/src/components/NotificationDrawer.jsx): global workflow UI · Surfaces cross-cutting reminders and notifications. · `client/src/components/NotificationDrawer.jsx`
- [Student workflows](https://github.com/dharshancr/college-management-system/blob/main/client/src/pages/DashboardView.jsx): dashboard, reminders, attendance · `client/src/pages/DashboardView.jsx`
- [Academic operations](https://github.com/dharshancr/college-management-system/blob/main/client/src/pages/TimetableScheduleView.jsx): scheduling and library UI · `client/src/pages/TimetableScheduleView.jsx`
- [Administrative workflows](https://github.com/dharshancr/college-management-system/blob/main/client/src/pages/AdmissionsView.jsx): admissions and payroll UI · `client/src/pages/AdmissionsView.jsx`
- [Campus communications](https://github.com/dharshancr/college-management-system/blob/main/client/src/pages/CommunicationView.jsx): messaging and announcements UI · `client/src/pages/CommunicationView.jsx`
- [Vite dev proxy](https://github.com/dharshancr/college-management-system/blob/main/client/vite.config.js): development API bridge · `client/vite.config.js`
- [Static bundle](https://github.com/dharshancr/college-management-system/tree/main/client/dist): Vite production assets · Can be served by Express in a single-server deployment. · `client/dist`

### Node API

REST control, authorization, and durable workflow changes.

- [Express REST API](https://github.com/dharshancr/college-management-system/blob/main/server/index.js): request control and workflows · Validates requests, enforces JWT roles, and executes domain mutations. · `server/index.js`

### Persistence

Demo data lifecycle and durable records.

- [Database abstraction](https://github.com/dharshancr/college-management-system/blob/main/server/db.js): persistence adapter · Only API handlers access durable records through this layer. · `server/db.js`
- [College records](https://github.com/dharshancr/college-management-system/blob/main/server/college_db.json): JSON database · `server/college_db.json`
- [Demo data seeder](https://github.com/dharshancr/college-management-system/blob/main/server/seed.js): dataset lifecycle · `server/seed.js`

### Other components

- [Root scripts](https://github.com/dharshancr/college-management-system/blob/main/package.json): package scripts · Coordinates development and seeding. · `package.json`

## Connections

- Root scripts → SPA entry: starts client
- Root scripts → Express REST API: starts API
- Root scripts → Demo data seeder: runs
- SPA entry → Application shell: mounts
- Application shell → Navigation: renders
- Application shell → Login modal: establishes session
- Application shell → Notification drawer: surfaces alerts
- Application shell → Student workflows: dispatches state
- Application shell → Academic operations: dispatches state
- Application shell → Administrative workflows: dispatches state
- Application shell → Campus communications: dispatches state
- Application shell → Vite dev proxy: development requests
- Application shell → Express REST API: JWT-authenticated REST
- Vite dev proxy → Express REST API: forwards in development
- Express REST API → Database abstraction: authorized reads and mutations
- Database abstraction → College records: persists
- Demo data seeder → Database abstraction: initializes or refreshes
- Express REST API → Static bundle: optionally serves