# jasimedarath/edutech architecture

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

- Interactive diagram: https://gitdiagram.com/jasimedarath/edutech
- Repository: https://github.com/jasimedarath/edutech

## Overview

1. **Overall shape**
   - This is a **Next.js 14 App Router** application with TypeScript and Tailwind, organized as a **mobile-first EdTech PWA**.
   - The architecture splits into three main layers: **route-based UI**, **server API routes**, and **shared service/integration libraries**.

2. **User-facing application shells**
   - The `app/` directory defines distinct experiences for **login/onboarding**, **student**, **teacher**, **admin**, and **super-admin** users.
   - Each role has its own route subtree and loading states, which suggests a **role-based product surface** rather than a single generic dashboard.

3. **Role and access boundary**
   - `middleware.ts` and `lib/auth.ts` are the likely control points for **authentication and authorization**.
   - Authentication is backed by **Supabase Auth**, with server/client helpers split across `lib/supabase-server.ts` and `lib/supabase-browser.ts`.
   - The app likely redirects users into the correct role area after sign-in and blocks unauthorized access at the edge/server boundary.

4. **Core domain areas**
   - **Student flow:** `app/student/*` and components like `PracticeDeck`, `ChatTutor`, `BadgePill`, and `StudentNav` support learning, practice, chat, and progress.
   - **Teacher flow:** `app/teacher/*` plus `GenerateForm`, `StudentDetailsSheet`, `HeatmapStrip`, and `TeacherNav` support content generation and learner monitoring.
   - **Admin / super-admin flow:** `app/admin/*` and `app/super-admin/*` manage tenants, schools, users, teachers, and admins.

5. **API surface by domain**
   - The `app/api/` tree is the main server-side boundary and is organized by feature:
     - `api/ai/*` for content generation
     - `api/chat` for tutoring/chat interactions
     - `api/progress/update` for learner progress tracking
     - `api/teacher/*` for teacher analytics and student data
     - `api/admin/*` and `api/super-admin/*` for operational management
     - `api/notifications/*` for push subscription and sending
   - This indicates a **feature-oriented API layer** rather than a generic REST backend.

6. **AI and content generation pipeline**
   - `lib/claude.ts`, `lib/cloudflare.ts`, and `lib/zsky.ts` show three AI/media providers:
     - **Anthropic Claude** for text and quizzes
     - **Cloudflare Workers AI** for images
     - **ZSky AI** for video
   - The AI routes are designed to **gracefully fall back to demo responses** when keys are missing, so the product can run in a partially configured or demo mode.

7. **Persistence and backend services**
   - Supabase is the primary backend: **auth, database, and likely storage**.
   - `supabase/schema.sql` is the canonical schema boundary, and the `lib/*data.ts` files imply domain-specific data access for tenants, teachers, and mock/demo content.
   - `lib/mock-data.ts` suggests the UI can render without live backend data, which is useful for scaffolding and demos.

8. **Offline-first PWA layer**
   - The project includes `public/manifest.json`, `public/sw.js`, Workbox assets, and `lib/indexeddb.ts`, so the app is built as a **PWA with offline caching and local persistence**.
   - UI helpers like `OfflineBanner`, `InstallPrompt`, `PullToRefresh`, and `PageLoader` reinforce the mobile app-like experience.
   - This means the client can continue to function with **cached assets and local data**, then sync back when online.

9. **Notifications and device messaging**
   - `lib/webpush.ts` and `app/api/notifications/*` form the push notification subsystem.
   - The app supports both **subscription registration** and **server-side send flows**, likely tied to classroom or learner engagement reminders.

10. **Operational / admin management**
   - Admin routes manage **schools, tenants, users, subjects, and classes**, while super-admin routes manage **admins, tenants, and school status**.
   - The presence of `TenantProfileForm`, `TenantUsersManager`, `SchoolClassesManager`, and `SchoolSubjectsManager` indicates a **multi-tenant education administration model**.

11. **Runtime and deployment concerns**
   - This is a **hybrid server/client Next.js app**: pages render in the app router, while API routes handle server operations and external calls.
   - `lib/rate-limit.ts` and `lib/usage.ts` indicate the backend includes **quota/usage control**, which is important for AI cost management and abuse prevention.

