# mkkapadi12/school-management-system architecture

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

- Interactive diagram: https://gitdiagram.com/mkkapadi12/school-management-system
- Repository: https://github.com/mkkapadi12/school-management-system

## Overview

1. **Repository shape**
   - This is a monorepo for a multi-tenant school management system with three real runtime boundaries: `client/` (React/Vite frontend), `server/` (Node.js/Express API), and `server/database/` (MySQL schema + stored procedures). The top-level `memory/` and planning docs are governance artifacts, not runtime components.

2. **Frontend shell**
   - The client is a Vite React app built around feature-based routing. `main.jsx` bootstraps providers, `App.jsx` and `client/src/components/routes/*` handle route protection, and `client/src/components/layouts/*` define role-specific shells for public, super admin, school admin, staff, and student views.
   - Routing is role-aware: public/guest pages, authenticated pages, and role-gated pages are separated by `GuestRoute`, `ProtectedRoute`, and `RoleRoute`.

3. **Frontend feature boundaries**
   - The UI is organized by business capability, not by generic page type. Major slices are `auth`, `guest`, `profile`, `school_admin`, `super_admin`, `staff`, and `student`.
   - Each slice typically contains its own pages, feature components, constants, utilities, and API client files. This makes dashboards, tables, dialogs, and forms local to the domain that owns them.

4. **Shared frontend infrastructure**
   - Shared UI lives in `client/src/components/shared` and `client/src/components/ui`, with the latter providing reusable design-system primitives from shadcn/ui-style components.
   - Cross-cutting client services include `client/src/app/store.js` and `baseApi.js` for RTK Query, `lib/axios.js` for HTTP transport, `providers/ThemeProvider.jsx` for dark/light mode, and hooks like `useAuth` / `useLogout` for auth state management.

5. **Frontend data flow**
   - UI actions generally go: page/component → feature API module → shared RTK Query base API / axios client → backend REST endpoint.
   - Cache coherence is handled through RTK Query tag invalidation, so tables, dashboards, and dialogs stay in sync after mutations without manual refresh logic.

6. **Backend application shape**
   - The server is an Express app with `server/index.js` and `src/app.js` wiring middleware, routes, and global error handling.
   - Requests move through a consistent pipeline: route → auth middleware → role authorization → validation/sanitization/rate limiting/upload handling → controller → model → MySQL stored procedure.

7. **Backend domain modules**
   - Backend code is split by domain: `auth`, `school`, `schoolAdmin`, `staff`, `student`, `class`, `department`, `branch`, `medium`, `subject`, `schedule`, and their school-specific variants.
   - Controllers hold request/response logic, models encapsulate database calls, and route files map HTTP resources. The pattern is intentionally uniform so each module can be diagrammed as a self-contained vertical slice.

8. **Auth, identity, and tenant boundaries**
   - Authentication is JWT-based with httpOnly cookies, enforced by `auth.js`; role checks are separated into `authorize.js`.
   - Multi-tenancy is a core boundary: school context is derived from the authenticated principal, not from arbitrary request body fields. That prevents cross-school data access.
   - The system uses a unified staff/user identity model for platform, school admin, and staff roles, while `student` is present as a reserved role and separate future-facing path.

9. **Database architecture**
   - The database is MySQL with a strong “stored procedures only” rule: application code does not embed inline SQL.
   - `server/database/` is split into a monolithic base schema/procedure set plus per-feature subfolders (`staff`, `branch`, `department`, `medium`, `subject`) for additional tables and procedures. There are also dedicated procedure files for students and seeded role data.
   - The application’s `callProcedure` utility is the single bridge from models to the database layer.

10. **External services and integrations**
   - Email flows use a mailer config plus HTML templates for welcome and reset-password emails.
   - File/image upload flows go through Cloudinary, with dedicated upload middleware and utility helpers.
   - Swagger docs are generated/maintained per domain under `src/docs`, which matters for how API boundaries are documented and consumed.

11. **Operational and delivery boundaries**
   - The repo includes GitHub Actions for separate client and server CI paths, plus Vercel deployment config files in both apps.
   - This suggests the frontend and backend can be built/deployed independently, even though they share the same repo and coordinated environment variables.

