# dylankatchen/knowgap-backend architecture

> Architecture diagram of the GitHub repository dylankatchen/knowgap-backend, 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/dylankatchen/knowgap-backend
- Repository: https://github.com/dylankatchen/knowgap-backend

## Overview

KnowGap is a Quart-based learning platform that connects Canvas course and quiz data to student risk insights and targeted video recommendations. Its principal flow brings course and submission data into backend services, analyzes performance, and presents recommendations and analytics through student and instructor endpoints. Separate capabilities include skills and mastery tracking, badges, progress, and mental-health support videos. The graph reflects README-described capabilities and relationships visible in excerpts or the source index; unsampled implementation details and some runtime wiring are not asserted.

Main entry points: [`app.py`](https://github.com/dylankatchen/knowgap-backend/blob/main/app.py) (Quart application), [`services/achieveup_service.py`](https://github.com/dylankatchen/knowgap-backend/blob/main/services/achieveup_service.py) (Learning analytics core), [`services/video_service.py`](https://github.com/dylankatchen/knowgap-backend/blob/main/services/video_service.py) (Video recommendations), [`services/course_service.py`](https://github.com/dylankatchen/knowgap-backend/blob/main/services/course_service.py) (Course and quiz data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_app["Quart application<br/>[app.py]"]
  node_auth_routes["Authentication routes<br/>[auth_routes.py]"]
  node_auth_service["Authentication service"]
  node_instructor_routes["Instructor routes"]
  node_achieveup_routes["AchieveUp routes"]
end

subgraph group_canvas["Canvas and courses"]
  node_canvas["Canvas LMS"]
  node_canvas_routes["Canvas routes<br/>[canvas_routes.py]"]
  node_canvas_service["Canvas integration"]
  node_course_routes["Course routes<br/>[course_routes.py]"]
  node_course_service["Course and quiz data<br/>[course_service.py]"]
  node_submissions["Submission processing"]
end

subgraph group_learning["Learning insights"]
  node_achieveup_service["Learning analytics core"]
  node_analytics["Risk analytics"]
  node_skill["Skill mastery<br/>[skill_service.py]"]
  node_progress["Progress tracking"]
  node_badges["Badges<br/>[badge_service.py]"]
end

subgraph group_recommend["Recommendations"]
  node_video_routes["Video routes<br/>[video_routes.py]"]
  node_video_service["Video recommendations<br/>[video_service.py]"]
  node_ai["Core topic generation<br/>[ai_utils.py]"]
  node_youtube["Video search and metadata<br/>[youtube_utils.py]"]
  node_support["Risk-level support videos<br/>[support_service.py]"]
end

subgraph group_platform["Shared platform"]
  node_mongo[("MongoDB")]
  node_config["Application configuration<br/>[config.py]"]
  node_encryption["Token encryption"]
end

node_student(("Student"))
node_instructor(("Instructor"))

node_student -->|"uses"| node_app
node_instructor -->|"uses"| node_app
node_app -->|"registers"| node_auth_routes
node_app -->|"registers"| node_canvas_routes
node_app -->|"registers"| node_achieveup_routes
node_app -->|"registers"| node_instructor_routes
node_app -->|"registers"| node_course_routes
node_app -->|"registers"| node_video_routes
node_auth_routes -->|"uses"| node_auth_service
node_canvas_routes -->|"uses"| node_canvas_service
node_course_routes -->|"uses"| node_course_service
node_course_routes -->|"uses"| node_canvas_service
node_instructor_routes -->|"verifies"| node_auth_service
node_instructor_routes -->|"requests insights"| node_achieveup_service
node_instructor_routes -->|"requests analytics"| node_analytics
node_achieveup_routes -->|"requests learning operations"| node_achieveup_service
node_course_service -->|"fetches course data"| node_canvas
node_submissions -->|"uses Canvas integration"| node_canvas_service
node_submissions -->|"stores submissions"| node_mongo
node_course_service -->|"reads and writes"| node_mongo
node_course_service -.->|"refreshes results"| node_submissions
node_achieveup_service -->|"verifies users"| node_auth_service
node_achieveup_service -->|"uses Canvas integration"| node_canvas_service
node_achieveup_service -->|"reads and writes"| node_mongo
node_analytics -->|"uses learning data"| node_achieveup_service
node_analytics -->|"reads and writes"| node_mongo
node_skill -->|"reads and writes"| node_mongo
node_progress -->|"reads and writes"| node_mongo
node_badges -->|"reads and writes"| node_mongo
node_video_routes -->|"requests recommendations"| node_video_service
node_video_service -->|"generates topics"| node_ai
node_video_service -->|"finds videos"| node_youtube
node_video_service -->|"caches video data"| node_mongo
node_video_service -->|"uses course data"| node_course_service
node_support -.->|"reads and writes"| node_mongo
node_auth_service -->|"decrypts Canvas tokens"| node_encryption
node_app -.->|"configures runtime"| node_config

click node_app "https://github.com/dylankatchen/knowgap-backend/blob/main/app.py"
click node_auth_routes "https://github.com/dylankatchen/knowgap-backend/blob/main/routes/auth_routes.py"
click node_auth_service "https://github.com/dylankatchen/knowgap-backend/blob/main/services/achieveup_auth_service.py"
click node_instructor_routes "https://github.com/dylankatchen/knowgap-backend/blob/main/routes/instructor_routes.py"
click node_achieveup_routes "https://github.com/dylankatchen/knowgap-backend/blob/main/routes/achieveup_routes.py"
click node_canvas_routes "https://github.com/dylankatchen/knowgap-backend/blob/main/routes/canvas_routes.py"
click node_canvas_service "https://github.com/dylankatchen/knowgap-backend/blob/main/services/achieveup_canvas_service.py"
click node_course_routes "https://github.com/dylankatchen/knowgap-backend/blob/main/routes/course_routes.py"
click node_course_service "https://github.com/dylankatchen/knowgap-backend/blob/main/services/course_service.py"
click node_submissions "https://github.com/dylankatchen/knowgap-backend/blob/main/services/canvas_submissions_service.py"
click node_achieveup_service "https://github.com/dylankatchen/knowgap-backend/blob/main/services/achieveup_service.py"
click node_analytics "https://github.com/dylankatchen/knowgap-backend/blob/main/services/analytics_service.py"
click node_skill "https://github.com/dylankatchen/knowgap-backend/blob/main/services/skill_service.py"
click node_progress "https://github.com/dylankatchen/knowgap-backend/blob/main/services/progress_service.py"
click node_badges "https://github.com/dylankatchen/knowgap-backend/blob/main/services/badge_service.py"
click node_video_routes "https://github.com/dylankatchen/knowgap-backend/blob/main/routes/video_routes.py"
click node_video_service "https://github.com/dylankatchen/knowgap-backend/blob/main/services/video_service.py"
click node_ai "https://github.com/dylankatchen/knowgap-backend/blob/main/utils/ai_utils.py"
click node_youtube "https://github.com/dylankatchen/knowgap-backend/blob/main/utils/youtube_utils.py"
click node_support "https://github.com/dylankatchen/knowgap-backend/blob/main/services/support_service.py"
click node_config "https://github.com/dylankatchen/knowgap-backend/blob/main/config.py"
click node_encryption "https://github.com/dylankatchen/knowgap-backend/blob/main/utils/encryption_utils.py"

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_auth_routes,node_auth_service,node_instructor_routes,node_achieveup_routes toneBlue
class node_canvas,node_canvas_routes,node_canvas_service,node_course_routes,node_course_service,node_submissions toneAmber
class node_achieveup_service,node_analytics,node_skill,node_progress,node_badges toneMint
class node_video_routes,node_video_service,node_ai,node_youtube,node_support toneRose
class node_mongo,node_config,node_encryption,node_student,node_instructor toneIndigo
```

## Components

### API and access

- [Quart application](https://github.com/dylankatchen/knowgap-backend/blob/main/app.py): `app.py`
- [Authentication routes](https://github.com/dylankatchen/knowgap-backend/blob/main/routes/auth_routes.py): `routes/auth_routes.py`
- [Authentication service](https://github.com/dylankatchen/knowgap-backend/blob/main/services/achieveup_auth_service.py): `services/achieveup_auth_service.py`
- [Instructor routes](https://github.com/dylankatchen/knowgap-backend/blob/main/routes/instructor_routes.py): `routes/instructor_routes.py`
- [AchieveUp routes](https://github.com/dylankatchen/knowgap-backend/blob/main/routes/achieveup_routes.py): `routes/achieveup_routes.py`

### Canvas and courses

- **Canvas LMS**
- [Canvas routes](https://github.com/dylankatchen/knowgap-backend/blob/main/routes/canvas_routes.py): `routes/canvas_routes.py`
- [Canvas integration](https://github.com/dylankatchen/knowgap-backend/blob/main/services/achieveup_canvas_service.py): `services/achieveup_canvas_service.py`
- [Course routes](https://github.com/dylankatchen/knowgap-backend/blob/main/routes/course_routes.py): `routes/course_routes.py`
- [Course and quiz data](https://github.com/dylankatchen/knowgap-backend/blob/main/services/course_service.py): `services/course_service.py`
- [Submission processing](https://github.com/dylankatchen/knowgap-backend/blob/main/services/canvas_submissions_service.py): `services/canvas_submissions_service.py`

### Learning insights

- [Learning analytics core](https://github.com/dylankatchen/knowgap-backend/blob/main/services/achieveup_service.py): `services/achieveup_service.py`
- [Risk analytics](https://github.com/dylankatchen/knowgap-backend/blob/main/services/analytics_service.py): `services/analytics_service.py`
- [Skill mastery](https://github.com/dylankatchen/knowgap-backend/blob/main/services/skill_service.py): `services/skill_service.py`
- [Progress tracking](https://github.com/dylankatchen/knowgap-backend/blob/main/services/progress_service.py): `services/progress_service.py`
- [Badges](https://github.com/dylankatchen/knowgap-backend/blob/main/services/badge_service.py): `services/badge_service.py`

### Recommendations

- [Video routes](https://github.com/dylankatchen/knowgap-backend/blob/main/routes/video_routes.py): `routes/video_routes.py`
- [Video recommendations](https://github.com/dylankatchen/knowgap-backend/blob/main/services/video_service.py): `services/video_service.py`
- [Core topic generation](https://github.com/dylankatchen/knowgap-backend/blob/main/utils/ai_utils.py): `utils/ai_utils.py`
- [Video search and metadata](https://github.com/dylankatchen/knowgap-backend/blob/main/utils/youtube_utils.py): `utils/youtube_utils.py`
- [Risk-level support videos](https://github.com/dylankatchen/knowgap-backend/blob/main/services/support_service.py): `services/support_service.py`

### Shared platform

- **MongoDB**
- [Application configuration](https://github.com/dylankatchen/knowgap-backend/blob/main/config.py): `config.py`
- [Token encryption](https://github.com/dylankatchen/knowgap-backend/blob/main/utils/encryption_utils.py): `utils/encryption_utils.py`

### Other components

- **Student**
- **Instructor**

## Connections

- Student → Quart application: uses
- Instructor → Quart application: uses
- Quart application → Authentication routes: registers (evidence: `app.py`)
- Quart application → Canvas routes: registers (evidence: `app.py`)
- Quart application → AchieveUp routes: registers (evidence: `app.py`)
- Quart application → Instructor routes: registers (evidence: `app.py`)
- Quart application → Course routes: registers (evidence: `app.py`)
- Quart application → Video routes: registers (evidence: `app.py`)
- Authentication routes → Authentication service: uses (evidence: `routes/auth_routes.py`)
- Canvas routes → Canvas integration: uses (evidence: `routes/canvas_routes.py`)
- Course routes → Course and quiz data: uses (evidence: `routes/course_routes.py`)
- Course routes → Canvas integration: uses (evidence: `routes/course_routes.py`)
- Instructor routes → Authentication service: verifies (evidence: `routes/instructor_routes.py`)
- Instructor routes → Learning analytics core: requests insights (evidence: `routes/instructor_routes.py`)
- Instructor routes → Risk analytics: requests analytics (evidence: `routes/instructor_routes.py`)
- AchieveUp routes → Learning analytics core: requests learning operations (evidence: `routes/achieveup_routes.py`)
- Course and quiz data → Canvas LMS: fetches course data
- Submission processing → Canvas integration: uses Canvas integration (evidence: `services/canvas_submissions_service.py`)
- Submission processing → MongoDB: stores submissions (evidence: `services/canvas_submissions_service.py`)
- Course and quiz data → MongoDB: reads and writes (evidence: `services/course_service.py`)
- Course and quiz data → Submission processing: refreshes results
- Learning analytics core → Authentication service: verifies users (evidence: `services/achieveup_service.py`)
- Learning analytics core → Canvas integration: uses Canvas integration (evidence: `services/achieveup_service.py`)
- Learning analytics core → MongoDB: reads and writes (evidence: `services/achieveup_service.py`)
- Risk analytics → Learning analytics core: uses learning data (evidence: `services/analytics_service.py`)
- Risk analytics → MongoDB: reads and writes (evidence: `services/analytics_service.py`)
- Skill mastery → MongoDB: reads and writes (evidence: `services/skill_service.py`)
- Progress tracking → MongoDB: reads and writes (evidence: `services/progress_service.py`)
- Badges → MongoDB: reads and writes (evidence: `services/badge_service.py`)
- Video routes → Video recommendations: requests recommendations (evidence: `routes/video_routes.py`)
- Video recommendations → Core topic generation: generates topics (evidence: `services/video_service.py`)
- Video recommendations → Video search and metadata: finds videos (evidence: `services/video_service.py`)
- Video recommendations → MongoDB: caches video data (evidence: `services/video_service.py`)
- Video recommendations → Course and quiz data: uses course data (evidence: `routes/video_routes.py`)
- Risk-level support videos → MongoDB: reads and writes
- Authentication service → Token encryption: decrypts Canvas tokens (evidence: `services/achieveup_auth_service.py`)
- Quart application → Application configuration: configures runtime (evidence: `app.py`)