# mattpocock/ai-engineer-workshop-2026-project architecture

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

- Interactive diagram: https://gitdiagram.com/mattpocock/ai-engineer-workshop-2026-project
- Repository: https://github.com/mattpocock/ai-engineer-workshop-2026-project

## Overview

Cadence is a full-stack course platform. Learners browse courses, purchase or redeem access, then study lessons and track progress; quizzes support assessment. Instructors create and manage course content, while admins manage users, courses, and categories. SQLite/Drizzle provides persistent domain state. The route table documents the app’s route-to-screen structure, but most route/service calls were not shown in the excerpts, so those relationships are left unasserted. Optional integrations and some runtime wiring are consequently shown only as unverified where useful.

Main entry points: [`app/routes.ts`](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes.ts) (Route table), [`app/services`](https://github.com/mattpocock/ai-engineer-workshop-2026-project/tree/main/app/services) (Domain services), [`app/routes/courses.$slug.lessons.$lessonId.tsx`](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/courses.%24slug.lessons.%24lessonId.tsx) (Lesson player), [`app/components/youtube-player.tsx`](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/components/youtube-player.tsx) (YouTube player)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["App routing"]
  node_route_config["Route table<br/>[routes.ts]"]
end

subgraph group_learning["Learner experience"]
  node_course_browse["Course catalog<br/>[courses.tsx]"]
  node_course_detail["Course details<br/>[courses.$slug.tsx]"]
  node_purchase["Purchase flow"]
  node_redeem["Coupon redemption<br/>[redeem.$code.tsx]"]
  node_dashboard["Learner dashboard<br/>[dashboard.tsx]"]
  node_lesson_view["Lesson player"]
  node_youtube["YouTube player<br/>[youtube-player.tsx]"]
  node_video_api["Video tracking API"]
end

subgraph group_authoring["Course operations"]
  node_instructor_tools["Course authoring"]
  node_lesson_authoring["Lesson and quiz editing"]
  node_admin_tools["Admin management<br/>[admin.users.tsx]"]
end

subgraph group_domain["Domain services"]
  node_services["Domain services"]
  node_quiz_scoring["Quiz scoring"]
end

subgraph group_persistence["Persistence and session"]
  node_session["Session handling<br/>[session.ts]"]
  node_database[("SQLite database<br/>[index.ts]")]
  node_schema["Domain schema<br/>[schema.ts]"]
end

node_learner(("Learner"))
node_instructor(("Instructor"))
node_admin(("Administrator"))
node_youtube_service["YouTube iframe API"]

node_route_config -->|"routes to"| node_course_browse
node_route_config -->|"routes to"| node_course_detail
node_route_config -->|"routes to"| node_purchase
node_route_config -->|"routes to"| node_redeem
node_route_config -->|"routes to"| node_dashboard
node_route_config -->|"routes to"| node_lesson_view
node_route_config -->|"routes to"| node_instructor_tools
node_route_config -->|"routes to"| node_lesson_authoring
node_route_config -->|"routes to"| node_admin_tools
node_lesson_view -.->|"embeds player"| node_youtube
node_youtube -->|"loads API"| node_youtube_service
node_youtube -.->|"sends tracking"| node_video_api
node_lesson_authoring -.->|"submits answers"| node_quiz_scoring
node_course_browse -.->|"uses domain logic"| node_services
node_purchase -.->|"processes purchase"| node_services
node_redeem -.->|"validates coupon"| node_services
node_lesson_view -.->|"records progress"| node_services
node_instructor_tools -.->|"manages courses"| node_services
node_admin_tools -.->|"manages users"| node_services
node_services -.->|"reads and writes"| node_database
node_quiz_scoring -->|"scores attempts"| node_database
node_database -->|"uses schema"| node_schema
node_learner -.->|"navigates"| node_route_config
node_instructor -.->|"navigates"| node_route_config
node_admin -.->|"navigates"| node_route_config
node_lesson_view -.->|"checks identity"| node_session

click node_route_config "https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes.ts"
click node_course_browse "https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/courses.tsx"
click node_course_detail "https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/courses.%24slug.tsx"
click node_purchase "https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/courses.%24slug.purchase.tsx"
click node_redeem "https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/redeem.%24code.tsx"
click node_dashboard "https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/dashboard.tsx"
click node_lesson_view "https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/courses.%24slug.lessons.%24lessonId.tsx"
click node_youtube "https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/components/youtube-player.tsx"
click node_video_api "https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/api.video-tracking.ts"
click node_instructor_tools "https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/instructor.%24courseId.tsx"
click node_lesson_authoring "https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/instructor.%24courseId.lessons.%24lessonId.quiz.tsx"
click node_admin_tools "https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/admin.users.tsx"
click node_services "https://github.com/mattpocock/ai-engineer-workshop-2026-project/tree/main/app/services"
click node_quiz_scoring "https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/services/quizScoringService.ts"
click node_session "https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/lib/session.ts"
click node_database "https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/db/index.ts"
click node_schema "https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/db/schema.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_route_config toneBlue
class node_course_browse,node_course_detail,node_purchase,node_redeem,node_dashboard,node_lesson_view,node_youtube,node_video_api toneAmber
class node_instructor_tools,node_lesson_authoring,node_admin_tools,node_youtube_service toneMint
class node_services,node_quiz_scoring toneRose
class node_session,node_database,node_schema,node_learner,node_instructor,node_admin toneIndigo
```

## Components

### App routing

- [Route table](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes.ts): `app/routes.ts`

### Learner experience

- [Course catalog](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/courses.tsx): `app/routes/courses.tsx`
- [Course details](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/courses.%24slug.tsx): `app/routes/courses.$slug.tsx`
- [Purchase flow](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/courses.%24slug.purchase.tsx): `app/routes/courses.$slug.purchase.tsx`
- [Coupon redemption](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/redeem.%24code.tsx): `app/routes/redeem.$code.tsx`
- [Learner dashboard](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/dashboard.tsx): `app/routes/dashboard.tsx`
- [Lesson player](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/courses.%24slug.lessons.%24lessonId.tsx): `app/routes/courses.$slug.lessons.$lessonId.tsx`
- [YouTube player](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/components/youtube-player.tsx): `app/components/youtube-player.tsx`
- [Video tracking API](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/api.video-tracking.ts): `app/routes/api.video-tracking.ts`

### Course operations

- [Course authoring](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/instructor.%24courseId.tsx): `app/routes/instructor.$courseId.tsx`
- [Lesson and quiz editing](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/instructor.%24courseId.lessons.%24lessonId.quiz.tsx): `app/routes/instructor.$courseId.lessons.$lessonId.quiz.tsx`
- [Admin management](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/routes/admin.users.tsx): `app/routes/admin.users.tsx`

### Domain services

- [Domain services](https://github.com/mattpocock/ai-engineer-workshop-2026-project/tree/main/app/services): `app/services`
- [Quiz scoring](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/services/quizScoringService.ts): `app/services/quizScoringService.ts`

### Persistence and session

- [Session handling](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/lib/session.ts): `app/lib/session.ts`
- [SQLite database](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/db/index.ts): `app/db/index.ts`
- [Domain schema](https://github.com/mattpocock/ai-engineer-workshop-2026-project/blob/main/app/db/schema.ts): `app/db/schema.ts`

### Other components

- **Learner**
- **Instructor**
- **Administrator**
- **YouTube iframe API**

## Connections

- Route table → Course catalog: routes to (evidence: `app/routes.ts`)
- Route table → Course details: routes to (evidence: `app/routes.ts`)
- Route table → Purchase flow: routes to (evidence: `app/routes.ts`)
- Route table → Coupon redemption: routes to (evidence: `app/routes.ts`)
- Route table → Learner dashboard: routes to (evidence: `app/routes.ts`)
- Route table → Lesson player: routes to (evidence: `app/routes.ts`)
- Route table → Course authoring: routes to (evidence: `app/routes.ts`)
- Route table → Lesson and quiz editing: routes to (evidence: `app/routes.ts`)
- Route table → Admin management: routes to (evidence: `app/routes.ts`)
- Lesson player → YouTube player: embeds player
- YouTube player → YouTube iframe API: loads API (evidence: `app/components/youtube-player.tsx`)
- YouTube player → Video tracking API: sends tracking
- Lesson and quiz editing → Quiz scoring: submits answers
- Course catalog → Domain services: uses domain logic
- Purchase flow → Domain services: processes purchase
- Coupon redemption → Domain services: validates coupon
- Lesson player → Domain services: records progress
- Course authoring → Domain services: manages courses
- Admin management → Domain services: manages users
- Domain services → SQLite database: reads and writes
- Quiz scoring → SQLite database: scores attempts (evidence: `app/services/quizScoringService.ts`)
- SQLite database → Domain schema: uses schema (evidence: `app/db/index.ts`)
- Learner → Route table: navigates
- Instructor → Route table: navigates
- Administrator → Route table: navigates
- Lesson player → Session handling: checks identity