12. **What to emphasize in an architecture diagram**
   - Show three main layers: React client, Express API, and MySQL procedure-driven data store.
   - Overlay two major cross-cutting concerns: role-based authorization and tenant scoping.
   - Then branch the client and server into their feature domains, because most functionality is organized by business module rather than by technical layer.

Main entry points: [`client/src/components/routes`](https://github.com/mkkapadi12/school-management-system/tree/master/client/src/components/routes) (Route guards), [`client/src/app`](https://github.com/mkkapadi12/school-management-system/tree/master/client/src/app) (Client state), [`client/src/App.jsx`](https://github.com/mkkapadi12/school-management-system/blob/master/client/src/App.jsx) (App shell), [`server/src/app.js`](https://github.com/mkkapadi12/school-management-system/blob/master/server/src/app.js) (Express app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_client_bootstrap["App bootstrap<br/>react entry<br/>[main.jsx]"]
  node_client_shell["App shell<br/>routing shell<br/>[App.jsx]"]
  node_client_routes["Route guards<br/>navigation control"]
  node_client_layouts["Role layouts<br/>ui shell"]
  node_client_auth["Auth UI<br/>feature slice"]
  node_client_profile["Profile UI<br/>feature slice"]
  node_client_guest["Guest pages<br/>feature slice"]
  node_client_super_admin["Super admin<br/>feature slice"]
  node_client_school_admin["School admin<br/>feature slice"]
  node_client_staff["Staff UI<br/>feature slice"]
  node_client_student["Student UI<br/>feature slice"]
  node_client_shared["Shared UI<br/>ui library"]
  node_client_state["Client state<br/>data layer"]
end

subgraph group_server["Server"]
  node_server_entry["Server entry<br/>express bootstrap<br/>[index.js]"]
  node_server_app["Express app<br/>middleware core<br/>[app.js]"]
  node_server_routes["API routes<br/>http routing"]
  node_server_middleware["API middleware<br/>request pipeline"]
  node_server_controllers["Controllers<br/>request handlers"]
  node_server_models["Models<br/>db access"]
  node_server_integrations["Integrations<br/>services"]
end

subgraph group_db["Database"]
  node_db_core[("MySQL procedures<br/>persistent store")]
  node_db_domains[("Domain schemas<br/>db modules")]
end

node_client_bootstrap -->|"mounts"| node_client_shell
node_client_shell -->|"uses"| node_client_routes
node_client_shell -->|"renders"| node_client_layouts
node_client_shell -->|"configures"| node_client_state
node_client_routes -->|"gates"| node_client_auth
node_client_routes -->|"allows"| node_client_guest
node_client_routes -->|"protects"| node_client_super_admin
node_client_routes -->|"protects"| node_client_school_admin
node_client_routes -->|"protects"| node_client_staff
node_client_routes -->|"protects"| node_client_student
node_client_profile -->|"queries"| node_client_state
node_client_super_admin -->|"calls"| node_client_state
node_client_school_admin -->|"calls"| node_client_state
node_client_staff -->|"calls"| node_client_state
node_client_state -->|"requests"| node_server_routes
node_server_entry -->|"starts"| node_server_app
node_server_app -->|"applies"| node_server_middleware
node_server_app -->|"mounts"| node_server_routes
node_server_routes -->|"dispatches"| node_server_controllers
node_server_controllers -->|"uses"| node_server_models
node_server_models -->|"executes"| node_db_core
node_db_core -.->|"extends"| node_db_domains
node_server_app -->|"depends on"| node_server_integrations
node_server_middleware -->|"uses"| node_server_integrations

click node_client_bootstrap "https://github.com/mkkapadi12/school-management-system/blob/master/client/src/main.jsx"
click node_client_shell "https://github.com/mkkapadi12/school-management-system/blob/master/client/src/App.jsx"
click node_client_routes "https://github.com/mkkapadi12/school-management-system/tree/master/client/src/components/routes"
click node_client_layouts "https://github.com/mkkapadi12/school-management-system/tree/master/client/src/components/layouts"
click node_client_auth "https://github.com/mkkapadi12/school-management-system/tree/master/client/src/features/auth"
click node_client_profile "https://github.com/mkkapadi12/school-management-system/tree/master/client/src/features/profile"
click node_client_guest "https://github.com/mkkapadi12/school-management-system/tree/master/client/src/features/guest"
click node_client_super_admin "https://github.com/mkkapadi12/school-management-system/tree/master/client/src/features/super_admin"
click node_client_school_admin "https://github.com/mkkapadi12/school-management-system/tree/master/client/src/features/school_admin"
click node_client_staff "https://github.com/mkkapadi12/school-management-system/tree/master/client/src/features/staff"
click node_client_student "https://github.com/mkkapadi12/school-management-system/tree/master/client/src/features/student"
click node_client_shared "https://github.com/mkkapadi12/school-management-system/tree/master/client/src/components/shared"
click node_client_state "https://github.com/mkkapadi12/school-management-system/tree/master/client/src/app"
click node_server_entry "https://github.com/mkkapadi12/school-management-system/blob/master/server/index.js"
click node_server_app "https://github.com/mkkapadi12/school-management-system/blob/master/server/src/app.js"
click node_server_routes "https://github.com/mkkapadi12/school-management-system/tree/master/server/src/routes"
click node_server_middleware "https://github.com/mkkapadi12/school-management-system/tree/master/server/src/middleware"
click node_server_controllers "https://github.com/mkkapadi12/school-management-system/tree/master/server/src/controllers"
click node_server_models "https://github.com/mkkapadi12/school-management-system/tree/master/server/src/models"
click node_server_integrations "https://github.com/mkkapadi12/school-management-system/tree/master/server/src/config"
click node_db_core "https://github.com/mkkapadi12/school-management-system/tree/master/server/database"
click node_db_domains "https://github.com/mkkapadi12/school-management-system/tree/master/server/database/staff"

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_client_bootstrap,node_client_shell,node_client_routes,node_client_layouts,node_client_auth,node_client_profile,node_client_guest,node_client_super_admin,node_client_school_admin,node_client_staff,node_client_student,node_client_shared,node_client_state toneBlue
class node_server_entry,node_server_app,node_server_routes,node_server_middleware,node_server_controllers,node_server_models,node_server_integrations toneAmber
class node_db_core,node_db_domains toneMint
```

## Components

### Client

React/Vite frontend and feature slices

- [App bootstrap](https://github.com/mkkapadi12/school-management-system/blob/master/client/src/main.jsx): react entry · Bootstraps providers and mounts the app shell · `client/src/main.jsx`
- [App shell](https://github.com/mkkapadi12/school-management-system/blob/master/client/src/App.jsx): routing shell · Top-level app composition and route wiring · `client/src/App.jsx`
- [Route guards](https://github.com/mkkapadi12/school-management-system/tree/master/client/src/components/routes): navigation control · Guest, protected, and role-gated route boundaries · `client/src/components/routes`
- [Role layouts](https://github.com/mkkapadi12/school-management-system/tree/master/client/src/components/layouts): ui shell · Public and role-specific navigation shells · `client/src/components/layouts`
- [Auth UI](https://github.com/mkkapadi12/school-management-system/tree/master/client/src/features/auth): feature slice · Login, password reset, and auth state · `client/src/features/auth`
- [Profile UI](https://github.com/mkkapadi12/school-management-system/tree/master/client/src/features/profile): feature slice · Profile view and account settings dialogs · `client/src/features/profile`
- [Guest pages](https://github.com/mkkapadi12/school-management-system/tree/master/client/src/features/guest): feature slice · Public marketing and informational pages · `client/src/features/guest`
- [Super admin](https://github.com/mkkapadi12/school-management-system/tree/master/client/src/features/super_admin): feature slice · Platform administration dashboards and management screens · `client/src/features/super_admin`
- [School admin](https://github.com/mkkapadi12/school-management-system/tree/master/client/src/features/school_admin): feature slice · School-scoped dashboards, tables, and forms · `client/src/features/school_admin`
- [Staff UI](https://github.com/mkkapadi12/school-management-system/tree/master/client/src/features/staff): feature slice · Staff dashboard, schedule, and leave actions · `client/src/features/staff`
- [Student UI](https://github.com/mkkapadi12/school-management-system/tree/master/client/src/features/student): feature slice · Student dashboard entry point · `client/src/features/student`
- [Shared UI](https://github.com/mkkapadi12/school-management-system/tree/master/client/src/components/shared): ui library · Reusable app components and design-system primitives · `client/src/components/shared`
- [Client state](https://github.com/mkkapadi12/school-management-system/tree/master/client/src/app): data layer · RTK Query store and API base configuration · `client/src/app`

### Server

Express API and domain modules

- [Server entry](https://github.com/mkkapadi12/school-management-system/blob/master/server/index.js): express bootstrap · Starts the API and wires the application · `server/index.js`
- [Express app](https://github.com/mkkapadi12/school-management-system/blob/master/server/src/app.js): middleware core · Middleware chain, routing, and error handling · `server/src/app.js`
- [API routes](https://github.com/mkkapadi12/school-management-system/tree/master/server/src/routes): http routing · Resource routing for auth, school, staff, student, and admin domains · `server/src/routes`
- [API middleware](https://github.com/mkkapadi12/school-management-system/tree/master/server/src/middleware): request pipeline · Auth, role checks, validation, rate limiting, upload, and sanitization · `server/src/middleware`
- [Controllers](https://github.com/mkkapadi12/school-management-system/tree/master/server/src/controllers): request handlers · HTTP request and response logic by domain · `server/src/controllers`
- [Models](https://github.com/mkkapadi12/school-management-system/tree/master/server/src/models): db access · Domain data access via stored procedures · `server/src/models`
- [Integrations](https://github.com/mkkapadi12/school-management-system/tree/master/server/src/config): services · Mailer, Cloudinary, JWT, and Google client configuration · `server/src/config`

### Database

MySQL schema and stored procedures

- [MySQL procedures](https://github.com/mkkapadi12/school-management-system/tree/master/server/database): persistent store · Base schema and procedure-driven persistence layer · `server/database`
- [Domain schemas](https://github.com/mkkapadi12/school-management-system/tree/master/server/database/staff): db modules · Feature-specific schema and procedure folders for school data · `server/database/staff`

## Connections

- App bootstrap → App shell: mounts · Bootstraps the app shell and provider tree
- App shell → Route guards: uses · Top-level app composition delegates access control to route guards
- App shell → Role layouts: renders · Selects the appropriate public or role shell
- App shell → Client state: configures · Wires shared app state and API services
- Route guards → Auth UI: gates · Protects authenticated and role-specific auth flows
- Route guards → Guest pages: allows · Exposes public pages through guest routing
- Route guards → Super admin: protects · Restricts platform admin views by role
- Route guards → School admin: protects · Restricts school admin views by role and tenant
- Route guards → Staff UI: protects · Restricts staff views by role
- Route guards → Student UI: protects · Restricts student views by role
- Profile UI → Client state: queries · Uses shared API state for profile reads and updates
- Super admin → Client state: calls · Uses feature APIs through the shared client layer
- School admin → Client state: calls · Uses feature APIs through the shared client layer
- Staff UI → Client state: calls · Uses feature APIs through the shared client layer
- Client state → API routes: requests · Client features reach the backend through REST endpoints
- Server entry → Express app: starts · Entry point initializes the Express application
- Express app → API middleware: applies · Runs requests through auth, validation, and safety middleware
- Express app → API routes: mounts · Registers domain route modules
- API routes → Controllers: dispatches · Routes hand off to domain controllers
- Controllers → Models: uses · Controllers delegate persistence to models
- Models → MySQL procedures: executes · Models bridge to the database through stored procedures
- MySQL procedures → Domain schemas: extends · Core schema is augmented by feature-specific database modules
- Express app → Integrations: depends on · Cross-cutting services support auth, email, uploads, and docs
- API middleware → Integrations: uses · Middleware relies on JWT, uploads, and other shared services