# anasaloqaidi/master-sheet architecture

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

- Interactive diagram: https://gitdiagram.com/anasaloqaidi/master-sheet
- Repository: https://github.com/anasaloqaidi/master-sheet

## Overview

1. This repository is a two-app monorepo: a NestJS API backend in `Master-Sheet-Api` and a React/Vite frontend in `Mastr-Sheet-Web-Ui`. The architecture is a classic client–server split, with the UI consuming REST endpoints from the backend.

2. The backend is organized as a feature-module NestJS application. Each business area has its own module, controller, and service: `user`, `student`, `subject`, `department`, `stage`, `academic-year`, `college`, `preparing-subject`, and grade-related modules (`mid-grade`, `final-grade`, `reFinal-grade`). This makes each domain boundary explicit in the API layer.

3. Persistence is handled through Drizzle ORM, surfaced via a dedicated `drizzle` module with provider/config/schema files. The backend likely uses PostgreSQL, as indicated by the README and the SQL/Drizzle setup. The schema layer is centralized rather than spread across feature modules.

4. Authentication is a separate backend subsystem under `auth`, using both local and JWT strategies plus guards. That means login is username/password-based first, then sessionless token-based access for protected routes. Role-aware access control is part of the security boundary.

5. The backend also includes an `email` module and a Handlebars template directory, which suggests server-side email delivery for flows such as password recovery or account-related notifications. This is an auxiliary service boundary, not part of the core CRUD paths.

6. The grade-management domain is split into multiple record types rather than one generic grade table. `mid-grade`, `final-grade`, and `reFinal-grade` are distinct subsystems, which implies different lifecycle rules and reporting paths for each exam phase.

7. The frontend is a Vite + React application structured around screens and reusable feature components. Top-level pages include sign-in, forgot/reset password, splash/loading, config, and a dashboard shell with subpages for each business domain.

8. State management on the frontend is Redux Toolkit-based and domain-scoped. There is a slice and async action files per entity area (`student`, `subject`, `stage`, `department`, `academicYear`, `college`, `user`, `preparingSubject`, `grade`, `auth`). This mirrors the backend module structure and makes the data flow easy to trace in a diagram.

9. The UI is organized around CRUD workflows. Most feature folders contain create/update/delete/search/filter/table components, indicating a pattern of list pages backed by form dialogs or panels. The `reports` and `grade` areas are more read-heavy and filtering/report oriented.

10. The dashboard is role-driven. The README describes different experiences for Dean, Head of Department, and Committee Member, and the frontend has protected/private routing plus dashboard subpages for academic operations, settings, reports, and administration. Authorization therefore affects both route access and which modules are visible.

11. Shared UI concerns are separated into reusable components and public constants. Examples include sidebar, header, logo, action toggles, export, and theme CSS modules. This suggests a shell layout around the dashboard with domain pages mounted inside it.

12. Data flow is: user logs in through the frontend auth pages, Redux dispatches auth actions to the NestJS auth endpoints, the backend validates credentials and issues JWTs, and subsequent feature requests go through protected API calls to domain controllers/services, which read/write via Drizzle to the database. Email flows branch out through the backend mail module when needed.

13. Testing and developer tooling exist on both sides but are secondary to runtime architecture. The backend has Nest e2e test scaffolding and Drizzle config; the frontend has Vite, ESLint, PostCSS, and CSS modules. These support development, but the key diagram boundaries are still UI, API, auth, ORM/database, and email delivery.