12. **Diagram-friendly data flow**
   - A useful diagram would show:
     - Browser/PWA client → Next.js app routes
     - Auth via Supabase → role-based routing/middleware
     - Client pages → internal API routes
     - API routes → Supabase database/Auth + external AI providers + Web Push
     - Offline path → Service worker + IndexedDB
   - The main architectural boundary is between **presentation/role surfaces** and **server integrations**.

Main entry points: [`app/student`](https://github.com/jasimedarath/edutech/tree/main/app/student) (Student app), [`app/layout.tsx`](https://github.com/jasimedarath/edutech/blob/main/app/layout.tsx) (App shell), [`middleware.ts`](https://github.com/jasimedarath/edutech/blob/main/middleware.ts) (Middleware), [`app/teacher`](https://github.com/jasimedarath/edutech/tree/main/app/teacher) (Teacher app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App surfaces"]
  node_app_root["App shell<br/>Next.js shell<br/>[layout.tsx]"]
  node_app_login["Login<br/>auth route<br/>[page.tsx]"]
  node_app_onboarding["Onboarding<br/>setup route<br/>[page.tsx]"]
  node_app_student["Student app<br/>learner routes"]
  node_app_teacher["Teacher app<br/>educator routes"]
  node_app_admin["Admin app<br/>tenant admin routes"]
  node_app_superadmin["Super-admin app<br/>platform admin routes"]
end

subgraph group_group_api["API surface"]
  node_api_ai["AI API<br/>generation endpoints"]
  node_api_chat["Chat API<br/>tutor endpoint<br/>[route.ts]"]
  node_api_progress["Progress API<br/>tracking endpoint<br/>[route.ts]"]
  node_api_teacher["Teacher API<br/>analytics endpoints"]
  node_api_admin["Admin API<br/>ops endpoints"]
  node_api_superadmin["Super-admin API<br/>platform ops"]
  node_api_notifications["Notifications API<br/>push endpoints"]
  node_api_auth_callback["Auth callback<br/>auth route<br/>[route.ts]"]
end

subgraph group_group_lib["Shared services"]
  node_middleware{{"Middleware<br/>access gate<br/>[middleware.ts]"}}
  node_auth_lib["Auth logic<br/>auth helpers<br/>[auth.ts]"]
  node_supabase_server[("Server Supabase<br/>supabase server client<br/>[supabase-server.ts]")]
  node_supabase_browser[("Browser Supabase<br/>supabase client")]
  node_teacher_data["Teacher data<br/>domain access<br/>[teacher-data.ts]"]
  node_tenant_data["Tenant data<br/>domain access<br/>[tenant-data.ts]"]
  node_ai_claude["Claude<br/>text AI<br/>[claude.ts]"]
  node_ai_cloudflare["Cloudflare AI<br/>image AI<br/>[cloudflare.ts]"]
  node_ai_zsky["ZSky AI<br/>video AI<br/>[zsky.ts]"]
  node_indexeddb[("IndexedDB<br/>local cache<br/>[indexeddb.ts]")]
  node_webpush["Web Push<br/>notification service<br/>[webpush.ts]"]
  node_schema[("Schema<br/>[schema.sql]")]
end

subgraph group_group_pwa["PWA layer"]
  node_pwa_assets["PWA assets<br/>offline runtime<br/>[sw.js]"]
end

node_middleware -->|"checks"| node_auth_lib
node_middleware -->|"routes"| node_app_student
node_middleware -->|"routes"| node_app_teacher
node_middleware -->|"routes"| node_app_admin
node_middleware -->|"routes"| node_app_superadmin
node_app_login -->|"sign-in"| node_api_auth_callback
node_app_root -->|"entry"| node_app_login
node_app_root -->|"setup"| node_app_onboarding
node_app_root -->|"surface"| node_app_student
node_app_root -->|"surface"| node_app_teacher
node_app_root -->|"surface"| node_app_admin
node_app_root -->|"surface"| node_app_superadmin
node_app_student -->|"uses"| node_api_chat
node_app_student -->|"uses"| node_api_progress
node_app_student -->|"caches"| node_indexeddb
node_app_teacher -->|"uses"| node_api_teacher
node_app_teacher -->|"uses"| node_api_ai
node_app_admin -->|"uses"| node_api_admin
node_app_superadmin -->|"uses"| node_api_superadmin
node_api_ai -->|"text"| node_ai_claude
node_api_ai -->|"image"| node_ai_cloudflare
node_api_ai -->|"video"| node_ai_zsky
node_api_chat -->|"tutor"| node_ai_claude
node_api_progress -->|"writes"| node_supabase_server
node_api_teacher -->|"reads"| node_teacher_data
node_api_admin -->|"reads/writes"| node_tenant_data
node_api_superadmin -->|"reads/writes"| node_tenant_data
node_api_notifications -->|"sends"| node_webpush
node_api_notifications -->|"stores"| node_supabase_server
node_api_auth_callback -->|"verifies"| node_supabase_server
node_supabase_server -->|"uses"| node_schema
node_supabase_browser -.->|"uses"| node_schema
node_app_student -->|"offline"| node_pwa_assets
node_app_teacher -->|"offline"| node_pwa_assets
node_app_admin -->|"offline"| node_pwa_assets
node_app_superadmin -->|"offline"| node_pwa_assets
node_app_student -->|"subscribes"| node_api_notifications

click node_app_root "https://github.com/jasimedarath/edutech/blob/main/app/layout.tsx"
click node_app_login "https://github.com/jasimedarath/edutech/blob/main/app/login/page.tsx"
click node_app_onboarding "https://github.com/jasimedarath/edutech/blob/main/app/onboarding/page.tsx"
click node_app_student "https://github.com/jasimedarath/edutech/tree/main/app/student"
click node_app_teacher "https://github.com/jasimedarath/edutech/tree/main/app/teacher"
click node_app_admin "https://github.com/jasimedarath/edutech/tree/main/app/admin"
click node_app_superadmin "https://github.com/jasimedarath/edutech/tree/main/app/super-admin"
click node_middleware "https://github.com/jasimedarath/edutech/blob/main/middleware.ts"
click node_auth_lib "https://github.com/jasimedarath/edutech/blob/main/lib/auth.ts"
click node_supabase_server "https://github.com/jasimedarath/edutech/blob/main/lib/supabase-server.ts"
click node_supabase_browser "https://github.com/jasimedarath/edutech/blob/main/lib/supabase-browser.ts"
click node_teacher_data "https://github.com/jasimedarath/edutech/blob/main/lib/teacher-data.ts"
click node_tenant_data "https://github.com/jasimedarath/edutech/blob/main/lib/tenant-data.ts"
click node_ai_claude "https://github.com/jasimedarath/edutech/blob/main/lib/claude.ts"
click node_ai_cloudflare "https://github.com/jasimedarath/edutech/blob/main/lib/cloudflare.ts"
click node_ai_zsky "https://github.com/jasimedarath/edutech/blob/main/lib/zsky.ts"
click node_indexeddb "https://github.com/jasimedarath/edutech/blob/main/lib/indexeddb.ts"
click node_webpush "https://github.com/jasimedarath/edutech/blob/main/lib/webpush.ts"
click node_pwa_assets "https://github.com/jasimedarath/edutech/blob/main/public/sw.js"
click node_api_ai "https://github.com/jasimedarath/edutech/tree/main/app/api/ai"
click node_api_chat "https://github.com/jasimedarath/edutech/blob/main/app/api/chat/route.ts"
click node_api_progress "https://github.com/jasimedarath/edutech/blob/main/app/api/progress/update/route.ts"
click node_api_teacher "https://github.com/jasimedarath/edutech/tree/main/app/api/teacher"
click node_api_admin "https://github.com/jasimedarath/edutech/tree/main/app/api/admin"
click node_api_superadmin "https://github.com/jasimedarath/edutech/tree/main/app/api/super-admin"
click node_api_notifications "https://github.com/jasimedarath/edutech/tree/main/app/api/notifications"
click node_api_auth_callback "https://github.com/jasimedarath/edutech/blob/main/app/auth/callback/route.ts"
click node_schema "https://github.com/jasimedarath/edutech/blob/main/supabase/schema.sql"

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_app_root,node_app_login,node_app_onboarding,node_app_student,node_app_teacher,node_app_admin,node_app_superadmin toneBlue
class node_api_ai,node_api_chat,node_api_progress,node_api_teacher,node_api_admin,node_api_superadmin,node_api_notifications,node_api_auth_callback toneAmber
class node_middleware,node_auth_lib,node_supabase_server,node_supabase_browser,node_teacher_data,node_tenant_data,node_ai_claude,node_ai_cloudflare,node_ai_zsky,node_indexeddb,node_webpush,node_schema toneMint
class node_pwa_assets toneRose
```

## Components

### App surfaces

Route-based user experiences and shells

- [App shell](https://github.com/jasimedarath/edutech/blob/main/app/layout.tsx): Next.js shell · Global layout and top-level routing entry for the App Router · `app/layout.tsx`
- [Login](https://github.com/jasimedarath/edutech/blob/main/app/login/page.tsx): auth route · Sign-in entry and loading state · `app/login/page.tsx`
- [Onboarding](https://github.com/jasimedarath/edutech/blob/main/app/onboarding/page.tsx): setup route · First-run onboarding flow · `app/onboarding/page.tsx`
- [Student app](https://github.com/jasimedarath/edutech/tree/main/app/student): learner routes · Student learning surface with practice, progress, topics, and chat · `app/student`
- [Teacher app](https://github.com/jasimedarath/edutech/tree/main/app/teacher): educator routes · Teacher dashboard, generation, library, and student views · `app/teacher`
- [Admin app](https://github.com/jasimedarath/edutech/tree/main/app/admin): tenant admin routes · Tenant and school administration surface · `app/admin`
- [Super-admin app](https://github.com/jasimedarath/edutech/tree/main/app/super-admin): platform admin routes · Platform-level management surface for tenants, schools, and admins · `app/super-admin`

### API surface

Feature-oriented server routes

- [AI API](https://github.com/jasimedarath/edutech/tree/main/app/api/ai): generation endpoints · Explanation, quiz, image, and video generation routes · `app/api/ai`
- [Chat API](https://github.com/jasimedarath/edutech/blob/main/app/api/chat/route.ts): tutor endpoint · Student tutoring chat endpoint · `app/api/chat/route.ts`
- [Progress API](https://github.com/jasimedarath/edutech/blob/main/app/api/progress/update/route.ts): tracking endpoint · Learner progress update endpoint · `app/api/progress/update/route.ts`
- [Teacher API](https://github.com/jasimedarath/edutech/tree/main/app/api/teacher): analytics endpoints · Teacher heatmap and student data endpoints · `app/api/teacher`
- [Admin API](https://github.com/jasimedarath/edutech/tree/main/app/api/admin): ops endpoints · Admin CRUD and school management endpoints · `app/api/admin`
- [Super-admin API](https://github.com/jasimedarath/edutech/tree/main/app/api/super-admin): platform ops · Platform management endpoints for admins, tenants, and schools · `app/api/super-admin`
- [Notifications API](https://github.com/jasimedarath/edutech/tree/main/app/api/notifications): push endpoints · Subscription registration and server-side send endpoints · `app/api/notifications`
- [Auth callback](https://github.com/jasimedarath/edutech/blob/main/app/auth/callback/route.ts): auth route · Callback handler for login/session completion · `app/auth/callback/route.ts`

### Shared services

Auth, data, AI, and infrastructure helpers

- [Middleware](https://github.com/jasimedarath/edutech/blob/main/middleware.ts): access gate · Edge authorization and role-based routing boundary · `middleware.ts`
- [Auth logic](https://github.com/jasimedarath/edutech/blob/main/lib/auth.ts): auth helpers · Session and role helpers used for gating and redirects · `lib/auth.ts`
- [Server Supabase](https://github.com/jasimedarath/edutech/blob/main/lib/supabase-server.ts): supabase server client · Server-side Supabase integration for auth and data access · `lib/supabase-server.ts`
- [Browser Supabase](https://github.com/jasimedarath/edutech/blob/main/lib/supabase-browser.ts): supabase client · Client-side Supabase helper for browser sessions · `lib/supabase-browser.ts`
- [Teacher data](https://github.com/jasimedarath/edutech/blob/main/lib/teacher-data.ts): domain access · Teacher and classroom data access layer · `lib/teacher-data.ts`
- [Tenant data](https://github.com/jasimedarath/edutech/blob/main/lib/tenant-data.ts): domain access · Tenant and school administration data access layer · `lib/tenant-data.ts`
- [Claude](https://github.com/jasimedarath/edutech/blob/main/lib/claude.ts): text AI · Anthropic-powered text, quiz, and explanation generation · `lib/claude.ts`
- [Cloudflare AI](https://github.com/jasimedarath/edutech/blob/main/lib/cloudflare.ts): image AI · Image generation provider integration · `lib/cloudflare.ts`
- [ZSky AI](https://github.com/jasimedarath/edutech/blob/main/lib/zsky.ts): video AI · Video generation provider integration · `lib/zsky.ts`
- [IndexedDB](https://github.com/jasimedarath/edutech/blob/main/lib/indexeddb.ts): local cache · Local persistence for offline-first client state · `lib/indexeddb.ts`
- [Web Push](https://github.com/jasimedarath/edutech/blob/main/lib/webpush.ts): notification service · Push subscription and delivery helpers · `lib/webpush.ts`
- [Schema](https://github.com/jasimedarath/edutech/blob/main/supabase/schema.sql): database schema · Canonical Supabase schema definition · `supabase/schema.sql`

### PWA layer

Offline cache and installable client support

- [PWA assets](https://github.com/jasimedarath/edutech/blob/main/public/sw.js): offline runtime · Manifest, service worker, and Workbox assets for installable offline mode · `public/sw.js`

## Connections

- Middleware → Auth logic: checks · Uses auth helpers to enforce role-based access
- Middleware → Student app: routes · Protects learner routes
- Middleware → Teacher app: routes · Protects teacher routes
- Middleware → Admin app: routes · Protects tenant admin routes
- Middleware → Super-admin app: routes · Protects platform admin routes
- Login → Auth callback: sign-in · Completes authentication flow
- App shell → Login: entry · Public entry path
- App shell → Onboarding: setup · First-time onboarding path
- App shell → Student app: surface · Learner experience shell
- App shell → Teacher app: surface · Teacher experience shell
- App shell → Admin app: surface · Admin experience shell
- App shell → Super-admin app: surface · Super-admin experience shell
- Student app → Chat API: uses · Student tutor chat
- Student app → Progress API: uses · Reports learning progress
- Student app → IndexedDB: caches · Stores offline student state
- Teacher app → Teacher API: uses · Loads class and learner analytics
- Teacher app → AI API: uses · Generates teaching content
- Admin app → Admin API: uses · Admin management actions
- Super-admin app → Super-admin API: uses · Platform management actions
- AI API → Claude: text · Explanation and quiz generation
- AI API → Cloudflare AI: image · Image generation
- AI API → ZSky AI: video · Video generation
- Chat API → Claude: tutor · Chat responses and tutoring assistance
- Progress API → Server Supabase: writes · Persists progress updates
- Teacher API → Teacher data: reads · Teacher dashboards and student summaries
- Admin API → Tenant data: reads/writes · Tenant, school, class, and user administration
- Super-admin API → Tenant data: reads/writes · Platform-level tenant and school management
- Notifications API → Web Push: sends · Push subscription and delivery
- Notifications API → Server Supabase: stores · Persists notification state and subscriptions
- Auth callback → Server Supabase: verifies · Completes server-side auth session setup
- Server Supabase → Schema: uses · Backed by canonical database schema
- Browser Supabase → Schema: uses · Client reads/writes through Supabase
- Student app → PWA assets: offline · Works with service worker and manifest
- Teacher app → PWA assets: offline · Works with service worker and manifest
- Admin app → PWA assets: offline · Works with service worker and manifest
- Super-admin app → PWA assets: offline · Works with service worker and manifest
- Student app → Notifications API: subscribes · Registers push subscription