How mkkapadi12/school-management-system works
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: routes Route guards · app Client state · App.jsx App shell · app.js Express app
Components 22
Client
React/Vite frontend and feature slices
- App bootstrap · Bootstraps providers and mounts the app shell
client/src/main.jsx - App shell · Top-level app composition and route wiring
client/src/App.jsx - Route guards · Guest, protected, and role-gated route boundaries
client/src/components/routes - Role layouts · Public and role-specific navigation shells
client/src/components/layouts - Auth UI · Login, password reset, and auth state
client/src/features/auth - Profile UI · Profile view and account settings dialogs
client/src/features/profile - Guest pages · Public marketing and informational pages
client/src/features/guest - Super admin · Platform administration dashboards and management screens
client/src/features/super_admin - School admin · School-scoped dashboards, tables, and forms
client/src/features/school_admin - Staff UI · Staff dashboard, schedule, and leave actions
client/src/features/staff - Student UI · Student dashboard entry point
client/src/features/student - Shared UI · Reusable app components and design-system primitives
client/src/components/shared - Client state · RTK Query store and API base configuration
client/src/app
Server
Express API and domain modules
- Server entry · Starts the API and wires the application
server/index.js - Express app · Middleware chain, routing, and error handling
server/src/app.js - API routes · Resource routing for auth, school, staff, student, and admin domains
server/src/routes - API middleware · Auth, role checks, validation, rate limiting, upload, and sanitization
server/src/middleware - Controllers · HTTP request and response logic by domain
server/src/controllers - Models · Domain data access via stored procedures
server/src/models - Integrations · Mailer, Cloudinary, JWT, and Google client configuration
server/src/config
Database
MySQL schema and stored procedures
- MySQL procedures · Base schema and procedure-driven persistence layer
server/database - Domain schemas · Feature-specific schema and procedure folders for school data
server/database/staff
Connections 24
- 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