# veeresh-bikkaneti/system-design-and-architecture architecture

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

- Interactive diagram: https://gitdiagram.com/veeresh-bikkaneti/system-design-and-architecture
- Repository: https://github.com/veeresh-bikkaneti/system-design-and-architecture

## Overview

System Design Mastery is a browser-based interactive course: learners browse the roadmap, open lessons, read diagrams and take quizzes, then save progress and earn badges. An optional client-side tutor answers lesson questions using retrieved course cards and on-device generation; narration supports lesson listening. Progress and quiz state persist in browser storage. Optional GitHub sign-in/sync uses the Worker. The graph follows the documented workflow and shown imports; unsampled internals are represented only at supported paths, and unverified integration links are omitted.

Main entry points: [`src/App.tsx`](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/App.tsx) (App routing), [`src/store/progress.ts`](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/store/progress.ts) (Progress state), [`src/ai/local/agent.ts`](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/ai/local/agent.ts) (Tutor agent), [`src/pages/HomePage.tsx`](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/pages/HomePage.tsx) (Course home)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Course experience"]
  node_app["App routing<br/>[App.tsx]"]
  node_home["Course home<br/>[HomePage.tsx]"]
  node_roadmap["Learning roadmap<br/>[RoadmapPage.tsx]"]
  node_lesson["Lesson reading<br/>[LessonPage.tsx]"]
  node_content["Lesson content<br/>[lessons.ts]"]
  node_diagrams["Interactive diagrams<br/>[PacketFlow.tsx]"]
  node_quiz["Lesson quizzes<br/>[Quiz.tsx]"]
end

subgraph group_progress["Progress and identity"]
  node_progressstore[("Progress state<br/>[progress.ts]")]
  node_gating["Lesson unlocking<br/>[progress-gate.ts]"]
  node_badges["Badge gallery<br/>[BadgesPage.tsx]"]
  node_auth["Sign-in and sync<br/>[AuthBar.tsx]"]
  node_worker["Auth Worker<br/>[index.ts]"]
end

subgraph group_tutor["Ben tutor"]
  node_chat["Tutor chat<br/>[QaChatPanel.tsx]"]
  node_agent["Tutor agent<br/>[agent.ts]"]
  node_cards["Course cards<br/>[cards.ts]"]
  node_retrieval["Card retrieval<br/>[retrieve.ts]"]
  node_routing["Semantic routing<br/>[router.ts]"]
  node_codec["Index codec<br/>[codec.ts]"]
  node_inference["On-device inference<br/>[inference.ts]"]
end

subgraph group_media["Lesson media"]
  node_narration["Lesson narration<br/>[LessonNarrator.tsx]"]
end

node_learner(("Learner"))
node_browserai["Browser AI engines"]

node_learner -->|"opens course"| node_app
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_roadmap
node_app -->|"routes to"| node_lesson
node_home -->|"lists lessons"| node_content
node_roadmap -->|"lists lessons"| node_content
node_lesson -->|"loads lesson"| node_content
node_app -->|"loads diagrams"| node_diagrams
node_app -->|"provides quiz"| node_quiz
node_lesson -->|"renders narration"| node_narration
node_home -->|"reads progress"| node_progressstore
node_roadmap -->|"reads progress"| node_progressstore
node_lesson -->|"records completion"| node_progressstore
node_quiz -.->|"records scores"| node_progressstore
node_home -->|"checks unlocks"| node_gating
node_roadmap -->|"checks unlocks"| node_gating
node_badges -->|"reads progress"| node_progressstore
node_auth -->|"reads progress"| node_progressstore
node_auth -->|"exchanges OAuth"| node_worker
node_learner -->|"asks question"| node_chat
node_chat -.->|"requests answer"| node_agent
node_agent -->|"uses course cards"| node_cards
node_agent -->|"retrieves context"| node_retrieval
node_inference -->|"prepares turns"| node_agent
node_inference -->|"retrieves context"| node_retrieval
node_routing -->|"builds query"| node_agent
node_routing -->|"uses card names"| node_retrieval
node_routing -->|"scores vectors"| node_codec
node_inference -.->|"runs locally"| node_browserai
node_learner -->|"listens"| node_narration

