# shawnstudio-org/spis-web architecture

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

- Interactive diagram: https://gitdiagram.com/shawnstudio-org/spis-web
- Repository: https://github.com/shawnstudio-org/spis-web

## Overview

SPIS Web is a Next.js frontend for managing students and turning mock-test reports into analysis, prescriptions, practice, and progress tracking. Users register or sign in, manage student profiles, submit reports, then review diagnosis and study guidance; the dashboard and plan settings provide account-level views. The README documents these capabilities, but most page implementations and the API client were not sampled, so links for those features reflect documented routes and visible API usage rather than inspected internal details.

Main entry points: [`src/lib/api.js`](https://github.com/shawnstudio-org/spis-web/blob/main/src/lib/api.js) (API client), [`src/app/students/[id]/diagnosis/page.js`](https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/%5Bid%5D/diagnosis/page.js) (Diagnosis), [`src/lib/auth-client.js`](https://github.com/shawnstudio-org/spis-web/blob/main/src/lib/auth-client.js) (Auth guard), [`src/app/students/page.js`](https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/page.js) (Student profiles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and account"]
  node_login["Sign in<br/>[page.js]"]
  node_register["Register<br/>[page.js]"]
  node_auth["Auth guard<br/>[auth-client.js]"]
  node_plan["Plan settings<br/>[page.js]"]
end

subgraph group_students["Student workspace"]
  node_dashboard["Dashboard<br/>[page.js]"]
  node_studentlist["Student profiles<br/>[page.js]"]
end

subgraph group_insights["Learning insights"]
  node_reportentry["Report entry<br/>[page.js]"]
  node_reporthistory["Report history<br/>[page.js]"]
  node_diagnosis["Diagnosis<br/>[page.js]"]
  node_prescriptions["Prescriptions<br/>[page.js]"]
  node_practice["Daily practice<br/>[page.js]"]
  node_progress["Progress tracking<br/>[page.js]"]
  node_strategy["Study strategy<br/>[page.js]"]
  node_advancedreport["Advanced report<br/>[page.js]"]
end

subgraph group_shared["App services"]
  node_api["API client<br/>[api.js]"]
  node_studentcontext["Student context"]
  node_viewmodels["View models<br/>[view-models.js]"]
  node_shell["App shell<br/>[AppShell.jsx]"]
end

node_user(("Parent or tutor"))
node_worker{{"SPIS Worker API"}}

node_user -->|"signs in"| node_login
node_user -->|"creates account"| node_register
node_login -->|"authenticates"| node_api
node_register -->|"registers"| node_api
node_login -->|"stores token"| node_auth
node_register -->|"stores token"| node_auth
node_auth -->|"checks session"| node_api
node_plan -->|"reads and updates"| node_api
node_user -->|"manages students"| node_studentlist
node_studentlist -->|"checks session"| node_auth
node_studentlist -->|"loads and edits"| node_api
node_dashboard -->|"loads overview"| node_api
node_user -->|"submits report"| node_reportentry
node_reportentry -->|"checks session"| node_auth
node_reportentry -->|"submits report"| node_api
node_advancedreport -->|"submits report"| node_api
node_reporthistory -->|"loads reports"| node_api
node_diagnosis -->|"loads student context"| node_studentcontext
node_studentcontext -->|"checks session"| node_auth
node_diagnosis -->|"analyzes report"| node_api
node_diagnosis -->|"generates prescription"| node_api
node_diagnosis -->|"updates items"| node_api
node_diagnosis -->|"normalizes results"| node_viewmodels
node_prescriptions -->|"loads prescriptions"| node_api
node_practice -->|"loads practice"| node_api
node_progress -->|"loads progress"| node_api
node_strategy -->|"loads strategy"| node_api
node_api -->|"sends requests"| node_worker
node_studentlist -->|"renders within"| node_shell
node_diagnosis -->|"renders within"| node_shell

click node_login "https://github.com/shawnstudio-org/spis-web/blob/main/src/app/login/page.js"
click node_register "https://github.com/shawnstudio-org/spis-web/blob/main/src/app/register/page.js"
click node_auth "https://github.com/shawnstudio-org/spis-web/blob/main/src/lib/auth-client.js"
click node_plan "https://github.com/shawnstudio-org/spis-web/blob/main/src/app/settings/plan/page.js"
click node_dashboard "https://github.com/shawnstudio-org/spis-web/blob/main/src/app/dashboard/page.js"
click node_studentlist "https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/page.js"
click node_reportentry "https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/%5Bid%5D/reports/new/page.js"
click node_reporthistory "https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/%5Bid%5D/reports/page.js"
click node_diagnosis "https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/%5Bid%5D/diagnosis/page.js"
click node_prescriptions "https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/%5Bid%5D/prescriptions/page.js"
click node_practice "https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/%5Bid%5D/daily-practice/page.js"
click node_progress "https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/%5Bid%5D/progress/page.js"
click node_strategy "https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/%5Bid%5D/strategy/page.js"
click node_advancedreport "https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/%5Bid%5D/reports/new/advanced/page.js"
click node_api "https://github.com/shawnstudio-org/spis-web/blob/main/src/lib/api.js"
click node_studentcontext "https://github.com/shawnstudio-org/spis-web/blob/main/src/lib/use-student-page.js"
click node_viewmodels "https://github.com/shawnstudio-org/spis-web/blob/main/src/lib/view-models.js"
click node_shell "https://github.com/shawnstudio-org/spis-web/blob/main/src/components/AppShell.jsx"

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_login,node_register,node_auth,node_plan toneBlue
class node_dashboard,node_studentlist toneAmber
class node_reportentry,node_reporthistory,node_diagnosis,node_prescriptions,node_practice,node_progress,node_strategy,node_advancedreport toneMint
class node_api,node_studentcontext,node_viewmodels,node_shell,node_worker toneRose
class node_user toneIndigo
```

## Components

### Identity and account

- [Sign in](https://github.com/shawnstudio-org/spis-web/blob/main/src/app/login/page.js): `src/app/login/page.js`
- [Register](https://github.com/shawnstudio-org/spis-web/blob/main/src/app/register/page.js): `src/app/register/page.js`
- [Auth guard](https://github.com/shawnstudio-org/spis-web/blob/main/src/lib/auth-client.js): `src/lib/auth-client.js`
- [Plan settings](https://github.com/shawnstudio-org/spis-web/blob/main/src/app/settings/plan/page.js): `src/app/settings/plan/page.js`

### Student workspace

- [Dashboard](https://github.com/shawnstudio-org/spis-web/blob/main/src/app/dashboard/page.js): `src/app/dashboard/page.js`
- [Student profiles](https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/page.js): `src/app/students/page.js`

### Learning insights

- [Report entry](https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/%5Bid%5D/reports/new/page.js): `src/app/students/[id]/reports/new/page.js`
- [Report history](https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/%5Bid%5D/reports/page.js): `src/app/students/[id]/reports/page.js`
- [Diagnosis](https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/%5Bid%5D/diagnosis/page.js): `src/app/students/[id]/diagnosis/page.js`
- [Prescriptions](https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/%5Bid%5D/prescriptions/page.js): `src/app/students/[id]/prescriptions/page.js`
- [Daily practice](https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/%5Bid%5D/daily-practice/page.js): `src/app/students/[id]/daily-practice/page.js`
- [Progress tracking](https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/%5Bid%5D/progress/page.js): `src/app/students/[id]/progress/page.js`
- [Study strategy](https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/%5Bid%5D/strategy/page.js): `src/app/students/[id]/strategy/page.js`
- [Advanced report](https://github.com/shawnstudio-org/spis-web/blob/main/src/app/students/%5Bid%5D/reports/new/advanced/page.js): `src/app/students/[id]/reports/new/advanced/page.js`

### App services

- [API client](https://github.com/shawnstudio-org/spis-web/blob/main/src/lib/api.js): `src/lib/api.js`
- [Student context](https://github.com/shawnstudio-org/spis-web/blob/main/src/lib/use-student-page.js): `src/lib/use-student-page.js`
- [View models](https://github.com/shawnstudio-org/spis-web/blob/main/src/lib/view-models.js): `src/lib/view-models.js`
- [App shell](https://github.com/shawnstudio-org/spis-web/blob/main/src/components/AppShell.jsx): `src/components/AppShell.jsx`

### Other components

- **Parent or tutor**
- **SPIS Worker API**

## Connections

- Parent or tutor → Sign in: signs in
- Parent or tutor → Register: creates account
- Sign in → API client: authenticates
- Register → API client: registers
- Sign in → Auth guard: stores token
- Register → Auth guard: stores token
- Auth guard → API client: checks session
- Plan settings → API client: reads and updates
- Parent or tutor → Student profiles: manages students
- Student profiles → Auth guard: checks session
- Student profiles → API client: loads and edits
- Dashboard → API client: loads overview
- Parent or tutor → Report entry: submits report
- Report entry → Auth guard: checks session
- Report entry → API client: submits report
- Advanced report → API client: submits report
- Report history → API client: loads reports
- Diagnosis → Student context: loads student context
- Student context → Auth guard: checks session
- Diagnosis → API client: analyzes report
- Diagnosis → API client: generates prescription
- Diagnosis → API client: updates items
- Diagnosis → View models: normalizes results
- Prescriptions → API client: loads prescriptions
- Daily practice → API client: loads practice
- Progress tracking → API client: loads progress
- Study strategy → API client: loads strategy
- API client → SPIS Worker API: sends requests
- Student profiles → App shell: renders within
- Diagnosis → App shell: renders within