# ngoquangphuc29306/study-toeic architecture

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

- Interactive diagram: https://gitdiagram.com/ngoquangphuc29306/study-toeic
- Repository: https://github.com/ngoquangphuc29306/study-toeic
- Video tour (about a minute): https://gitdiagram.com/ngoquangphuc29306/study-toeic/video

## Overview

EasyTOEIC is a personal TOEIC vocabulary and exam-practice application. Users authenticate, enter the protected app, manage vocabulary collections, and study through flashcards, quizzes, pronunciation, SRS, or synonym sessions; the app also exposes TOEIC test-taking, review, media, and learning tools. The README documents the vocabulary workflow and Supabase’s role; TOEIC modules are evident from the tree, but most of their internal wiring was not sampled, so those links are kept conservative.

Main entry points: [`app/app/page.tsx`](https://github.com/ngoquangphuc29306/study-toeic/blob/main/app/app/page.tsx) (Protected App), [`lib/supabase/server.ts`](https://github.com/ngoquangphuc29306/study-toeic/blob/main/lib/supabase/server.ts) (Supabase), [`components/FlashcardMode.tsx`](https://github.com/ngoquangphuc29306/study-toeic/blob/main/components/FlashcardMode.tsx) (Flashcard Modes), [`app/api/toeic-tools/lookup/route.ts`](https://github.com/ngoquangphuc29306/study-toeic/blob/main/app/api/toeic-tools/lookup/route.ts) (Dictionary Lookup API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App and Auth"]
  node_landing["Landing Page<br/>[page.tsx]"]
  node_auth["Auth Pages<br/>[page.tsx]"]
  node_auth_callback["Auth Callback<br/>[route.ts]"]
  node_app_route["Protected App<br/>[page.tsx]"]
end

subgraph group_vocabulary["Vocabulary Learning"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_vocab_manager["Vocabulary Manager<br/>[VocabManager.tsx]"]
  node_flashcards["Flashcard Modes<br/>[FlashcardMode.tsx]"]
  node_quiz["Quiz Mode<br/>[QuizMode.tsx]"]
  node_synonym["Synonym Practice"]
  node_reminder["Review Reminder"]
end

subgraph group_toeic["TOEIC Practice"]
  node_toeic_catalog["Test Catalog"]
  node_toeic_attempt["Attempt Workspace"]
  node_toeic_history["Attempt History"]
  node_toeic_learning["Learning Tools"]
  node_toeic_dictionary_route["Dictionary Lookup API<br/>[route.ts]"]
  node_toeic_dictionary["Dictionary Provider"]
  node_toeic_media_route["Media Signing API<br/>[route.ts]"]
  node_toeic_media["Media Signing"]
end

subgraph group_services["Application Services"]
  node_vocab_service["Vocabulary Services"]
  node_app_data["App Data Service<br/>[appDataService.ts]"]
end

subgraph group_state["Persistence and Providers"]
  node_session_state[("Study Session State<br/>[storage.ts]")]
  node_supabase[("Supabase<br/>[server.ts]")]
  node_browser_storage[("Browser Storage")]
  node_rating_rpc["Rating RPC"]
end

node_learner(("Learner"))

node_learner -->|"opens"| node_landing
node_learner -->|"signs in"| node_auth
node_auth -->|"completes auth"| node_auth_callback
node_auth_callback -->|"exchanges code"| node_supabase
node_learner -->|"enters"| node_app_route
node_app_route -->|"shows"| node_dashboard
node_app_route -->|"shows"| node_vocab_manager
node_vocab_manager -->|"manages vocabulary"| node_vocab_service
node_app_route -->|"starts study"| node_flashcards
node_app_route -->|"starts quiz"| node_quiz
node_app_route -->|"starts practice"| node_synonym
node_synonym -->|"reports completion"| node_app_route
node_app_route -->|"checks due reviews"| node_reminder
node_reminder -->|"reads and writes snooze"| node_browser_storage
node_flashcards -->|"persists session"| node_session_state
node_flashcards -->|"submits rating"| node_rating_rpc
node_rating_rpc -->|"schedules atomically"| node_supabase
node_app_route -->|"offers practice"| node_toeic_catalog
node_toeic_catalog -->|"selects test"| node_toeic_attempt
node_toeic_attempt -->|"reviews attempts"| node_toeic_history
node_toeic_dictionary_route -->|"checks user"| node_supabase
node_toeic_dictionary_route -->|"looks up term"| node_toeic_dictionary
node_toeic_media_route -->|"checks user"| node_supabase
node_toeic_media_route -->|"signs paths"| node_toeic_media

click node_landing "https://github.com/ngoquangphuc29306/study-toeic/blob/main/app/page.tsx"
click node_auth "https://github.com/ngoquangphuc29306/study-toeic/blob/main/app/login/page.tsx"
click node_auth_callback "https://github.com/ngoquangphuc29306/study-toeic/blob/main/app/auth/callback/route.ts"
click node_app_route "https://github.com/ngoquangphuc29306/study-toeic/blob/main/app/app/page.tsx"
click node_dashboard "https://github.com/ngoquangphuc29306/study-toeic/blob/main/components/Dashboard.tsx"
click node_vocab_manager "https://github.com/ngoquangphuc29306/study-toeic/blob/main/components/VocabManager.tsx"
click node_flashcards "https://github.com/ngoquangphuc29306/study-toeic/blob/main/components/FlashcardMode.tsx"
click node_quiz "https://github.com/ngoquangphuc29306/study-toeic/blob/main/components/QuizMode.tsx"
click node_synonym "https://github.com/ngoquangphuc29306/study-toeic/blob/main/features/synonym-practice/hooks/useSynonymPracticeSession.ts"
click node_reminder "https://github.com/ngoquangphuc29306/study-toeic/blob/main/features/review-reminder/hooks/useReviewReminder.ts"
click node_session_state "https://github.com/ngoquangphuc29306/study-toeic/blob/main/lib/session/storage.ts"
click node_toeic_catalog "https://github.com/ngoquangphuc29306/study-toeic/blob/main/features/toeic-tests/components/ToeicTestCatalogPage.tsx"
click node_toeic_attempt "https://github.com/ngoquangphuc29306/study-toeic/blob/main/features/toeic-tests/components/ToeicAttemptWorkspace.tsx"
click node_toeic_history "https://github.com/ngoquangphuc29306/study-toeic/blob/main/features/toeic-tests/components/ToeicAttemptHistoryPage.tsx"
click node_toeic_learning "https://github.com/ngoquangphuc29306/study-toeic/blob/main/features/toeic-tests/services/toeicLearningService.ts"
click node_toeic_dictionary_route "https://github.com/ngoquangphuc29306/study-toeic/blob/main/app/api/toeic-tools/lookup/route.ts"
click node_toeic_dictionary "https://github.com/ngoquangphuc29306/study-toeic/blob/main/features/toeic-tests/server/toeicDictionaryService.ts"
click node_toeic_media_route "https://github.com/ngoquangphuc29306/study-toeic/blob/main/app/api/toeic-tests/%5BtestId%5D/media/route.ts"
click node_toeic_media "https://github.com/ngoquangphuc29306/study-toeic/blob/main/features/toeic-tests/server/toeicMediaService.ts"
click node_vocab_service "https://github.com/ngoquangphuc29306/study-toeic/blob/main/services/vocabularyService.ts"
click node_app_data "https://github.com/ngoquangphuc29306/study-toeic/blob/main/services/appDataService.ts"
click node_supabase "https://github.com/ngoquangphuc29306/study-toeic/blob/main/lib/supabase/server.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_landing,node_auth,node_auth_callback,node_app_route toneBlue
class node_dashboard,node_vocab_manager,node_flashcards,node_quiz,node_synonym,node_reminder toneAmber
class node_toeic_catalog,node_toeic_attempt,node_toeic_history,node_toeic_learning,node_toeic_dictionary_route,node_toeic_dictionary,node_toeic_media_route,node_toeic_media toneMint
class node_vocab_service,node_app_data toneRose
class node_session_state,node_supabase,node_browser_storage,node_rating_rpc,node_learner toneIndigo
```

## Components

### App and Auth

- [Landing Page](https://github.com/ngoquangphuc29306/study-toeic/blob/main/app/page.tsx): `app/page.tsx`
- [Auth Pages](https://github.com/ngoquangphuc29306/study-toeic/blob/main/app/login/page.tsx): `app/login/page.tsx`
- [Auth Callback](https://github.com/ngoquangphuc29306/study-toeic/blob/main/app/auth/callback/route.ts): `app/auth/callback/route.ts`
- [Protected App](https://github.com/ngoquangphuc29306/study-toeic/blob/main/app/app/page.tsx): `app/app/page.tsx`

### Vocabulary Learning

- [Dashboard](https://github.com/ngoquangphuc29306/study-toeic/blob/main/components/Dashboard.tsx): `components/Dashboard.tsx`
- [Vocabulary Manager](https://github.com/ngoquangphuc29306/study-toeic/blob/main/components/VocabManager.tsx): `components/VocabManager.tsx`
- [Flashcard Modes](https://github.com/ngoquangphuc29306/study-toeic/blob/main/components/FlashcardMode.tsx): `components/FlashcardMode.tsx`
- [Quiz Mode](https://github.com/ngoquangphuc29306/study-toeic/blob/main/components/QuizMode.tsx): `components/QuizMode.tsx`
- [Synonym Practice](https://github.com/ngoquangphuc29306/study-toeic/blob/main/features/synonym-practice/hooks/useSynonymPracticeSession.ts): `features/synonym-practice/hooks/useSynonymPracticeSession.ts`
- [Review Reminder](https://github.com/ngoquangphuc29306/study-toeic/blob/main/features/review-reminder/hooks/useReviewReminder.ts): `features/review-reminder/hooks/useReviewReminder.ts`

### TOEIC Practice

- [Test Catalog](https://github.com/ngoquangphuc29306/study-toeic/blob/main/features/toeic-tests/components/ToeicTestCatalogPage.tsx): `features/toeic-tests/components/ToeicTestCatalogPage.tsx`
- [Attempt Workspace](https://github.com/ngoquangphuc29306/study-toeic/blob/main/features/toeic-tests/components/ToeicAttemptWorkspace.tsx): `features/toeic-tests/components/ToeicAttemptWorkspace.tsx`
- [Attempt History](https://github.com/ngoquangphuc29306/study-toeic/blob/main/features/toeic-tests/components/ToeicAttemptHistoryPage.tsx): `features/toeic-tests/components/ToeicAttemptHistoryPage.tsx`
- [Learning Tools](https://github.com/ngoquangphuc29306/study-toeic/blob/main/features/toeic-tests/services/toeicLearningService.ts): `features/toeic-tests/services/toeicLearningService.ts`
- [Dictionary Lookup API](https://github.com/ngoquangphuc29306/study-toeic/blob/main/app/api/toeic-tools/lookup/route.ts): `app/api/toeic-tools/lookup/route.ts`
- [Dictionary Provider](https://github.com/ngoquangphuc29306/study-toeic/blob/main/features/toeic-tests/server/toeicDictionaryService.ts): `features/toeic-tests/server/toeicDictionaryService.ts`
- [Media Signing API](https://github.com/ngoquangphuc29306/study-toeic/blob/main/app/api/toeic-tests/%5BtestId%5D/media/route.ts): `app/api/toeic-tests/[testId]/media/route.ts`
- [Media Signing](https://github.com/ngoquangphuc29306/study-toeic/blob/main/features/toeic-tests/server/toeicMediaService.ts): `features/toeic-tests/server/toeicMediaService.ts`

### Application Services

- [Vocabulary Services](https://github.com/ngoquangphuc29306/study-toeic/blob/main/services/vocabularyService.ts): `services/vocabularyService.ts`
- [App Data Service](https://github.com/ngoquangphuc29306/study-toeic/blob/main/services/appDataService.ts): `services/appDataService.ts`

### Persistence and Providers

- [Study Session State](https://github.com/ngoquangphuc29306/study-toeic/blob/main/lib/session/storage.ts): `lib/session/storage.ts`
- [Supabase](https://github.com/ngoquangphuc29306/study-toeic/blob/main/lib/supabase/server.ts): `lib/supabase/server.ts`
- **Browser Storage**
- **Rating RPC**

### Other components

- **Learner**

## Connections

- Learner → Landing Page: opens
- Learner → Auth Pages: signs in
- Auth Pages → Auth Callback: completes auth
- Auth Callback → Supabase: exchanges code
- Learner → Protected App: enters
- Protected App → Dashboard: shows
- Protected App → Vocabulary Manager: shows
- Vocabulary Manager → Vocabulary Services: manages vocabulary
- Protected App → Flashcard Modes: starts study
- Protected App → Quiz Mode: starts quiz
- Protected App → Synonym Practice: starts practice
- Synonym Practice → Protected App: reports completion
- Protected App → Review Reminder: checks due reviews
- Review Reminder → Browser Storage: reads and writes snooze
- Flashcard Modes → Study Session State: persists session
- Flashcard Modes → Rating RPC: submits rating
- Rating RPC → Supabase: schedules atomically
- Protected App → Test Catalog: offers practice
- Test Catalog → Attempt Workspace: selects test
- Attempt Workspace → Attempt History: reviews attempts
- Dictionary Lookup API → Supabase: checks user
- Dictionary Lookup API → Dictionary Provider: looks up term
- Media Signing API → Supabase: checks user
- Media Signing API → Media Signing: signs paths