click node_app "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/App.tsx"
click node_home "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/pages/HomePage.tsx"
click node_roadmap "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/pages/RoadmapPage.tsx"
click node_lesson "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/pages/LessonPage.tsx"
click node_content "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/lib/lessons.ts"
click node_diagrams "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/components/diagrams/PacketFlow.tsx"
click node_quiz "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/components/Quiz.tsx"
click node_progressstore "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/store/progress.ts"
click node_gating "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/lib/progress-gate.ts"
click node_badges "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/pages/BadgesPage.tsx"
click node_auth "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/components/AuthBar.tsx"
click node_worker "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/worker/src/index.ts"
click node_chat "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/components/qa/QaChatPanel.tsx"
click node_agent "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/ai/local/agent.ts"
click node_cards "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/ai/local/cards.ts"
click node_retrieval "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/ai/local/retrieve.ts"
click node_routing "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/ai/local/semantic/router.ts"
click node_codec "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/ai/local/semantic/codec.ts"
click node_inference "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/ai/local/inference.ts"
click node_narration "https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/components/LessonNarrator.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_app,node_home,node_roadmap,node_lesson,node_content,node_diagrams,node_quiz,node_browserai toneBlue
class node_progressstore,node_gating,node_badges,node_auth,node_worker toneAmber
class node_chat,node_agent,node_cards,node_retrieval,node_routing,node_codec,node_inference toneMint
class node_narration toneRose
class node_learner toneIndigo
```

## Components

### Course experience

- [App routing](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/App.tsx): `src/App.tsx`
- [Course home](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/pages/HomePage.tsx): `src/pages/HomePage.tsx`
- [Learning roadmap](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/pages/RoadmapPage.tsx): `src/pages/RoadmapPage.tsx`
- [Lesson reading](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/pages/LessonPage.tsx): `src/pages/LessonPage.tsx`
- [Lesson content](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/lib/lessons.ts): `src/lib/lessons.ts`
- [Interactive diagrams](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/components/diagrams/PacketFlow.tsx): `src/components/diagrams/PacketFlow.tsx`
- [Lesson quizzes](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/components/Quiz.tsx): `src/components/Quiz.tsx`

### Progress and identity

- [Progress state](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/store/progress.ts): `src/store/progress.ts`
- [Lesson unlocking](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/lib/progress-gate.ts): `src/lib/progress-gate.ts`
- [Badge gallery](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/pages/BadgesPage.tsx): `src/pages/BadgesPage.tsx`
- [Sign-in and sync](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/components/AuthBar.tsx): `src/components/AuthBar.tsx`
- [Auth Worker](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/worker/src/index.ts): `worker/src/index.ts`

### Ben tutor

- [Tutor chat](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/components/qa/QaChatPanel.tsx): `src/components/qa/QaChatPanel.tsx`
- [Tutor agent](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/ai/local/agent.ts): `src/ai/local/agent.ts`
- [Course cards](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/ai/local/cards.ts): `src/ai/local/cards.ts`
- [Card retrieval](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/ai/local/retrieve.ts): `src/ai/local/retrieve.ts`
- [Semantic routing](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/ai/local/semantic/router.ts): `src/ai/local/semantic/router.ts`
- [Index codec](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/ai/local/semantic/codec.ts): `src/ai/local/semantic/codec.ts`
- [On-device inference](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/ai/local/inference.ts): `src/ai/local/inference.ts`

### Lesson media

- [Lesson narration](https://github.com/veeresh-bikkaneti/system-design-and-architecture/blob/main/src/components/LessonNarrator.tsx): `src/components/LessonNarrator.tsx`

### Other components

- **Learner**
- **Browser AI engines**

## Connections

- Learner → App routing: opens course (evidence: `README.md`)
- App routing → Course home: routes to (evidence: `src/App.tsx`)
- App routing → Learning roadmap: routes to (evidence: `src/App.tsx`)
- App routing → Lesson reading: routes to (evidence: `src/App.tsx`)
- Course home → Lesson content: lists lessons (evidence: `src/pages/HomePage.tsx`)
- Learning roadmap → Lesson content: lists lessons (evidence: `src/pages/RoadmapPage.tsx`)
- Lesson reading → Lesson content: loads lesson (evidence: `src/pages/LessonPage.tsx`)
- App routing → Interactive diagrams: loads diagrams (evidence: `src/App.tsx`)
- App routing → Lesson quizzes: provides quiz (evidence: `src/App.tsx`)
- Lesson reading → Lesson narration: renders narration (evidence: `src/pages/LessonPage.tsx`)
- Course home → Progress state: reads progress (evidence: `src/pages/HomePage.tsx`)
- Learning roadmap → Progress state: reads progress (evidence: `src/pages/RoadmapPage.tsx`)
- Lesson reading → Progress state: records completion (evidence: `src/pages/LessonPage.tsx`)
- Lesson quizzes → Progress state: records scores
- Course home → Lesson unlocking: checks unlocks (evidence: `src/pages/HomePage.tsx`)
- Learning roadmap → Lesson unlocking: checks unlocks (evidence: `src/pages/RoadmapPage.tsx`)
- Badge gallery → Progress state: reads progress (evidence: `src/pages/BadgesPage.tsx`)
- Sign-in and sync → Progress state: reads progress (evidence: `src/components/AuthBar.tsx`)
- Sign-in and sync → Auth Worker: exchanges OAuth (evidence: `src/components/AuthBar.tsx`)
- Learner → Tutor chat: asks question (evidence: `README.md`)
- Tutor chat → Tutor agent: requests answer
- Tutor agent → Course cards: uses course cards (evidence: `src/ai/local/agent.ts`)
- Tutor agent → Card retrieval: retrieves context (evidence: `src/ai/local/agent.ts`)
- On-device inference → Tutor agent: prepares turns (evidence: `src/ai/local/inference.ts`)
- On-device inference → Card retrieval: retrieves context (evidence: `src/ai/local/inference.ts`)
- Semantic routing → Tutor agent: builds query (evidence: `src/ai/local/semantic/router.ts`)
- Semantic routing → Card retrieval: uses card names (evidence: `src/ai/local/semantic/router.ts`)
- Semantic routing → Index codec: scores vectors (evidence: `src/ai/local/semantic/router.ts`)
- On-device inference → Browser AI engines: runs locally (evidence: `README.md`)
- Learner → Lesson narration: listens (evidence: `README.md`)