# leohztest-blip/school-management-saas architecture

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

- Interactive diagram: https://gitdiagram.com/leohztest-blip/school-management-saas
- Repository: https://github.com/leohztest-blip/school-management-saas

## Overview

1. **What this repo is**
   - Shiksha ERP is a multi-tenant school management SaaS built on **Next.js 15 App Router** with **TypeScript** and **Tailwind CSS**.
   - The main product is a web app, but the repo also contains an **edge-functions** bundle with a separate worker, so the architecture is not just a single frontend.

2. **Primary runtime boundaries**
   - `src/` is the main Next.js application.
   - `edge-functions/` appears to be a parallel deployment target for edge/runtime code, including `job-worker/index.ts`.
   - `supabase/` contains the backend schema, migrations, seed data, and storage definitions, making Supabase the persistence and auth boundary.

3. **Route-level structure**
   - The app is organized by route groups: `/(auth)` for login/register, `/admin` for platform/admin views, `/dashboard` for school operational modules, and `/portal/parent` for parent-facing access.
   - There is a dynamic student detail route at `/dashboard/students/[id]`, which implies record-centric navigation inside the dashboard.

4. **Shell/layout architecture**
   - The app uses nested layouts: root layout, auth layout, admin layout, and dashboard layout.
   - Shared navigation primitives live in `components/layout/` such as the dashboard layout, navbar, and sidebars; these are the main chrome boundaries for authenticated areas.

5. **Domain modules in the dashboard**
   - The dashboard is split into functional business areas: students, staff, attendance, fees, payroll, exams, classes, inventory, library, hostel, transport, timetable, leave, expenses, payments, reports, notifications, settings, and analytics.
   - This suggests a modular ERP UI where each route maps to one operational subsystem rather than a generic page framework.

6. **Admin vs school-operator separation**
   - `/admin` contains higher-level management views like analytics and schools, separate from the school-operational dashboard.
   - This is an important tenant/platform boundary for diagrams: admin concerns likely span multiple schools, while dashboard screens are day-to-day school operations.

7. **Business logic layer**
   - `src/services/` is the main domain service layer, split into analytics, attendance, billing, communication, dashboard, fees, HR, reporting, and students.
   - Pages and components should be understood as consumers of these services rather than containing most of the logic themselves.

8. **Data access and backend integration**
   - `src/lib/supabase/client.ts` and `src/lib/supabase/server.ts` provide the two Supabase access paths, indicating both browser-side and server-side data/auth usage.
   - Supabase supplies **PostgreSQL, Auth, Storage, and RLS**, so authorization and tenant isolation are enforced partly at the database layer.

9. **Auth, permissions, and route protection**
   - `src/middleware.ts` plus `config/permissions.ts` and `hooks/use-permissions.tsx` form the access-control layer.
   - `auth.store.ts` and `ui.store.ts` use Zustand for client state, likely handling session/UI state across the authenticated experience.

10. **Reusable UI and reporting primitives**
   - Shared components such as `data-table`, `stats-card`, `page-header`, `fee-receipt`, and `payslip` indicate reusable output/reporting surfaces across modules.
   - `TanStack Table`, `Recharts`, and form libraries (`React Hook Form` + `Zod`) are used to support tabular admin workflows, dashboards, and validated forms.

11. **Background/edge processing**
   - `edge-functions/job-worker/index.ts` suggests asynchronous or offloaded processing outside the main Next.js request path.
   - Combined with `communication` and `reporting` services, this likely supports background tasks such as notifications, document generation, or scheduled processing.

12. **Data model and deployment artifacts**
   - `supabase/schema.sql`, `schema_phase2.sql`, `migrations/004_branches.sql`, `seed.sql`, and `storage.sql` show the backend is schema-driven and versioned in-repo.
   - The presence of `branches` and phase-specific schema files implies multi-tenant growth and staged rollout of features.

13. **How to draw the architecture**
   - A good diagram should show: browser users -> Next.js routes/layouts -> middleware/permissions -> page components -> domain services -> Supabase/Postgres/Auth/Storage.
   - Add a second path for edge/background execution through `edge-functions/job-worker`, and keep admin, school dashboard, and parent portal as distinct user-facing entry points.

