# asteria-07/schoolpulse architecture

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

- Interactive diagram: https://gitdiagram.com/asteria-07/schoolpulse
- Repository: https://github.com/asteria-07/schoolpulse

## Overview

SchoolPulse is a school-operations portal with role-oriented dashboards and backend APIs. Users enter through the sign-in experience, navigate operational areas such as attendance, students, staff, timetables, alerts and documents, and can request AI insights or document extraction. The frontend API client calls the FastAPI backend; backend handlers authenticate users and read or write school data through Supabase. The tree and excerpts establish these main capabilities, but do not show wiring for every route or the implementations of several subsystems.

Main entry points: [`schoolpulse-fullstack-final/schoolpulse-fullstack/src/components/app-shell.tsx`](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/components/app-shell.tsx) (App navigation), [`schoolpulse-fullstack-final/schoolpulse-fullstack/src/lib/api-client.ts`](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/lib/api-client.ts) (API client), [`schoolpulse-fullstack-final/schoolpulse-fullstack/backend/main.py`](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/backend/main.py) (FastAPI handlers), [`schoolpulse-fullstack-final/schoolpulse-fullstack/backend/supabase_client.py`](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/backend/supabase_client.py) (Supabase client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_sign_in["Sign-in<br/>[index.tsx]"]
  node_app_shell["App navigation<br/>[app-shell.tsx]"]
  node_router["Route setup<br/>[router.tsx]"]
  node_api_client["API client<br/>[api-client.ts]"]
end

subgraph group_operations["School operations"]
  node_dashboard["Dashboard<br/>[dashboard.tsx]"]
  node_attendance["Attendance<br/>[attendance.tsx]"]
  node_student_admin["Student records<br/>[students.tsx]"]
  node_staff_admin["Staff records<br/>[staff.tsx]"]
  node_timetable["Timetables<br/>[timetable.tsx]"]
  node_alerts["Alerts<br/>[alerts.tsx]"]
  node_documents["Documents<br/>[documents.tsx]"]
  node_parent_portal["Parent portal<br/>[parent.tsx]"]
  node_ai_copilot["AI copilot<br/>[ai-copilot.tsx]"]
end

subgraph group_services["Backend services"]
  node_api["FastAPI handlers<br/>[main.py]"]
  node_auth["Token validation<br/>[auth.py]"]
  node_ai_service["AI processing<br/>[ai.py]"]
  node_solver["Timetable solver<br/>[solver.py]"]
end

subgraph group_persistence["Identity and data"]
  node_supabase_client["Supabase client<br/>[supabase_client.py]"]
  node_supabase[("Supabase")]
end

node_school_user(("School user"))

node_school_user -->|"signs in"| node_sign_in
node_sign_in -->|"navigates"| node_router
node_router -->|"renders routes"| node_app_shell
node_app_shell -->|"navigates"| node_dashboard
node_app_shell -->|"navigates"| node_attendance
node_app_shell -->|"navigates"| node_student_admin
node_app_shell -->|"navigates"| node_staff_admin
node_app_shell -->|"navigates"| node_timetable
node_app_shell -->|"navigates"| node_alerts
node_app_shell -->|"navigates"| node_documents
node_school_user -->|"views portal"| node_parent_portal
node_api_client -->|"HTTP requests"| node_api
node_api -->|"validates user"| node_auth
node_auth -->|"verifies token"| node_supabase_client
node_api -->|"queries records"| node_supabase_client
node_supabase_client -->|"connects"| node_supabase
node_api -->|"requests AI work"| node_ai_service
node_ai_copilot -->|"requests insights"| node_api_client
node_documents -->|"uploads document"| node_api_client
node_attendance -->|"records attendance"| node_api_client
node_student_admin -->|"manages students"| node_api_client
node_staff_admin -->|"manages staff"| node_api_client
node_timetable -->|"requests solve"| node_api_client
node_api -->|"solves timetable"| node_solver

click node_sign_in "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/index.tsx"
click node_app_shell "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/components/app-shell.tsx"
click node_router "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/router.tsx"
click node_api_client "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/lib/api-client.ts"
click node_dashboard "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/dashboard.tsx"
click node_attendance "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/attendance.tsx"
click node_student_admin "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/students.tsx"
click node_staff_admin "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/staff.tsx"
click node_timetable "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/timetable.tsx"
click node_alerts "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/alerts.tsx"
click node_documents "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/documents.tsx"
click node_parent_portal "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/parent.tsx"
click node_ai_copilot "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/components/ai-copilot.tsx"
click node_api "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/backend/main.py"
click node_auth "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/backend/auth.py"
click node_ai_service "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/backend/ai.py"
click node_solver "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/backend/solver.py"
click node_supabase_client "https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/backend/supabase_client.py"

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_sign_in,node_app_shell,node_router,node_api_client,node_school_user toneBlue
class node_dashboard,node_attendance,node_student_admin,node_staff_admin,node_timetable,node_alerts,node_documents,node_parent_portal,node_ai_copilot toneAmber
class node_api,node_auth,node_ai_service,node_solver toneMint
class node_supabase_client,node_supabase toneRose
```

## Components

### Web experience

- [Sign-in](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/index.tsx): `schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/index.tsx`
- [App navigation](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/components/app-shell.tsx): `schoolpulse-fullstack-final/schoolpulse-fullstack/src/components/app-shell.tsx`
- [Route setup](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/router.tsx): `schoolpulse-fullstack-final/schoolpulse-fullstack/src/router.tsx`
- [API client](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/lib/api-client.ts): `schoolpulse-fullstack-final/schoolpulse-fullstack/src/lib/api-client.ts`

### School operations

- [Dashboard](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/dashboard.tsx): `schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/dashboard.tsx`
- [Attendance](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/attendance.tsx): `schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/attendance.tsx`
- [Student records](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/students.tsx): `schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/students.tsx`
- [Staff records](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/staff.tsx): `schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/staff.tsx`
- [Timetables](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/timetable.tsx): `schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/timetable.tsx`
- [Alerts](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/alerts.tsx): `schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/alerts.tsx`
- [Documents](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/documents.tsx): `schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/documents.tsx`
- [Parent portal](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/parent.tsx): `schoolpulse-fullstack-final/schoolpulse-fullstack/src/routes/parent.tsx`
- [AI copilot](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/src/components/ai-copilot.tsx): `schoolpulse-fullstack-final/schoolpulse-fullstack/src/components/ai-copilot.tsx`

### Backend services

- [FastAPI handlers](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/backend/main.py): `schoolpulse-fullstack-final/schoolpulse-fullstack/backend/main.py`
- [Token validation](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/backend/auth.py): `schoolpulse-fullstack-final/schoolpulse-fullstack/backend/auth.py`
- [AI processing](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/backend/ai.py): `schoolpulse-fullstack-final/schoolpulse-fullstack/backend/ai.py`
- [Timetable solver](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/backend/solver.py): `schoolpulse-fullstack-final/schoolpulse-fullstack/backend/solver.py`

### Identity and data

- [Supabase client](https://github.com/asteria-07/schoolpulse/blob/main/schoolpulse-fullstack-final/schoolpulse-fullstack/backend/supabase_client.py): `schoolpulse-fullstack-final/schoolpulse-fullstack/backend/supabase_client.py`
- **Supabase**

### Other components

- **School user**

## Connections

- School user → Sign-in: signs in
- Sign-in → Route setup: navigates
- Route setup → App navigation: renders routes
- App navigation → Dashboard: navigates
- App navigation → Attendance: navigates
- App navigation → Student records: navigates
- App navigation → Staff records: navigates
- App navigation → Timetables: navigates
- App navigation → Alerts: navigates
- App navigation → Documents: navigates
- School user → Parent portal: views portal
- API client → FastAPI handlers: HTTP requests
- FastAPI handlers → Token validation: validates user
- Token validation → Supabase client: verifies token
- FastAPI handlers → Supabase client: queries records
- Supabase client → Supabase: connects
- FastAPI handlers → AI processing: requests AI work
- AI copilot → API client: requests insights
- Documents → API client: uploads document
- Attendance → API client: records attendance
- Student records → API client: manages students
- Staff records → API client: manages staff
- Timetables → API client: requests solve
- FastAPI handlers → Timetable solver: solves timetable