Main entry points: [`Master-Sheet-Api/src/main.ts`](https://github.com/anasaloqaidi/master-sheet/blob/main/Master-Sheet-Api/src/main.ts) (API server), [`Mastr-Sheet-Web-Ui/src/pages/dashbord/Main.jsx`](https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/pages/dashbord/Main.jsx) (Dashboard), [`Mastr-Sheet-Web-Ui/src/redux/store.js`](https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/redux/store.js) (Redux store), [`Master-Sheet-Api/src/Modules/auth/auth.module.ts`](https://github.com/anasaloqaidi/master-sheet/blob/main/Master-Sheet-Api/src/Modules/auth/auth.module.ts) (Auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Master-Sheet-Api"]
  node_api_server["API server<br/>NestJS entry<br/>[main.ts]"]
  node_auth_backend["Auth<br/>security module<br/>[auth.module.ts]"]
  node_domain_backend["Core domains<br/>feature modules<br/>[student.module.ts]"]
  node_grade_backend["Grades<br/>grading modules"]
  node_drizzle_backend[("Drizzle ORM<br/>persistence layer<br/>[drizzle.module.ts]")]
  node_email_backend["Email<br/>notification service<br/>[email.module.ts]"]
  node_template_backend["Mail template<br/>hbs template<br/>[index.hbs]"]
end

subgraph group_frontend["Mastr-Sheet-Web-Ui"]
  node_ui_shell["App shell<br/>React app<br/>[App.jsx]"]
  node_auth_pages["Auth pages<br/>public screens<br/>[SignIn.jsx]"]
  node_private_route["Private route<br/>route guard<br/>[Private.jsx]"]
  node_dashboard_shell["Dashboard<br/>layout pages<br/>[Main.jsx]"]
  node_dashboard_slices["Redux store<br/>state management<br/>[store.js]"]
  node_shared_ui["Shared UI<br/>components<br/>[SideBar.jsx]"]
  node_crud_components["CRUD widgets<br/>feature components<br/>[Table.jsx]"]
  node_grade_reports_ui["Grades & reports<br/>read views<br/>[Table.jsx]"]
end

node_ui_shell -->|"routes"| node_auth_pages
node_ui_shell -->|"protects"| node_private_route
node_private_route -->|"enters"| node_dashboard_shell
node_dashboard_shell -->|"uses"| node_shared_ui
node_dashboard_shell -->|"mounts"| node_crud_components
node_dashboard_shell -->|"mounts"| node_grade_reports_ui
node_auth_pages -->|"dispatches"| node_dashboard_slices
node_crud_components -->|"dispatches"| node_dashboard_slices
node_grade_reports_ui -->|"dispatches"| node_dashboard_slices
node_dashboard_slices -->|"REST calls"| node_api_server
node_api_server -->|"loads"| node_auth_backend
node_api_server -->|"loads"| node_domain_backend
node_api_server -->|"loads"| node_grade_backend
node_domain_backend -->|"persists via"| node_drizzle_backend
node_grade_backend -->|"persists via"| node_drizzle_backend
node_auth_backend -->|"verifies via"| node_drizzle_backend
node_email_backend -->|"renders"| node_template_backend
node_auth_backend -->|"triggers"| node_email_backend
node_api_server -->|"loads"| node_email_backend

click node_api_server "https://github.com/anasaloqaidi/master-sheet/blob/main/Master-Sheet-Api/src/main.ts"
click node_auth_backend "https://github.com/anasaloqaidi/master-sheet/blob/main/Master-Sheet-Api/src/Modules/auth/auth.module.ts"
click node_domain_backend "https://github.com/anasaloqaidi/master-sheet/blob/main/Master-Sheet-Api/src/Modules/student/student.module.ts"
click node_grade_backend "https://github.com/anasaloqaidi/master-sheet/blob/main/Master-Sheet-Api/src/Modules/mid-grade/mid-grade.module.ts"
click node_drizzle_backend "https://github.com/anasaloqaidi/master-sheet/blob/main/Master-Sheet-Api/src/Modules/drizzle/drizzle.module.ts"
click node_email_backend "https://github.com/anasaloqaidi/master-sheet/blob/main/Master-Sheet-Api/src/Modules/email/email.module.ts"
click node_template_backend "https://github.com/anasaloqaidi/master-sheet/blob/main/Master-Sheet-Api/template/index.hbs"
click node_ui_shell "https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/App.jsx"
click node_auth_pages "https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/pages/SignIn.jsx"
click node_private_route "https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/pages/Private.jsx"
click node_dashboard_shell "https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/pages/dashbord/Main.jsx"
click node_dashboard_slices "https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/redux/store.js"
click node_shared_ui "https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/components/sidebar/SideBar.jsx"
click node_crud_components "https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/components/student/Table.jsx"
click node_grade_reports_ui "https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/components/grade/Table.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_api_server,node_auth_backend,node_domain_backend,node_grade_backend,node_drizzle_backend,node_email_backend,node_template_backend toneBlue
class node_ui_shell,node_auth_pages,node_private_route,node_dashboard_shell,node_dashboard_slices,node_shared_ui,node_crud_components,node_grade_reports_ui toneAmber
```

## Components

### Master-Sheet-Api

NestJS API backend with feature modules, auth, email, and Drizzle persistence

- [API server](https://github.com/anasaloqaidi/master-sheet/blob/main/Master-Sheet-Api/src/main.ts): NestJS entry · Bootstraps the backend application and composes all server-side modules · `Master-Sheet-Api/src/main.ts`
- [Auth](https://github.com/anasaloqaidi/master-sheet/blob/main/Master-Sheet-Api/src/Modules/auth/auth.module.ts): security module · Local login, JWT issuance, and route guards for protected access · `Master-Sheet-Api/src/Modules/auth/auth.module.ts`
- [Core domains](https://github.com/anasaloqaidi/master-sheet/blob/main/Master-Sheet-Api/src/Modules/student/student.module.ts): feature modules · CRUD-oriented business modules for user, student, subject, department, stage, academic-year, college, and preparing-subject · `Master-Sheet-Api/src/Modules/student/student.module.ts`
- [Grades](https://github.com/anasaloqaidi/master-sheet/blob/main/Master-Sheet-Api/src/Modules/mid-grade/mid-grade.module.ts): grading modules · Separate mid-grade, final-grade, and reFinal-grade workflows and endpoints · `Master-Sheet-Api/src/Modules/mid-grade/mid-grade.module.ts`
- [Drizzle ORM](https://github.com/anasaloqaidi/master-sheet/blob/main/Master-Sheet-Api/src/Modules/drizzle/drizzle.module.ts): persistence layer · Database connection, schema, and provider layer for relational storage · `Master-Sheet-Api/src/Modules/drizzle/drizzle.module.ts`
- [Email](https://github.com/anasaloqaidi/master-sheet/blob/main/Master-Sheet-Api/src/Modules/email/email.module.ts): notification service · Server-side mail delivery for account and recovery flows · `Master-Sheet-Api/src/Modules/email/email.module.ts`
- [Mail template](https://github.com/anasaloqaidi/master-sheet/blob/main/Master-Sheet-Api/template/index.hbs): hbs template · Handlebars template used by the email subsystem · `Master-Sheet-Api/template/index.hbs`

### Mastr-Sheet-Web-Ui

React/Vite client with routed screens, dashboard, and Redux state

- [App shell](https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/App.jsx): React app · Top-level Vite/React application and route composition · `Mastr-Sheet-Web-Ui/src/App.jsx`
- [Auth pages](https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/pages/SignIn.jsx): public screens · Sign-in, forgot password, and reset password entry points · `Mastr-Sheet-Web-Ui/src/pages/SignIn.jsx`
- [Private route](https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/pages/Private.jsx): route guard · Protected route boundary before dashboard access · `Mastr-Sheet-Web-Ui/src/pages/Private.jsx`
- [Dashboard](https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/pages/dashbord/Main.jsx): layout pages · Role-aware dashboard shell and subpage router for operational areas · `Mastr-Sheet-Web-Ui/src/pages/dashbord/Main.jsx`
- [Redux store](https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/redux/store.js): state management · Central Redux store and domain slices for auth and entity workflows · `Mastr-Sheet-Web-Ui/src/redux/store.js`
- [Shared UI](https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/components/sidebar/SideBar.jsx): components · Sidebar, header, logo, action toggles, export, and theming primitives · `Mastr-Sheet-Web-Ui/src/components/sidebar/SideBar.jsx`
- [CRUD widgets](https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/components/student/Table.jsx): feature components · Entity-specific create, update, delete, table, search, and filter controls · `Mastr-Sheet-Web-Ui/src/components/student/Table.jsx`
- [Grades & reports](https://github.com/anasaloqaidi/master-sheet/blob/main/Mastr-Sheet-Web-Ui/src/components/grade/Table.jsx): read views · Filtering, reporting, and grade-focused views inside the dashboard · `Mastr-Sheet-Web-Ui/src/components/grade/Table.jsx`

## Connections

- App shell → Auth pages: routes · Public authentication screens are mounted from the application router
- App shell → Private route: protects · Authenticated dashboard access is gated by a private route boundary
- Private route → Dashboard: enters · Successful auth transitions into the dashboard layout
- Dashboard → Shared UI: uses · Dashboard pages are framed by sidebar, header, and shared controls
- Dashboard → CRUD widgets: mounts · Entity management screens use CRUD-oriented components
- Dashboard → Grades & reports: mounts · Grade and report areas use specialized read/filter views
- Auth pages → Redux store: dispatches · Sign-in and password flows are handled through Redux auth actions
- CRUD widgets → Redux store: dispatches · Feature pages read and write through entity slices and async actions
- Grades & reports → Redux store: dispatches · Grade/report views load and filter data through Redux
- Redux store → API server: REST calls · Frontend async actions communicate with the NestJS backend endpoints
- API server → Auth: loads · Backend composition includes the authentication subsystem
- API server → Core domains: loads · Backend composition includes feature modules for core business areas
- API server → Grades: loads · Backend composition includes the grade-management modules
- Core domains → Drizzle ORM: persists via · Domain services read and write through the shared Drizzle layer
- Grades → Drizzle ORM: persists via · Grade workflows store and query records through Drizzle
- Auth → Drizzle ORM: verifies via · Authentication depends on stored user data and shared persistence
- Email → Mail template: renders · Email delivery uses the Handlebars template for message content
- Auth → Email: triggers · Password-recovery and account flows can branch into email delivery
- API server → Email: loads · The backend includes email as an auxiliary service module
