# kathir-23/sql-tutorial architecture

> Architecture diagram of the GitHub repository kathir-23/sql-tutorial, 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/kathir-23/sql-tutorial
- Repository: https://github.com/kathir-23/sql-tutorial

## Overview

SQL Mastery is a browser-based SQL learning platform. Learners follow a curriculum of lessons, write and run queries against seeded SQLite practice databases, and receive immediate results; optional branches add AI tutoring, guided projects, mixed review, and progress tracking. The graph reflects the documented capabilities and the sampled call sites. Lesson rendering, project-step execution, and several supporting routes are represented at their enclosing paths because their source was not sampled.

Main entry points: [`components/ChallengeBlock.tsx`](https://github.com/kathir-23/sql-tutorial/blob/main/components/ChallengeBlock.tsx) (SQL challenge), [`app/playground/page.tsx`](https://github.com/kathir-23/sql-tutorial/blob/main/app/playground/page.tsx) (Playground), [`app/review/page.tsx`](https://github.com/kathir-23/sql-tutorial/blob/main/app/review/page.tsx) (Mixed review), [`app/api/ai/route.ts`](https://github.com/kathir-23/sql-tutorial/blob/main/app/api/ai/route.ts) (Tutor API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Lessons and practice"]
  node_home["Home terminal<br/>[page.tsx]"]
  node_curriculum["Curriculum<br/>[page.tsx]"]
  node_lesson["Lesson<br/>[page.tsx]"]
  node_lessonsdata["Lesson content<br/>[lessons.ts]"]
end

subgraph group_query["SQL runtime"]
  node_challenge["SQL challenge<br/>[ChallengeBlock.tsx]"]
  node_playground["Playground<br/>[page.tsx]"]
  node_queryengine["SQLite engine<br/>[db.ts]"]
  node_databases["Practice databases<br/>[databases.ts]"]
  node_results["Query results<br/>[ResultsTable.tsx]"]
  node_editor["SQL editor<br/>[SQLEditor.tsx]"]
  node_schema["Schema viewer<br/>[SchemaViewer.tsx]"]
end

subgraph group_guidance["Learning support"]
  node_glossary["Glossary<br/>[page.tsx]"]
end

subgraph group_progress["Progress and projects"]
  node_projects["Guided projects<br/>[page.tsx]"]
  node_projectdata["Project definitions<br/>[projects.ts]"]
  node_projectstate[("Project progress")]
  node_review["Mixed review<br/>[page.tsx]"]
  node_reviewbuilder["Review set builder<br/>[review.ts]"]
  node_progressstate[("Lesson progress<br/>[progress.ts]")]
  node_stats["Progress stats<br/>[page.tsx]"]
end

subgraph group_tutor["AI tutoring"]
  node_tutorui["AI tutor<br/>[AITutor.tsx]"]
  node_aiapi["Tutor API<br/>[route.ts]"]
  node_ratelimit["Rate limiter<br/>[rate-limit.ts]"]
  node_schemahelp["Schema descriptions<br/>[databases.ts]"]
end

node_learner(("Learner"))
node_gemini["Google Gemini"]

node_learner -->|"opens"| node_home
node_home -->|"navigates"| node_curriculum
node_curriculum -->|"opens lesson"| node_lesson
node_lesson -->|"reads content"| node_lessonsdata
node_lesson -->|"renders practice"| node_challenge
node_challenge -->|"accepts query"| node_editor
node_challenge -->|"runs query"| node_queryengine
node_queryengine -->|"loads seed SQL"| node_databases
node_challenge -->|"shows output"| node_results
node_challenge -->|"records completion"| node_progressstate
node_learner -->|"opens"| node_playground
node_playground -->|"runs query"| node_queryengine
node_playground -->|"selects database"| node_databases
node_playground -->|"accepts query"| node_editor
node_playground -->|"shows schema"| node_schema
node_playground -->|"shows output"| node_results
node_learner -->|"looks up terms"| node_glossary
node_learner -->|"opens"| node_projects
node_projects -->|"reads projects"| node_projectdata
node_projects -->|"reads progress"| node_projectstate
node_learner -->|"starts review"| node_review
node_review -->|"reads completed lessons"| node_progressstate
node_review -->|"builds review set"| node_reviewbuilder
node_reviewbuilder -->|"selects challenges"| node_lessonsdata
node_review -->|"runs practice"| node_queryengine
node_review -->|"loads practice data"| node_databases
node_review -->|"marks reviewed"| node_progressstate
node_learner -->|"checks progress"| node_stats
node_stats -->|"reads metrics"| node_progressstate
node_stats -->|"reads project metrics"| node_projectstate
node_challenge -->|"requests help"| node_tutorui
node_tutorui -->|"sends context"| node_aiapi
node_aiapi -->|"checks limit"| node_ratelimit
node_aiapi -->|"reads schema"| node_schemahelp
node_aiapi -.->|"requests response"| node_gemini
node_gemini -.->|"streams answer"| node_aiapi
node_aiapi -->|"returns answer"| node_tutorui

click node_home "https://github.com/kathir-23/sql-tutorial/blob/main/app/page.tsx"
click node_curriculum "https://github.com/kathir-23/sql-tutorial/blob/main/app/learn/page.tsx"
click node_lesson "https://github.com/kathir-23/sql-tutorial/blob/main/app/learn/%5BmoduleSlug%5D/%5BlessonSlug%5D/page.tsx"
click node_challenge "https://github.com/kathir-23/sql-tutorial/blob/main/components/ChallengeBlock.tsx"
click node_playground "https://github.com/kathir-23/sql-tutorial/blob/main/app/playground/page.tsx"
click node_queryengine "https://github.com/kathir-23/sql-tutorial/blob/main/lib/db.ts"
click node_databases "https://github.com/kathir-23/sql-tutorial/blob/main/lib/databases.ts"
click node_results "https://github.com/kathir-23/sql-tutorial/blob/main/components/ResultsTable.tsx"
click node_editor "https://github.com/kathir-23/sql-tutorial/blob/main/components/SQLEditor.tsx"
click node_schema "https://github.com/kathir-23/sql-tutorial/blob/main/components/SchemaViewer.tsx"
click node_lessonsdata "https://github.com/kathir-23/sql-tutorial/blob/main/lib/lessons.ts"
click node_glossary "https://github.com/kathir-23/sql-tutorial/blob/main/app/glossary/page.tsx"
click node_projects "https://github.com/kathir-23/sql-tutorial/blob/main/app/projects/%5Bslug%5D/page.tsx"
click node_projectdata "https://github.com/kathir-23/sql-tutorial/blob/main/lib/projects.ts"
click node_projectstate "https://github.com/kathir-23/sql-tutorial/blob/main/lib/project-progress.ts"
click node_review "https://github.com/kathir-23/sql-tutorial/blob/main/app/review/page.tsx"
click node_reviewbuilder "https://github.com/kathir-23/sql-tutorial/blob/main/lib/review.ts"
click node_progressstate "https://github.com/kathir-23/sql-tutorial/blob/main/lib/progress.ts"
click node_stats "https://github.com/kathir-23/sql-tutorial/blob/main/app/stats/page.tsx"
click node_tutorui "https://github.com/kathir-23/sql-tutorial/blob/main/components/AITutor.tsx"
click node_aiapi "https://github.com/kathir-23/sql-tutorial/blob/main/app/api/ai/route.ts"
click node_ratelimit "https://github.com/kathir-23/sql-tutorial/blob/main/lib/rate-limit.ts"
click node_schemahelp "https://github.com/kathir-23/sql-tutorial/blob/main/lib/databases.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_home,node_curriculum,node_lesson,node_lessonsdata toneBlue
class node_challenge,node_playground,node_queryengine,node_databases,node_results,node_editor,node_schema toneAmber
class node_glossary toneMint
class node_projects,node_projectdata,node_projectstate,node_review,node_reviewbuilder,node_progressstate,node_stats toneRose
class node_tutorui,node_aiapi,node_ratelimit,node_schemahelp,node_learner,node_gemini toneIndigo
```

## Components

### Lessons and practice

- [Home terminal](https://github.com/kathir-23/sql-tutorial/blob/main/app/page.tsx): `app/page.tsx`
- [Curriculum](https://github.com/kathir-23/sql-tutorial/blob/main/app/learn/page.tsx): `app/learn/page.tsx`
- [Lesson](https://github.com/kathir-23/sql-tutorial/blob/main/app/learn/%5BmoduleSlug%5D/%5BlessonSlug%5D/page.tsx): `app/learn/[moduleSlug]/[lessonSlug]/page.tsx`
- [Lesson content](https://github.com/kathir-23/sql-tutorial/blob/main/lib/lessons.ts): `lib/lessons.ts`

### SQL runtime

- [SQL challenge](https://github.com/kathir-23/sql-tutorial/blob/main/components/ChallengeBlock.tsx): `components/ChallengeBlock.tsx`
- [Playground](https://github.com/kathir-23/sql-tutorial/blob/main/app/playground/page.tsx): `app/playground/page.tsx`
- [SQLite engine](https://github.com/kathir-23/sql-tutorial/blob/main/lib/db.ts): `lib/db.ts`
- [Practice databases](https://github.com/kathir-23/sql-tutorial/blob/main/lib/databases.ts): `lib/databases.ts`
- [Query results](https://github.com/kathir-23/sql-tutorial/blob/main/components/ResultsTable.tsx): `components/ResultsTable.tsx`
- [SQL editor](https://github.com/kathir-23/sql-tutorial/blob/main/components/SQLEditor.tsx): `components/SQLEditor.tsx`
- [Schema viewer](https://github.com/kathir-23/sql-tutorial/blob/main/components/SchemaViewer.tsx): `components/SchemaViewer.tsx`

### Learning support

- [Glossary](https://github.com/kathir-23/sql-tutorial/blob/main/app/glossary/page.tsx): `app/glossary/page.tsx`

### Progress and projects

- [Guided projects](https://github.com/kathir-23/sql-tutorial/blob/main/app/projects/%5Bslug%5D/page.tsx): `app/projects/[slug]/page.tsx`
- [Project definitions](https://github.com/kathir-23/sql-tutorial/blob/main/lib/projects.ts): `lib/projects.ts`
- [Project progress](https://github.com/kathir-23/sql-tutorial/blob/main/lib/project-progress.ts): `lib/project-progress.ts`
- [Mixed review](https://github.com/kathir-23/sql-tutorial/blob/main/app/review/page.tsx): `app/review/page.tsx`
- [Review set builder](https://github.com/kathir-23/sql-tutorial/blob/main/lib/review.ts): `lib/review.ts`
- [Lesson progress](https://github.com/kathir-23/sql-tutorial/blob/main/lib/progress.ts): `lib/progress.ts`
- [Progress stats](https://github.com/kathir-23/sql-tutorial/blob/main/app/stats/page.tsx): `app/stats/page.tsx`

### AI tutoring

- [AI tutor](https://github.com/kathir-23/sql-tutorial/blob/main/components/AITutor.tsx): `components/AITutor.tsx`
- [Tutor API](https://github.com/kathir-23/sql-tutorial/blob/main/app/api/ai/route.ts): `app/api/ai/route.ts`
- [Rate limiter](https://github.com/kathir-23/sql-tutorial/blob/main/lib/rate-limit.ts): `lib/rate-limit.ts`
- [Schema descriptions](https://github.com/kathir-23/sql-tutorial/blob/main/lib/databases.ts): `lib/databases.ts`

### Other components

- **Learner**
- **Google Gemini**

## Connections

- Learner → Home terminal: opens
- Home terminal → Curriculum: navigates
- Curriculum → Lesson: opens lesson
- Lesson → Lesson content: reads content
- Lesson → SQL challenge: renders practice
- SQL challenge → SQL editor: accepts query
- SQL challenge → SQLite engine: runs query
- SQLite engine → Practice databases: loads seed SQL
- SQL challenge → Query results: shows output
- SQL challenge → Lesson progress: records completion
- Learner → Playground: opens
- Playground → SQLite engine: runs query
- Playground → Practice databases: selects database
- Playground → SQL editor: accepts query
- Playground → Schema viewer: shows schema
- Playground → Query results: shows output
- Learner → Glossary: looks up terms
- Learner → Guided projects: opens
- Guided projects → Project definitions: reads projects
- Guided projects → Project progress: reads progress
- Learner → Mixed review: starts review
- Mixed review → Lesson progress: reads completed lessons
- Mixed review → Review set builder: builds review set
- Review set builder → Lesson content: selects challenges
- Mixed review → SQLite engine: runs practice
- Mixed review → Practice databases: loads practice data
- Mixed review → Lesson progress: marks reviewed
- Learner → Progress stats: checks progress
- Progress stats → Lesson progress: reads metrics
- Progress stats → Project progress: reads project metrics
- SQL challenge → AI tutor: requests help
- AI tutor → Tutor API: sends context
- Tutor API → Rate limiter: checks limit
- Tutor API → Schema descriptions: reads schema
- Tutor API → Google Gemini: requests response
- Google Gemini → Tutor API: streams answer
- Tutor API → AI tutor: returns answer