# zyrus-47/grokked architecture

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

- Interactive diagram: https://gitdiagram.com/zyrus-47/grokked
- Repository: https://github.com/zyrus-47/grokked

## Overview

Grokked is a guided coding-learning platform: a student describes an app, reviews and edits an AI-generated curriculum, then works through incremental code and explanations. Each step ends in a five-question comprehension gate; passing unlocks the next step, while grading updates concept mastery. Completion leads to a runnable showcase and mastery report. The README documents the verifier’s independent checking, spaced repetition, sandbox and ZIP export. API-to-agent and API-to-validation links are supported by indexed imports; UI request wiring is described by the README rather than shown in the sampled page excerpts.

Main entry points: [`app/api/build-step/route.ts`](https://github.com/zyrus-47/grokked/blob/main/app/api/build-step/route.ts) (Step builder), [`lib/gemini.ts`](https://github.com/zyrus-47/grokked/blob/main/lib/gemini.ts) (Gemini service), [`app/api/plan/route.ts`](https://github.com/zyrus-47/grokked/blob/main/app/api/plan/route.ts) (Curriculum planner), [`app/api/explain/route.ts`](https://github.com/zyrus-47/grokked/blob/main/app/api/explain/route.ts) (Step explainer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Learning journey"]
  node_landing["App prompt<br/>[page.tsx]"]
  node_planui["Editable plan<br/>[page.tsx]"]
  node_workspace["Code workspace<br/>[CodePane.tsx]"]
  node_agentfeed["Agent activity<br/>[AgentFeed.tsx]"]
  node_quizgate["Quiz gate<br/>[QuizCard.tsx]"]
end

subgraph group_agents["Learning agents"]
  node_planner["Curriculum planner<br/>[route.ts]"]
  node_builder["Step builder<br/>[route.ts]"]
  node_explainer["Step explainer<br/>[route.ts]"]
  node_quizgen["Quiz generator<br/>[route.ts]"]
  node_verifier["Quiz verifier<br/>[route.ts]"]
  node_grader["Mastery grader<br/>[route.ts]"]
end

subgraph group_runtime["Agent runtime"]
  node_gemini["Gemini service<br/>[gemini.ts]"]
  node_prompts["Agent instructions<br/>[agent-prompts.ts]"]
  node_schemas["Output validation<br/>[zod-schemas.ts]"]
  node_demo["Offline demo content<br/>[todo-app.ts]"]
end

subgraph group_outcomes["Progress and results"]
  node_state["Learning state<br/>[store.ts]"]
  node_reportpage["Completion page<br/>[page.tsx]"]
  node_report["Mastery and showcase<br/>[MasteryReport.tsx]"]
  node_sandbox["Sandboxed app preview<br/>[MasteryReport.tsx]"]
  node_zip["ZIP export<br/>[MasteryReport.tsx]"]
end

node_student(("Student"))
node_geminiservice["Google Gemini"]

node_student -->|"describes app"| node_landing
node_landing -->|"requests plan"| node_planner
node_planner -->|"returns plan"| node_planui
node_planui -->|"requests step"| node_builder
node_builder -->|"provides code"| node_workspace
node_builder -.->|"builds step context"| node_explainer
node_explainer -->|"provides explanations"| node_workspace
node_workspace -->|"requests questions"| node_quizgen
node_quizgen -->|"submits quiz"| node_verifier
node_verifier -->|"returns verified quiz"| node_quizgate
node_quizgate -->|"submits answers"| node_grader
node_grader -->|"updates mastery"| node_state
node_state -->|"unlocks next step"| node_planui
node_state -->|"provides progress"| node_reportpage
node_reportpage -->|"renders report"| node_report
node_report -->|"previews app"| node_sandbox
node_report -->|"exports bundle"| node_zip
node_planner -->|"calls model"| node_gemini
node_builder -->|"calls model"| node_gemini
node_explainer -->|"calls model"| node_gemini
node_quizgen -->|"calls model"| node_gemini
node_verifier -->|"calls model"| node_gemini
node_grader -->|"calls model"| node_gemini
node_gemini -->|"uses SDK"| node_geminiservice
node_planner -->|"uses instructions"| node_prompts
node_builder -->|"uses instructions"| node_prompts
node_explainer -->|"uses instructions"| node_prompts
node_quizgen -->|"uses instructions"| node_prompts
node_verifier -->|"uses instructions"| node_prompts
node_grader -->|"uses instructions"| node_prompts
node_planner -->|"validates output"| node_schemas
node_builder -->|"validates output"| node_schemas
node_explainer -->|"validates output"| node_schemas
node_quizgen -->|"validates output"| node_schemas
node_verifier -->|"validates output"| node_schemas
node_grader -->|"validates output"| node_schemas
node_planner -->|"loads demo plan"| node_demo
node_builder -->|"loads demo step"| node_demo
node_explainer -->|"loads demo summary"| node_demo
node_quizgen -->|"loads demo quiz"| node_demo

click node_landing "https://github.com/zyrus-47/grokked/blob/main/app/page.tsx"
click node_planner "https://github.com/zyrus-47/grokked/blob/main/app/api/plan/route.ts"
click node_planui "https://github.com/zyrus-47/grokked/blob/main/app/plan/page.tsx"
click node_builder "https://github.com/zyrus-47/grokked/blob/main/app/api/build-step/route.ts"
click node_explainer "https://github.com/zyrus-47/grokked/blob/main/app/api/explain/route.ts"
click node_workspace "https://github.com/zyrus-47/grokked/blob/main/components/CodePane.tsx"
click node_agentfeed "https://github.com/zyrus-47/grokked/blob/main/components/AgentFeed.tsx"
click node_quizgen "https://github.com/zyrus-47/grokked/blob/main/app/api/quiz/route.ts"
click node_quizgate "https://github.com/zyrus-47/grokked/blob/main/components/QuizCard.tsx"
click node_verifier "https://github.com/zyrus-47/grokked/blob/main/app/api/verify/route.ts"
click node_grader "https://github.com/zyrus-47/grokked/blob/main/app/api/grade/route.ts"
click node_state "https://github.com/zyrus-47/grokked/blob/main/lib/store.ts"
click node_reportpage "https://github.com/zyrus-47/grokked/blob/main/app/report/page.tsx"
click node_report "https://github.com/zyrus-47/grokked/blob/main/components/MasteryReport.tsx"
click node_gemini "https://github.com/zyrus-47/grokked/blob/main/lib/gemini.ts"
click node_prompts "https://github.com/zyrus-47/grokked/blob/main/lib/agent-prompts.ts"
click node_schemas "https://github.com/zyrus-47/grokked/blob/main/lib/zod-schemas.ts"
click node_demo "https://github.com/zyrus-47/grokked/blob/main/data/demo/todo-app.ts"
click node_sandbox "https://github.com/zyrus-47/grokked/blob/main/components/MasteryReport.tsx"
click node_zip "https://github.com/zyrus-47/grokked/blob/main/components/MasteryReport.tsx"

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_planui,node_workspace,node_agentfeed,node_quizgate toneBlue
class node_planner,node_builder,node_explainer,node_quizgen,node_verifier,node_grader toneAmber
class node_gemini,node_prompts,node_schemas,node_demo toneMint
class node_state,node_reportpage,node_report,node_sandbox,node_zip toneRose
class node_student,node_geminiservice toneIndigo
```

## Components

### Learning journey

- [App prompt](https://github.com/zyrus-47/grokked/blob/main/app/page.tsx): `app/page.tsx`
- [Editable plan](https://github.com/zyrus-47/grokked/blob/main/app/plan/page.tsx): `app/plan/page.tsx`
- [Code workspace](https://github.com/zyrus-47/grokked/blob/main/components/CodePane.tsx): `components/CodePane.tsx`
- [Agent activity](https://github.com/zyrus-47/grokked/blob/main/components/AgentFeed.tsx): `components/AgentFeed.tsx`
- [Quiz gate](https://github.com/zyrus-47/grokked/blob/main/components/QuizCard.tsx): `components/QuizCard.tsx`

### Learning agents

- [Curriculum planner](https://github.com/zyrus-47/grokked/blob/main/app/api/plan/route.ts): `app/api/plan/route.ts`
- [Step builder](https://github.com/zyrus-47/grokked/blob/main/app/api/build-step/route.ts): `app/api/build-step/route.ts`
- [Step explainer](https://github.com/zyrus-47/grokked/blob/main/app/api/explain/route.ts): `app/api/explain/route.ts`
- [Quiz generator](https://github.com/zyrus-47/grokked/blob/main/app/api/quiz/route.ts): `app/api/quiz/route.ts`
- [Quiz verifier](https://github.com/zyrus-47/grokked/blob/main/app/api/verify/route.ts): `app/api/verify/route.ts`
- [Mastery grader](https://github.com/zyrus-47/grokked/blob/main/app/api/grade/route.ts): `app/api/grade/route.ts`

### Agent runtime

- [Gemini service](https://github.com/zyrus-47/grokked/blob/main/lib/gemini.ts): `lib/gemini.ts`
- [Agent instructions](https://github.com/zyrus-47/grokked/blob/main/lib/agent-prompts.ts): `lib/agent-prompts.ts`
- [Output validation](https://github.com/zyrus-47/grokked/blob/main/lib/zod-schemas.ts): `lib/zod-schemas.ts`
- [Offline demo content](https://github.com/zyrus-47/grokked/blob/main/data/demo/todo-app.ts): `data/demo/todo-app.ts`

### Progress and results

- [Learning state](https://github.com/zyrus-47/grokked/blob/main/lib/store.ts): `lib/store.ts`
- [Completion page](https://github.com/zyrus-47/grokked/blob/main/app/report/page.tsx): `app/report/page.tsx`
- [Mastery and showcase](https://github.com/zyrus-47/grokked/blob/main/components/MasteryReport.tsx): `components/MasteryReport.tsx`
- [Sandboxed app preview](https://github.com/zyrus-47/grokked/blob/main/components/MasteryReport.tsx): `components/MasteryReport.tsx`
- [ZIP export](https://github.com/zyrus-47/grokked/blob/main/components/MasteryReport.tsx): `components/MasteryReport.tsx`

### Other components

- **Student**
- **Google Gemini**

## Connections

- Student → App prompt: describes app (evidence: `README.md`)
- App prompt → Curriculum planner: requests plan (evidence: `README.md`)
- Curriculum planner → Editable plan: returns plan (evidence: `README.md`)
- Editable plan → Step builder: requests step (evidence: `README.md`)
- Step builder → Code workspace: provides code (evidence: `README.md`)
- Step builder → Step explainer: builds step context (evidence: `README.md`)
- Step explainer → Code workspace: provides explanations (evidence: `README.md`)
- Code workspace → Quiz generator: requests questions (evidence: `README.md`)
- Quiz generator → Quiz verifier: submits quiz (evidence: `README.md`)
- Quiz verifier → Quiz gate: returns verified quiz (evidence: `README.md`)
- Quiz gate → Mastery grader: submits answers (evidence: `README.md`)
- Mastery grader → Learning state: updates mastery (evidence: `README.md`)
- Learning state → Editable plan: unlocks next step (evidence: `lib/store.ts`)
- Learning state → Completion page: provides progress (evidence: `app/report/page.tsx`)
- Completion page → Mastery and showcase: renders report (evidence: `app/report/page.tsx`)
- Mastery and showcase → Sandboxed app preview: previews app (evidence: `README.md`)
- Mastery and showcase → ZIP export: exports bundle (evidence: `README.md`)
- Curriculum planner → Gemini service: calls model (evidence: `app/api/plan/route.ts`)
- Step builder → Gemini service: calls model (evidence: `app/api/build-step/route.ts`)
- Step explainer → Gemini service: calls model (evidence: `app/api/explain/route.ts`)
- Quiz generator → Gemini service: calls model (evidence: `app/api/quiz/route.ts`)
- Quiz verifier → Gemini service: calls model (evidence: `app/api/verify/route.ts`)
- Mastery grader → Gemini service: calls model (evidence: `app/api/grade/route.ts`)
- Gemini service → Google Gemini: uses SDK (evidence: `lib/gemini.ts`)
- Curriculum planner → Agent instructions: uses instructions (evidence: `app/api/plan/route.ts`)
- Step builder → Agent instructions: uses instructions (evidence: `app/api/build-step/route.ts`)
- Step explainer → Agent instructions: uses instructions (evidence: `app/api/explain/route.ts`)
- Quiz generator → Agent instructions: uses instructions (evidence: `app/api/quiz/route.ts`)
- Quiz verifier → Agent instructions: uses instructions (evidence: `app/api/verify/route.ts`)
- Mastery grader → Agent instructions: uses instructions (evidence: `app/api/grade/route.ts`)
- Curriculum planner → Output validation: validates output (evidence: `app/api/plan/route.ts`)
- Step builder → Output validation: validates output (evidence: `app/api/build-step/route.ts`)
- Step explainer → Output validation: validates output (evidence: `app/api/explain/route.ts`)
- Quiz generator → Output validation: validates output (evidence: `app/api/quiz/route.ts`)
- Quiz verifier → Output validation: validates output (evidence: `app/api/verify/route.ts`)
- Mastery grader → Output validation: validates output (evidence: `app/api/grade/route.ts`)
- Curriculum planner → Offline demo content: loads demo plan (evidence: `app/api/plan/route.ts`)
- Step builder → Offline demo content: loads demo step (evidence: `app/api/build-step/route.ts`)
- Step explainer → Offline demo content: loads demo summary (evidence: `app/api/explain/route.ts`)
- Quiz generator → Offline demo content: loads demo quiz (evidence: `app/api/quiz/route.ts`)
