# natsouzax/lexuri architecture

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

- Interactive diagram: https://gitdiagram.com/natsouzax/lexuri
- Repository: https://github.com/natsouzax/lexuri

## Overview

Lexuri is a research prototype for learning English through music. Its main journey is account setup and level selection, studying songs with synced lyrics and translation, saving vocabulary, completing a three-day review cycle, and turning personal takeaways into a song. Album study, glossary practice, speaking/pronunciation, and gamification are additional product branches. The README documents the overall learner flow; source excerpts confirm selected API-to-service and persistence relationships, while many UI and route implementations were not sampled.

Main entry points: [`lib/supabase-server.ts`](https://github.com/natsouzax/lexuri/blob/master/lib/supabase-server.ts) (Supabase data), [`app/api/takeaways/route.ts`](https://github.com/natsouzax/lexuri/blob/master/app/api/takeaways/route.ts) (Takeaways and verses), [`components/YoutubeSyncPlayer.tsx`](https://github.com/natsouzax/lexuri/blob/master/components/YoutubeSyncPlayer.tsx) (Synced lyric player), [`components/LessonView.tsx`](https://github.com/natsouzax/lexuri/blob/master/components/LessonView.tsx) (Lesson and chunks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Song learning"]
  node_catalog["Song and album catalog<br/>[page.tsx]"]
  node_album["Album journeys<br/>[page.tsx]"]
  node_lessons["Static lesson library<br/>[index.ts]"]
  node_player["Synced lyric player"]
  node_lessonview["Lesson and chunks<br/>[LessonView.tsx]"]
  node_translator["Floating translator"]
end

subgraph group_review["Review and glossary"]
  node_flashcards["Vocabulary library<br/>[page.tsx]"]
  node_reviewcycle["Three-day song review<br/>[SrsSession.tsx]"]
  node_srs["Spaced repetition<br/>[srs.ts]"]
  node_glossary["Glossary practice<br/>[route.ts]"]
  node_speaking["Speaking review<br/>[SpeakingReview.tsx]"]
end

subgraph group_creation["Personal music"]
  node_takeaways["Takeaways and verses<br/>[route.ts]"]
  node_studio["Personal song studio<br/>[MusicStudio.tsx]"]
  node_songapi["Personal song generation<br/>[route.ts]"]
end

subgraph group_engagement["Progress and accounts"]
  node_auth["Sign in and level<br/>[page.tsx]"]
  node_dashboard["Dashboard and missions<br/>[page.tsx]"]
  node_gamification["XP and leaderboard<br/>[gamification.ts]"]
end

subgraph group_platform["Runtime services"]
  node_translation["Translation and definition<br/>[route.ts]"]
  node_speechapi["Speech assessment<br/>[route.ts]"]
  node_database[("Supabase data<br/>[supabase-server.ts]")]
  node_media["Media and lyrics adapters<br/>[index.ts]"]
end

node_learner(("Learner"))
node_openai{{"OpenAI services"}}
node_youtube{{"YouTube media"}}

node_learner -->|"creates account"| node_auth
node_auth -->|"opens songs"| node_catalog
node_catalog -->|"loads lessons"| node_lessons
node_album -->|"uses album tracks"| node_lessons
node_lessons -->|"supplies synced lyrics"| node_player
node_player -->|"plays video"| node_youtube
node_player -->|"shows lyrics"| node_lessonview
node_lessonview -->|"opens translation"| node_translator
node_translator -->|"requests translation"| node_translation
node_translation -.->|"calls model"| node_openai
node_lessonview -->|"saves vocabulary"| node_flashcards
node_flashcards -->|"starts review"| node_reviewcycle
node_reviewcycle -->|"schedules cards"| node_srs
node_reviewcycle -->|"captures takeaways"| node_takeaways
node_takeaways -->|"stores learning data"| node_database
node_takeaways -.->|"generates verses"| node_openai
node_glossary -->|"assesses answers"| node_openai
node_glossary -->|"reads and writes practice"| node_database
node_takeaways -->|"feeds personal song"| node_studio
node_studio -.->|"requests song data"| node_songapi
node_songapi -->|"generates song"| node_openai
node_songapi -->|"stores song sections"| node_database
node_speaking -.->|"submits practice"| node_speechapi
node_speechapi -->|"loads review items"| node_database
node_dashboard -->|"shows progress"| node_gamification
node_gamification -->|"persists awards"| node_database
node_media -->|"fetches captions"| node_youtube

click node_auth "https://github.com/natsouzax/lexuri/blob/master/app/(auth)/register/page.tsx"
click node_catalog "https://github.com/natsouzax/lexuri/blob/master/app/(app)/feed/page.tsx"
click node_album "https://github.com/natsouzax/lexuri/blob/master/app/(app)/albums/page.tsx"
click node_lessons "https://github.com/natsouzax/lexuri/blob/master/data/featured-lessons/index.ts"
click node_player "https://github.com/natsouzax/lexuri/blob/master/components/YoutubeSyncPlayer.tsx"
click node_lessonview "https://github.com/natsouzax/lexuri/blob/master/components/LessonView.tsx"
click node_translator "https://github.com/natsouzax/lexuri/blob/master/components/FloatingTranslator.tsx"
click node_translation "https://github.com/natsouzax/lexuri/blob/master/app/api/llm/translate/route.ts"
click node_flashcards "https://github.com/natsouzax/lexuri/blob/master/app/(app)/flashcards/page.tsx"
click node_reviewcycle "https://github.com/natsouzax/lexuri/blob/master/components/review/SrsSession.tsx"
click node_srs "https://github.com/natsouzax/lexuri/blob/master/lib/srs.ts"
click node_takeaways "https://github.com/natsouzax/lexuri/blob/master/app/api/takeaways/route.ts"
click node_glossary "https://github.com/natsouzax/lexuri/blob/master/app/api/glossary-practice/route.ts"
click node_studio "https://github.com/natsouzax/lexuri/blob/master/components/music/MusicStudio.tsx"
click node_songapi "https://github.com/natsouzax/lexuri/blob/master/app/api/user-songs/route.ts"
click node_speaking "https://github.com/natsouzax/lexuri/blob/master/components/review/SpeakingReview.tsx"
click node_speechapi "https://github.com/natsouzax/lexuri/blob/master/app/api/speaking-review/%5Bid%5D/assess/route.ts"
click node_dashboard "https://github.com/natsouzax/lexuri/blob/master/app/(app)/dashboard/page.tsx"
click node_gamification "https://github.com/natsouzax/lexuri/blob/master/lib/gamification.ts"
click node_database "https://github.com/natsouzax/lexuri/blob/master/lib/supabase-server.ts"
click node_media "https://github.com/natsouzax/lexuri/blob/master/lib/media/index.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_catalog,node_album,node_lessons,node_player,node_lessonview,node_translator toneBlue
class node_flashcards,node_reviewcycle,node_srs,node_glossary,node_speaking toneAmber
class node_takeaways,node_studio,node_songapi toneMint
class node_auth,node_dashboard,node_gamification toneRose
class node_translation,node_speechapi,node_database,node_media,node_learner,node_openai,node_youtube toneIndigo
```

## Components

### Song learning

- [Song and album catalog](https://github.com/natsouzax/lexuri/blob/master/app/(app)/feed/page.tsx): `app/(app)/feed/page.tsx`
- [Album journeys](https://github.com/natsouzax/lexuri/blob/master/app/(app)/albums/page.tsx): `app/(app)/albums/page.tsx`
- [Static lesson library](https://github.com/natsouzax/lexuri/blob/master/data/featured-lessons/index.ts): `data/featured-lessons/index.ts`
- [Synced lyric player](https://github.com/natsouzax/lexuri/blob/master/components/YoutubeSyncPlayer.tsx): `components/YoutubeSyncPlayer.tsx`
- [Lesson and chunks](https://github.com/natsouzax/lexuri/blob/master/components/LessonView.tsx): `components/LessonView.tsx`
- [Floating translator](https://github.com/natsouzax/lexuri/blob/master/components/FloatingTranslator.tsx): `components/FloatingTranslator.tsx`

### Review and glossary

- [Vocabulary library](https://github.com/natsouzax/lexuri/blob/master/app/(app)/flashcards/page.tsx): `app/(app)/flashcards/page.tsx`
- [Three-day song review](https://github.com/natsouzax/lexuri/blob/master/components/review/SrsSession.tsx): `components/review/SrsSession.tsx`
- [Spaced repetition](https://github.com/natsouzax/lexuri/blob/master/lib/srs.ts): `lib/srs.ts`
- [Glossary practice](https://github.com/natsouzax/lexuri/blob/master/app/api/glossary-practice/route.ts): `app/api/glossary-practice/route.ts`
- [Speaking review](https://github.com/natsouzax/lexuri/blob/master/components/review/SpeakingReview.tsx): `components/review/SpeakingReview.tsx`

### Personal music

- [Takeaways and verses](https://github.com/natsouzax/lexuri/blob/master/app/api/takeaways/route.ts): `app/api/takeaways/route.ts`
- [Personal song studio](https://github.com/natsouzax/lexuri/blob/master/components/music/MusicStudio.tsx): `components/music/MusicStudio.tsx`
- [Personal song generation](https://github.com/natsouzax/lexuri/blob/master/app/api/user-songs/route.ts): `app/api/user-songs/route.ts`

### Progress and accounts

- [Sign in and level](https://github.com/natsouzax/lexuri/blob/master/app/(auth)/register/page.tsx): `app/(auth)/register/page.tsx`
- [Dashboard and missions](https://github.com/natsouzax/lexuri/blob/master/app/(app)/dashboard/page.tsx): `app/(app)/dashboard/page.tsx`
- [XP and leaderboard](https://github.com/natsouzax/lexuri/blob/master/lib/gamification.ts): `lib/gamification.ts`

### Runtime services

- [Translation and definition](https://github.com/natsouzax/lexuri/blob/master/app/api/llm/translate/route.ts): `app/api/llm/translate/route.ts`
- [Speech assessment](https://github.com/natsouzax/lexuri/blob/master/app/api/speaking-review/%5Bid%5D/assess/route.ts): `app/api/speaking-review/[id]/assess/route.ts`
- [Supabase data](https://github.com/natsouzax/lexuri/blob/master/lib/supabase-server.ts): `lib/supabase-server.ts`
- [Media and lyrics adapters](https://github.com/natsouzax/lexuri/blob/master/lib/media/index.ts): `lib/media/index.ts`

### Other components

- **Learner**
- **OpenAI services**
- **YouTube media**

## Connections

- Learner → Sign in and level: creates account (evidence: `README.md`)
- Sign in and level → Song and album catalog: opens songs (evidence: `README.md`)
- Song and album catalog → Static lesson library: loads lessons (evidence: `data/featured-lessons/index.ts`)
- Album journeys → Static lesson library: uses album tracks (evidence: `data/featured-lessons/index.ts`)
- Static lesson library → Synced lyric player: supplies synced lyrics (evidence: `README.md`)
- Synced lyric player → YouTube media: plays video (evidence: `README.md`)
- Synced lyric player → Lesson and chunks: shows lyrics (evidence: `README.md`)
- Lesson and chunks → Floating translator: opens translation (evidence: `README.md`)
- Floating translator → Translation and definition: requests translation (evidence: `README.md`)
- Translation and definition → OpenAI services: calls model
- Lesson and chunks → Vocabulary library: saves vocabulary (evidence: `README.md`)
- Vocabulary library → Three-day song review: starts review (evidence: `README.md`)
- Three-day song review → Spaced repetition: schedules cards (evidence: `README.md`)
- Three-day song review → Takeaways and verses: captures takeaways (evidence: `README.md`)
- Takeaways and verses → Supabase data: stores learning data (evidence: `app/api/takeaways/route.ts`)
- Takeaways and verses → OpenAI services: generates verses
- Glossary practice → OpenAI services: assesses answers (evidence: `app/api/glossary-practice/route.ts`)
- Glossary practice → Supabase data: reads and writes practice (evidence: `app/api/glossary-practice/route.ts`)
- Takeaways and verses → Personal song studio: feeds personal song (evidence: `README.md`)
- Personal song studio → Personal song generation: requests song data
- Personal song generation → OpenAI services: generates song (evidence: `app/api/user-songs/route.ts`)
- Personal song generation → Supabase data: stores song sections (evidence: `app/api/user-songs/route.ts`)
- Speaking review → Speech assessment: submits practice
- Speech assessment → Supabase data: loads review items
- Dashboard and missions → XP and leaderboard: shows progress (evidence: `app/(app)/dashboard/page.tsx`)
- XP and leaderboard → Supabase data: persists awards (evidence: `app/api/gamification/award-action/route.ts`)
- Media and lyrics adapters → YouTube media: fetches captions (evidence: `lib/media/index.ts`)