# med-abdellahi-07/neuron-showcase architecture

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

- Interactive diagram: https://gitdiagram.com/med-abdellahi-07/neuron-showcase
- Repository: https://github.com/med-abdellahi-07/neuron-showcase

## Overview

Neuron is an offline-first study PWA for university students. Students authenticate, choose course material, study and practise online or offline, and can ask a course-grounded assistant; their timetable, progress and later-synced results support that loop. Separate capabilities include class spaces, chat, announcements, recordings, notifications and staff administration. The README documents the overall integrations and offline flow; sampled route and library code confirms selected AI, snapshot, authentication and scheduling relationships. Many unsampled features are represented at their existing app-action or feature-directory paths, so their internal call wiring is not inferred.

Main entry points: [`src/app/api/chat/route.ts`](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/api/chat/route.ts) (Assistant chat route), [`src/app/api/offline-snapshot/route.ts`](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/api/offline-snapshot/route.ts) (Offline snapshot route), [`public/sw.js`](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/public/sw.js) (Offline PWA), [`src/lib/auth.ts`](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/lib/auth.ts) (Authentication and roles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Study and practice"]
  node_course_ui["Courses and lessons<br/>[page.tsx]"]
  node_practice["Practice and review<br/>[page.tsx]"]
  node_duels["Classmate duels<br/>[page.tsx]"]
  node_progress["Progress and streaks<br/>[page.tsx]"]
end

subgraph group_assistant["AI assistant"]
  node_assistant_ui["Assistant screens<br/>[page.tsx]"]
  node_chat_route["Assistant chat route<br/>[route.ts]"]
  node_rag["Course retrieval<br/>[rag.ts]"]
  node_guided["Guided explanations<br/>[guided.ts]"]
  node_ai_providers{{"AI providers"}}
  node_web_search{{"Web search"}}
end

subgraph group_campus["Campus operations"]
  node_schedule["Timetable<br/>[page.tsx]"]
  node_space_chat["Space chat<br/>[space-chat.tsx]"]
  node_admin["Staff administration<br/>[page.tsx]"]
  node_notifications["Push notifications<br/>[route.ts]"]
end

subgraph group_offline["Offline experience"]
  node_offline_pwa["Offline PWA<br/>[sw.js]"]
  node_offline_store[("Offline data store<br/>[db.ts]")]
  node_offline_sync["Result synchronization<br/>[sync.ts]"]
  node_snapshot["Offline snapshot route<br/>[route.ts]"]
end

subgraph group_foundation["Platform foundation"]
  node_auth["Authentication and roles<br/>[auth.ts]"]
  node_data["Course and schedule data<br/>[data.ts]"]
  node_spaces["Space access<br/>[spaces.ts]"]
  node_i18n["Arabic French English<br/>[dictionaries.ts]"]
end

node_student(("Student"))
node_supabase[("Supabase auth database storage")]

node_student -->|"studies"| node_course_ui
node_student -->|"practises"| node_practice
node_student -->|"asks"| node_assistant_ui
node_student -->|"checks"| node_schedule
node_student -->|"chats"| node_space_chat
node_assistant_ui -.->|"sends chat"| node_chat_route
node_chat_route -->|"checks identity"| node_auth
node_chat_route -->|"checks feature"| node_spaces
node_chat_route -->|"retrieves course"| node_rag
node_chat_route -->|"loads material"| node_guided
node_chat_route -.->|"searches optionally"| node_web_search
node_chat_route -->|"generates answer"| node_ai_providers
node_rag -.->|"reads course index"| node_supabase
node_student -->|"uses offline"| node_offline_pwa
node_offline_pwa -->|"reads and writes"| node_offline_store
node_offline_pwa -.->|"loads snapshot"| node_snapshot
node_snapshot -->|"gets profile"| node_auth
node_snapshot -->|"loads subjects"| node_data
node_snapshot -->|"reads sessions"| node_supabase
node_offline_sync -.->|"syncs results"| node_supabase
node_schedule -.->|"loads schedule data"| node_data
node_course_ui -.->|"loads course material"| node_supabase
node_practice -.->|"records attempts"| node_supabase
node_duels -.->|"stores duels"| node_supabase
node_progress -.->|"reads progress"| node_supabase
node_space_chat -.->|"uses chat route"| node_supabase
node_admin -.->|"manages platform data"| node_supabase
node_notifications -->|"reads and logs"| node_supabase
node_notifications -->|"sends reminders"| node_student
node_auth -->|"verifies session"| node_supabase
node_data -->|"reads schedule data"| node_supabase
node_spaces -->|"reads space"| node_supabase
node_student -->|"selects language"| node_i18n

click node_course_ui "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/(app)/subjects/%5Bcode%5D/%5Bkind%5D/page.tsx"
click node_practice "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/(app)/practice/page.tsx"
click node_duels "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/(app)/practice/duel/page.tsx"
click node_progress "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/(app)/progress/page.tsx"
click node_assistant_ui "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/(app)/assistant/page.tsx"
click node_chat_route "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/api/chat/route.ts"
click node_rag "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/lib/ai/rag.ts"
click node_guided "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/lib/ai/guided.ts"
click node_schedule "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/(app)/schedule/page.tsx"
click node_space_chat "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/components/space-chat.tsx"
click node_admin "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/(app)/admin/page.tsx"
click node_notifications "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/api/cron/notify/route.ts"
click node_offline_pwa "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/public/sw.js"
click node_offline_store "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/lib/offline/db.ts"
click node_offline_sync "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/lib/offline/sync.ts"
click node_snapshot "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/api/offline-snapshot/route.ts"
click node_auth "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/lib/auth.ts"
click node_data "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/lib/data.ts"
click node_spaces "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/lib/spaces.ts"
click node_i18n "https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/lib/i18n/dictionaries.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_course_ui,node_practice,node_duels,node_progress toneBlue
class node_assistant_ui,node_chat_route,node_rag,node_guided,node_ai_providers,node_web_search,node_supabase toneAmber
class node_schedule,node_space_chat,node_admin,node_notifications toneMint
class node_offline_pwa,node_offline_store,node_offline_sync,node_snapshot toneRose
class node_auth,node_data,node_spaces,node_i18n,node_student toneIndigo
```

## Components

### Study and practice

- [Courses and lessons](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/(app)/subjects/%5Bcode%5D/%5Bkind%5D/page.tsx): `src/app/(app)/subjects/[code]/[kind]/page.tsx`
- [Practice and review](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/(app)/practice/page.tsx): `src/app/(app)/practice/page.tsx`
- [Classmate duels](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/(app)/practice/duel/page.tsx): `src/app/(app)/practice/duel/page.tsx`
- [Progress and streaks](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/(app)/progress/page.tsx): `src/app/(app)/progress/page.tsx`

### AI assistant

- [Assistant screens](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/(app)/assistant/page.tsx): `src/app/(app)/assistant/page.tsx`
- [Assistant chat route](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [Course retrieval](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/lib/ai/rag.ts): `src/lib/ai/rag.ts`
- [Guided explanations](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/lib/ai/guided.ts): `src/lib/ai/guided.ts`
- **AI providers**
- **Web search**

### Campus operations

- [Timetable](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/(app)/schedule/page.tsx): `src/app/(app)/schedule/page.tsx`
- [Space chat](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/components/space-chat.tsx): `src/components/space-chat.tsx`
- [Staff administration](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/(app)/admin/page.tsx): `src/app/(app)/admin/page.tsx`
- [Push notifications](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/api/cron/notify/route.ts): `src/app/api/cron/notify/route.ts`

### Offline experience

- [Offline PWA](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/public/sw.js): `public/sw.js`
- [Offline data store](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/lib/offline/db.ts): `src/lib/offline/db.ts`
- [Result synchronization](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/lib/offline/sync.ts): `src/lib/offline/sync.ts`
- [Offline snapshot route](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/app/api/offline-snapshot/route.ts): `src/app/api/offline-snapshot/route.ts`

### Platform foundation

- [Authentication and roles](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [Course and schedule data](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/lib/data.ts): `src/lib/data.ts`
- [Space access](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/lib/spaces.ts): `src/lib/spaces.ts`
- [Arabic French English](https://github.com/med-abdellahi-07/neuron-showcase/blob/main/src/lib/i18n/dictionaries.ts): `src/lib/i18n/dictionaries.ts`

### Other components

- **Student**
- **Supabase auth database storage**

## Connections

- Student → Courses and lessons: studies
- Student → Practice and review: practises
- Student → Assistant screens: asks
- Student → Timetable: checks
- Student → Space chat: chats
- Assistant screens → Assistant chat route: sends chat
- Assistant chat route → Authentication and roles: checks identity (evidence: `src/app/api/chat/route.ts`)
- Assistant chat route → Space access: checks feature (evidence: `src/app/api/chat/route.ts`)
- Assistant chat route → Course retrieval: retrieves course (evidence: `src/app/api/chat/route.ts`)
- Assistant chat route → Guided explanations: loads material (evidence: `src/app/api/chat/route.ts`)
- Assistant chat route → Web search: searches optionally (evidence: `src/app/api/chat/route.ts`)
- Assistant chat route → AI providers: generates answer
- Course retrieval → Supabase auth database storage: reads course index
- Student → Offline PWA: uses offline
- Offline PWA → Offline data store: reads and writes
- Offline PWA → Offline snapshot route: loads snapshot
- Offline snapshot route → Authentication and roles: gets profile (evidence: `src/app/api/offline-snapshot/route.ts`)
- Offline snapshot route → Course and schedule data: loads subjects (evidence: `src/app/api/offline-snapshot/route.ts`)
- Offline snapshot route → Supabase auth database storage: reads sessions (evidence: `src/app/api/offline-snapshot/route.ts`)
- Result synchronization → Supabase auth database storage: syncs results
- Timetable → Course and schedule data: loads schedule data
- Courses and lessons → Supabase auth database storage: loads course material
- Practice and review → Supabase auth database storage: records attempts
- Classmate duels → Supabase auth database storage: stores duels
- Progress and streaks → Supabase auth database storage: reads progress
- Space chat → Supabase auth database storage: uses chat route
- Staff administration → Supabase auth database storage: manages platform data
- Push notifications → Supabase auth database storage: reads and logs (evidence: `src/app/api/cron/notify/route.ts`)
- Push notifications → Student: sends reminders (evidence: `src/app/api/cron/notify/route.ts`)
- Authentication and roles → Supabase auth database storage: verifies session (evidence: `src/lib/auth.ts`)
- Course and schedule data → Supabase auth database storage: reads schedule data (evidence: `src/lib/data.ts`)
- Space access → Supabase auth database storage: reads space (evidence: `src/lib/spaces.ts`)
- Student → Arabic French English: selects language