Main entry points: [`src/lib/supabase/server.ts`](https://github.com/leohztest-blip/school-management-saas/blob/main/src/lib/supabase/server.ts) (Supabase server), [`src/app/dashboard/page.tsx`](https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/dashboard/page.tsx) (Dashboard home), [`src/app/layout.tsx`](https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/layout.tsx) (Root layout), [`src/app/dashboard/layout.tsx`](https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/dashboard/layout.tsx) (Dashboard layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web App"]
  node_src_app_layout["Root layout<br/>next app shell<br/>[layout.tsx]"]
  node_src_middleware{{"Middleware<br/>route guard<br/>[middleware.ts]"}}
  node_src_permissions["Permissions<br/>access control<br/>[permissions.ts]"]
  node_src_auth_layout["Auth layout<br/>route layout<br/>[layout.tsx]"]
  node_src_auth_login["Login<br/>auth page<br/>[page.tsx]"]
  node_src_admin_layout["Admin layout<br/>route layout<br/>[layout.tsx]"]
  node_src_admin_home["Admin home<br/>admin page<br/>[page.tsx]"]
  node_src_dashboard_layout["Dashboard layout<br/>route layout<br/>[layout.tsx]"]
  node_src_dashboard_home["Dashboard home<br/>dashboard page<br/>[page.tsx]"]
  node_src_students_detail["Student detail<br/>record page<br/>[page.tsx]"]
  node_src_parent_portal["Parent portal<br/>portal page<br/>[page.tsx]"]
  node_src_dashboard_shell["Chrome<br/>layout component"]
  node_src_data_table["Data table<br/>shared ui<br/>[data-table.tsx]"]
end

subgraph group_services["Domain Services"]
  node_svc_dashboard["Dashboard svc<br/>orchestration"]
  node_svc_students["Students svc<br/>domain service"]
  node_svc_analytics["Analytics svc<br/>domain service"]
  node_svc_billing["Billing svc<br/>domain service<br/>[billing.service.ts]"]
  node_svc_hr["HR svc<br/>domain service<br/>[hr.service.ts]"]
  node_svc_reporting["Reporting svc<br/>domain service"]
  node_svc_comm["Comms svc<br/>domain service"]
end

subgraph group_data["Supabase Backend"]
  node_supa_client["Supabase client<br/>browser data access<br/>[client.ts]"]
  node_supa_server["Supabase server<br/>server data access<br/>[server.ts]"]
  node_supabase_schema[("Schema<br/>[schema.sql]")]
  node_supabase_phase2[("Phase 2 schema<br/>postgres schema<br/>[schema_phase2.sql]")]
  node_supabase_branch["Branches<br/>migration<br/>[004_branches.sql]"]
  node_supabase_storage[("Storage<br/>[storage.sql]")]
end

subgraph group_edge["Edge Runtime"]
  node_edge_worker{{"Job worker<br/>edge worker<br/>[index.ts]"}}
end

node_src_app_layout -->|"wraps auth"| node_src_auth_layout
node_src_app_layout -->|"wraps admin"| node_src_admin_layout
node_src_app_layout -->|"wraps dashboard"| node_src_dashboard_layout
node_src_app_layout -->|"exposes portal"| node_src_parent_portal
node_src_middleware -->|"uses"| node_src_permissions
node_src_middleware -.->|"protects"| node_src_auth_layout
node_src_auth_layout -->|"hosts"| node_src_auth_login
node_src_admin_layout -->|"hosts"| node_src_admin_home
node_src_dashboard_layout -->|"hosts"| node_src_dashboard_home
node_src_dashboard_layout -->|"hosts"| node_src_students_detail
node_src_dashboard_layout -->|"uses"| node_src_dashboard_shell
node_src_dashboard_home -->|"calls"| node_svc_dashboard
node_src_students_detail -->|"calls"| node_svc_students
node_src_dashboard_home -->|"calls"| node_svc_analytics
node_src_dashboard_home -->|"calls"| node_svc_billing
node_src_dashboard_home -->|"calls"| node_svc_hr
node_src_dashboard_home -->|"calls"| node_svc_reporting
node_src_dashboard_home -->|"calls"| node_svc_comm
node_svc_dashboard -->|"reads/writes"| node_supa_server
node_svc_students -->|"reads/writes"| node_supa_server
node_svc_analytics -->|"queries"| node_supa_server
node_svc_billing -->|"queries"| node_supa_server
node_svc_hr -->|"queries"| node_supa_server
node_svc_reporting -->|"generates"| node_supa_server
node_svc_comm -->|"notifies"| node_supa_server
node_src_dashboard_shell -->|"composes"| node_src_data_table
node_supa_server -->|"targets"| node_supabase_schema
node_supa_server -.->|"extends"| node_supabase_phase2
node_supa_server -->|"tracks"| node_supabase_branch
node_supa_server -->|"uses"| node_supabase_storage
node_supa_client -->|"targets"| node_supabase_schema
node_edge_worker -.->|"processes"| node_supa_server
node_edge_worker -.->|"supports"| node_svc_comm
node_edge_worker -.->|"supports"| node_svc_reporting

click node_src_app_layout "https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/layout.tsx"
click node_src_middleware "https://github.com/leohztest-blip/school-management-saas/blob/main/src/middleware.ts"
click node_src_permissions "https://github.com/leohztest-blip/school-management-saas/blob/main/src/config/permissions.ts"
click node_src_auth_layout "https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/(auth)/layout.tsx"
click node_src_auth_login "https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/(auth)/login/page.tsx"
click node_src_admin_layout "https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/admin/layout.tsx"
click node_src_admin_home "https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/admin/page.tsx"
click node_src_dashboard_layout "https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/dashboard/layout.tsx"
click node_src_dashboard_home "https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/dashboard/page.tsx"
click node_src_students_detail "https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/dashboard/students/[id]/page.tsx"
click node_src_parent_portal "https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/portal/parent/page.tsx"
click node_src_dashboard_shell "https://github.com/leohztest-blip/school-management-saas/blob/main/src/components/layout/dashboard-layout.tsx"
click node_src_data_table "https://github.com/leohztest-blip/school-management-saas/blob/main/src/components/shared/data-table.tsx"
click node_svc_dashboard "https://github.com/leohztest-blip/school-management-saas/blob/main/src/services/dashboard.service.ts"
click node_svc_students "https://github.com/leohztest-blip/school-management-saas/blob/main/src/services/students.service.ts"
click node_svc_analytics "https://github.com/leohztest-blip/school-management-saas/blob/main/src/services/analytics/analytics.service.ts"
click node_svc_billing "https://github.com/leohztest-blip/school-management-saas/blob/main/src/services/billing/billing.service.ts"
click node_svc_hr "https://github.com/leohztest-blip/school-management-saas/blob/main/src/services/hr/hr.service.ts"
click node_svc_reporting "https://github.com/leohztest-blip/school-management-saas/blob/main/src/services/reporting/reporting.service.ts"
click node_svc_comm "https://github.com/leohztest-blip/school-management-saas/blob/main/src/services/communication/communication.service.ts"
click node_supa_client "https://github.com/leohztest-blip/school-management-saas/blob/main/src/lib/supabase/client.ts"
click node_supa_server "https://github.com/leohztest-blip/school-management-saas/blob/main/src/lib/supabase/server.ts"
click node_supabase_schema "https://github.com/leohztest-blip/school-management-saas/blob/main/supabase/schema.sql"
click node_supabase_phase2 "https://github.com/leohztest-blip/school-management-saas/blob/main/supabase/schema_phase2.sql"
click node_supabase_branch "https://github.com/leohztest-blip/school-management-saas/blob/main/supabase/migrations/004_branches.sql"
click node_supabase_storage "https://github.com/leohztest-blip/school-management-saas/blob/main/supabase/storage.sql"
click node_edge_worker "https://github.com/leohztest-blip/school-management-saas/blob/main/edge-functions/job-worker/index.ts"

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_src_app_layout,node_src_middleware,node_src_permissions,node_src_auth_layout,node_src_auth_login,node_src_admin_layout,node_src_admin_home,node_src_dashboard_layout,node_src_dashboard_home,node_src_students_detail,node_src_parent_portal,node_src_dashboard_shell,node_src_data_table toneBlue
class node_svc_dashboard,node_svc_students,node_svc_analytics,node_svc_billing,node_svc_hr,node_svc_reporting,node_svc_comm toneAmber
class node_supa_client,node_supa_server,node_supabase_schema,node_supabase_phase2,node_supabase_branch,node_supabase_storage toneMint
class node_edge_worker toneRose
```

## Components

### Web App

Main Next.js application routes, layouts, and UI surface.

- [Root layout](https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/layout.tsx): next app shell · Top-level App Router shell for the main web app. · `src/app/layout.tsx`
- [Middleware](https://github.com/leohztest-blip/school-management-saas/blob/main/src/middleware.ts): route guard · Global request interception for auth and routing control. · `src/middleware.ts`
- [Permissions](https://github.com/leohztest-blip/school-management-saas/blob/main/src/config/permissions.ts): access control · Central permission rules used by routes and hooks. · `src/config/permissions.ts`
- [Auth layout](https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/(auth)/layout.tsx): route layout · Shell for login and registration flows. · `src/app/(auth)/layout.tsx`
- [Login](https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/(auth)/login/page.tsx): auth page · Primary authentication entry point. · `src/app/(auth)/login/page.tsx`
- [Admin layout](https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/admin/layout.tsx): route layout · Platform-admin shell for cross-school operations. · `src/app/admin/layout.tsx`
- [Admin home](https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/admin/page.tsx): admin page · Admin landing view. · `src/app/admin/page.tsx`
- [Dashboard layout](https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/dashboard/layout.tsx): route layout · Operational shell for school staff workflows. · `src/app/dashboard/layout.tsx`
- [Dashboard home](https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/dashboard/page.tsx): dashboard page · Operational landing view for school users. · `src/app/dashboard/page.tsx`
- [Student detail](https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/dashboard/students/[id]/page.tsx): record page · Dynamic student record route inside the dashboard. · `src/app/dashboard/students/[id]/page.tsx`
- [Parent portal](https://github.com/leohztest-blip/school-management-saas/blob/main/src/app/portal/parent/page.tsx): portal page · Parent-facing access path. · `src/app/portal/parent/page.tsx`
- [Chrome](https://github.com/leohztest-blip/school-management-saas/blob/main/src/components/layout/dashboard-layout.tsx): layout component · Shared authenticated navigation shell used across dashboard views. · `src/components/layout/dashboard-layout.tsx`
- [Data table](https://github.com/leohztest-blip/school-management-saas/blob/main/src/components/shared/data-table.tsx): shared ui · Reusable tabular workflow component for admin-style screens. · `src/components/shared/data-table.tsx`

### Domain Services

Business logic consumed by app routes and shared UI.

- [Dashboard svc](https://github.com/leohztest-blip/school-management-saas/blob/main/src/services/dashboard.service.ts): orchestration · General dashboard domain coordination layer. · `src/services/dashboard.service.ts`
- [Students svc](https://github.com/leohztest-blip/school-management-saas/blob/main/src/services/students.service.ts): domain service · Student-centric business logic and record workflows. · `src/services/students.service.ts`
- [Analytics svc](https://github.com/leohztest-blip/school-management-saas/blob/main/src/services/analytics/analytics.service.ts): domain service · Analytics and metrics aggregation for admin and dashboard views. · `src/services/analytics/analytics.service.ts`
- [Billing svc](https://github.com/leohztest-blip/school-management-saas/blob/main/src/services/billing/billing.service.ts): domain service · Fee and payment-related service layer. · `src/services/billing/billing.service.ts`
- [HR svc](https://github.com/leohztest-blip/school-management-saas/blob/main/src/services/hr/hr.service.ts): domain service · Staff, payroll, and people operations logic. · `src/services/hr/hr.service.ts`
- [Reporting svc](https://github.com/leohztest-blip/school-management-saas/blob/main/src/services/reporting/reporting.service.ts): domain service · Report generation and export logic. · `src/services/reporting/reporting.service.ts`
- [Comms svc](https://github.com/leohztest-blip/school-management-saas/blob/main/src/services/communication/communication.service.ts): domain service · Notifications and communication workflows. · `src/services/communication/communication.service.ts`

### Supabase Backend

Schema, migrations, storage, and dual client/server access paths.

- [Supabase client](https://github.com/leohztest-blip/school-management-saas/blob/main/src/lib/supabase/client.ts): browser data access · Client-side Supabase access path. · `src/lib/supabase/client.ts`
- [Supabase server](https://github.com/leohztest-blip/school-management-saas/blob/main/src/lib/supabase/server.ts): server data access · Server-side Supabase access path. · `src/lib/supabase/server.ts`
- [Schema](https://github.com/leohztest-blip/school-management-saas/blob/main/supabase/schema.sql): postgres schema · Primary database schema definition. · `supabase/schema.sql`
- [Phase 2 schema](https://github.com/leohztest-blip/school-management-saas/blob/main/supabase/schema_phase2.sql): postgres schema · Expanded schema for staged feature rollout. · `supabase/schema_phase2.sql`
- [Branches](https://github.com/leohztest-blip/school-management-saas/blob/main/supabase/migrations/004_branches.sql): migration · Tenant/branch-related migration. · `supabase/migrations/004_branches.sql`
- [Storage](https://github.com/leohztest-blip/school-management-saas/blob/main/supabase/storage.sql): storage schema · Supabase storage definitions. · `supabase/storage.sql`

### Edge Runtime

Separate worker bundle for background or offloaded processing.

- [Job worker](https://github.com/leohztest-blip/school-management-saas/blob/main/edge-functions/job-worker/index.ts): edge worker · Offloaded background processing outside the main request path. · `edge-functions/job-worker/index.ts`

## Connections

- Root layout → Auth layout: wraps auth · Root app shell contains the auth route group.
- Root layout → Admin layout: wraps admin · Root app shell contains the admin route group.
- Root layout → Dashboard layout: wraps dashboard · Root app shell contains the dashboard route group.
- Root layout → Parent portal: exposes portal · Root app shell also exposes parent-facing routes.
- Middleware → Permissions: uses · Middleware consults shared permission rules.
- Middleware → Auth layout: protects · Route protection gates access to auth and authenticated areas.
- Auth layout → Login: hosts · Auth layout hosts login and related screens.
- Admin layout → Admin home: hosts · Admin layout hosts the admin landing page.
- Dashboard layout → Dashboard home: hosts · Dashboard layout hosts the operational home screen.
- Dashboard layout → Student detail: hosts · Dashboard layout hosts dynamic student record routes.
- Dashboard layout → Chrome: uses · Dashboard routes share common authenticated chrome.
- Dashboard home → Dashboard svc: calls · Dashboard home is driven by dashboard orchestration services.
- Student detail → Students svc: calls · Student detail views depend on student domain services.
- Dashboard home → Analytics svc: calls · Dashboard pages consume analytics service outputs.
- Dashboard home → Billing svc: calls · Fees and payments screens use billing services.
- Dashboard home → HR svc: calls · Staff and payroll workflows use HR services.
- Dashboard home → Reporting svc: calls · Reports and exports use reporting services.
- Dashboard home → Comms svc: calls · Notifications and messaging use communication services.
- Dashboard svc → Supabase server: reads/writes · Server-side operations persist through Supabase.
- Students svc → Supabase server: reads/writes · Student workflows use server-side Supabase access.
- Analytics svc → Supabase server: queries · Analytics aggregates data from the backend.
- Billing svc → Supabase server: queries · Billing and payment operations query Supabase.
- HR svc → Supabase server: queries · HR operations query Supabase.
- Reporting svc → Supabase server: generates · Reports are built from server-side data access.
- Comms svc → Supabase server: notifies · Communication workflows consume backend state.
- Chrome → Data table: composes · Shared chrome renders common workflow components.
- Supabase server → Schema: targets · Server access is backed by the main database schema.
- Supabase server → Phase 2 schema: extends · Server access also aligns with phase 2 schema evolution.
- Supabase server → Branches: tracks · Branch-related migration supports tenant growth.
- Supabase server → Storage: uses · Server workflows use Supabase storage definitions.
- Supabase client → Schema: targets · Browser access reads from the same backend schema.
- Job worker → Supabase server: processes · Edge worker likely offloads backend tasks and job processing.
- Job worker → Comms svc: supports · Background execution can support notifications and async work.
- Job worker → Reporting svc: supports · Background execution can support document/report generation.