How leohztest-blip/school-management-saas works
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: server.ts Supabase server · page.tsx Dashboard home · app/layout.tsx Root layout · dashboard/layout.tsx Dashboard layout
Components 27
Web App
Main Next.js application routes, layouts, and UI surface.
- Root layout · Top-level App Router shell for the main web app.
src/app/layout.tsx - Middleware · Global request interception for auth and routing control.
src/middleware.ts - Permissions · Central permission rules used by routes and hooks.
src/config/permissions.ts - Auth layout · Shell for login and registration flows.
src/app/(auth)/layout.tsx - Login · Primary authentication entry point.
src/app/(auth)/login/page.tsx - Admin layout · Platform-admin shell for cross-school operations.
src/app/admin/layout.tsx - Admin home · Admin landing view.
src/app/admin/page.tsx - Dashboard layout · Operational shell for school staff workflows.
src/app/dashboard/layout.tsx - Dashboard home · Operational landing view for school users.
src/app/dashboard/page.tsx - Student detail · Dynamic student record route inside the dashboard.
src/app/dashboard/students/[id]/page.tsx - Parent portal · Parent-facing access path.
src/app/portal/parent/page.tsx - Chrome · Shared authenticated navigation shell used across dashboard views.
src/components/layout/dashboard-layout.tsx - Data table · 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 · General dashboard domain coordination layer.
src/services/dashboard.service.ts - Students svc · Student-centric business logic and record workflows.
src/services/students.service.ts - Analytics svc · Analytics and metrics aggregation for admin and dashboard views.
src/services/analytics/analytics.service.ts - Billing svc · Fee and payment-related service layer.
src/services/billing/billing.service.ts - HR svc · Staff, payroll, and people operations logic.
src/services/hr/hr.service.ts - Reporting svc · Report generation and export logic.
src/services/reporting/reporting.service.ts - Comms svc · Notifications and communication workflows.
src/services/communication/communication.service.ts
Supabase Backend
Schema, migrations, storage, and dual client/server access paths.
- Supabase client · Client-side Supabase access path.
src/lib/supabase/client.ts - Supabase server · Server-side Supabase access path.
src/lib/supabase/server.ts - Schema · Primary database schema definition.
supabase/schema.sql - Phase 2 schema · Expanded schema for staged feature rollout.
supabase/schema_phase2.sql - Branches · Tenant/branch-related migration.
supabase/migrations/004_branches.sql - Storage · Supabase storage definitions.
supabase/storage.sql
Edge Runtime
Separate worker bundle for background or offloaded processing.
- Job worker · Offloaded background processing outside the main request path.
edge-functions/job-worker/index.ts
Connections 34
- 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.