# themconquer/knowgap-backend architecture

> Architecture diagram of the GitHub repository themconquer/knowgap-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/themconquer/knowgap-backend
- Repository: https://github.com/themconquer/knowgap-backend

## Overview

KnowGap Backend (AchieveUp API) serves instructors building Canvas-course skill matrices and students tracking mastery and badges. The main workflow is login, course and quiz retrieval, skill assignment, submission syncing, mastery calculation, and progress or badge reporting. Separate branches support course analytics, badge sharing, and skill-video curation. The graph follows documented capabilities and SOURCE INDEX references; some implementation details are unsampled, so uncertain relationships are omitted.

Main entry points: [`mongodb.py`](https://github.com/themconquer/knowgap-backend/blob/main/mongodb.py) (MongoDB access), [`services/achieveup_service.py`](https://github.com/themconquer/knowgap-backend/blob/main/services/achieveup_service.py) (Matrix and skills), [`routes/achieveup_routes.py`](https://github.com/themconquer/knowgap-backend/blob/main/routes/achieveup_routes.py) (AchieveUp routes), [`services/badge_service.py`](https://github.com/themconquer/knowgap-backend/blob/main/services/badge_service.py) (Badges and sharing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_auth_routes["Auth routes<br/>[auth_routes.py]"]
  node_auth_service["Identity service"]
  node_achieveup_routes["AchieveUp routes"]
  node_canvas_routes["Canvas routes<br/>[canvas_routes.py]"]
  node_video_routes["Video routes"]
end

subgraph group_learning["Skills and mastery"]
  node_skill_service["Matrix and skills"]
  node_ai_service["AI suggestions"]
  node_submissions["Submission processing"]
  node_mastery["Mastery service<br/>[mastery_service.py]"]
  node_tiers["Badge tiers<br/>[skill_tiers.py]"]
end

subgraph group_integrations["External integrations"]
  node_canvas_service["Canvas integration"]
  node_ai_utils["AI gateway client<br/>[ai_utils.py]"]
  node_youtube_utils["YouTube client<br/>[youtube_utils.py]"]
end

subgraph group_data["Persistence and sync"]
  node_sync["Sync status"]
  node_mongodb["MongoDB access<br/>[mongodb.py]"]
end

subgraph group_engagement["Analytics and media"]
  node_analytics["Course analytics"]
  node_badges["Badges and sharing<br/>[badge_service.py]"]
  node_videos["Skill videos"]
end

node_frontend(("Web frontend"))
node_canvas["Canvas LMS"]
node_youtube["YouTube"]
node_database[("MongoDB")]

node_frontend -->|"calls API"| node_auth_routes
node_frontend -->|"calls API"| node_achieveup_routes
node_frontend -->|"calls API"| node_canvas_routes
node_frontend -->|"calls API"| node_video_routes
node_auth_routes -->|"invokes"| node_auth_service
node_achieveup_routes -->|"invokes"| node_skill_service
node_achieveup_routes -->|"invokes"| node_badges
node_achieveup_routes -->|"invokes"| node_analytics
node_achieveup_routes -->|"invokes"| node_sync
node_canvas_routes -->|"invokes"| node_canvas_service
node_video_routes -->|"invokes"| node_videos
node_skill_service -->|"uses"| node_ai_utils
node_skill_service -->|"uses"| node_canvas_service
node_skill_service -->|"verifies users"| node_auth_service
node_ai_service -->|"uses"| node_ai_utils
node_submissions -->|"fetches Canvas data"| node_canvas_service
node_submissions -->|"delegates"| node_mastery
node_sync -->|"runs sync"| node_submissions
node_analytics -->|"reads skill data"| node_skill_service
node_analytics -->|"uses tiers"| node_tiers
node_badges -->|"uses tiers"| node_tiers
node_badges -->|"gets course data"| node_canvas_service
node_badges -->|"checks instructor"| node_skill_service
node_videos -->|"requests suggestions"| node_ai_utils
node_videos -->|"uses"| node_youtube_utils
node_canvas_service -->|"requests course data"| node_canvas
node_youtube_utils -->|"queries videos"| node_youtube
node_auth_service -->|"reads and writes"| node_mongodb
node_skill_service -->|"reads and writes"| node_mongodb
node_submissions -->|"stores results"| node_mongodb
node_analytics -->|"reads data"| node_mongodb
node_badges -->|"reads and writes"| node_mongodb
node_videos -->|"reads and writes"| node_mongodb
node_sync -->|"reads and writes"| node_mongodb
node_mongodb -->|"persists data"| node_database

click node_auth_routes "https://github.com/themconquer/knowgap-backend/blob/main/routes/auth_routes.py"
click node_auth_service "https://github.com/themconquer/knowgap-backend/blob/main/services/achieveup_auth_service.py"
click node_achieveup_routes "https://github.com/themconquer/knowgap-backend/blob/main/routes/achieveup_routes.py"
click node_canvas_routes "https://github.com/themconquer/knowgap-backend/blob/main/routes/canvas_routes.py"
click node_video_routes "https://github.com/themconquer/knowgap-backend/blob/main/routes/skill_video_routes.py"
click node_skill_service "https://github.com/themconquer/knowgap-backend/blob/main/services/achieveup_service.py"
click node_ai_service "https://github.com/themconquer/knowgap-backend/blob/main/services/achieveup_ai_service.py"
click node_submissions "https://github.com/themconquer/knowgap-backend/blob/main/services/canvas_submissions_service.py"
click node_mastery "https://github.com/themconquer/knowgap-backend/blob/main/services/mastery_service.py"
click node_tiers "https://github.com/themconquer/knowgap-backend/blob/main/services/skill_tiers.py"
click node_canvas_service "https://github.com/themconquer/knowgap-backend/blob/main/services/achieveup_canvas_service.py"
click node_ai_utils "https://github.com/themconquer/knowgap-backend/blob/main/utils/ai_utils.py"
click node_youtube_utils "https://github.com/themconquer/knowgap-backend/blob/main/utils/youtube_utils.py"
click node_sync "https://github.com/themconquer/knowgap-backend/blob/main/services/sync_status_service.py"
click node_mongodb "https://github.com/themconquer/knowgap-backend/blob/main/mongodb.py"
click node_analytics "https://github.com/themconquer/knowgap-backend/blob/main/services/analytics_service.py"
click node_badges "https://github.com/themconquer/knowgap-backend/blob/main/services/badge_service.py"
click node_videos "https://github.com/themconquer/knowgap-backend/blob/main/services/skill_video_service.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_auth_routes,node_auth_service,node_achieveup_routes,node_canvas_routes,node_video_routes,node_frontend toneBlue
class node_skill_service,node_ai_service,node_submissions,node_mastery,node_tiers,node_database toneAmber
class node_canvas_service,node_ai_utils,node_youtube_utils toneMint
class node_sync,node_mongodb toneRose
class node_analytics,node_badges,node_videos,node_canvas,node_youtube toneIndigo
```

## Components

### API and identity

- [Auth routes](https://github.com/themconquer/knowgap-backend/blob/main/routes/auth_routes.py): `routes/auth_routes.py`
- [Identity service](https://github.com/themconquer/knowgap-backend/blob/main/services/achieveup_auth_service.py): `services/achieveup_auth_service.py`
- [AchieveUp routes](https://github.com/themconquer/knowgap-backend/blob/main/routes/achieveup_routes.py): `routes/achieveup_routes.py`
- [Canvas routes](https://github.com/themconquer/knowgap-backend/blob/main/routes/canvas_routes.py): `routes/canvas_routes.py`
- [Video routes](https://github.com/themconquer/knowgap-backend/blob/main/routes/skill_video_routes.py): `routes/skill_video_routes.py`

### Skills and mastery

- [Matrix and skills](https://github.com/themconquer/knowgap-backend/blob/main/services/achieveup_service.py): `services/achieveup_service.py`
- [AI suggestions](https://github.com/themconquer/knowgap-backend/blob/main/services/achieveup_ai_service.py): `services/achieveup_ai_service.py`
- [Submission processing](https://github.com/themconquer/knowgap-backend/blob/main/services/canvas_submissions_service.py): `services/canvas_submissions_service.py`
- [Mastery service](https://github.com/themconquer/knowgap-backend/blob/main/services/mastery_service.py): `services/mastery_service.py`
- [Badge tiers](https://github.com/themconquer/knowgap-backend/blob/main/services/skill_tiers.py): `services/skill_tiers.py`

### External integrations

- [Canvas integration](https://github.com/themconquer/knowgap-backend/blob/main/services/achieveup_canvas_service.py): `services/achieveup_canvas_service.py`
- [AI gateway client](https://github.com/themconquer/knowgap-backend/blob/main/utils/ai_utils.py): `utils/ai_utils.py`
- [YouTube client](https://github.com/themconquer/knowgap-backend/blob/main/utils/youtube_utils.py): `utils/youtube_utils.py`

### Persistence and sync

- [Sync status](https://github.com/themconquer/knowgap-backend/blob/main/services/sync_status_service.py): `services/sync_status_service.py`
- [MongoDB access](https://github.com/themconquer/knowgap-backend/blob/main/mongodb.py): `mongodb.py`

### Analytics and media

- [Course analytics](https://github.com/themconquer/knowgap-backend/blob/main/services/analytics_service.py): `services/analytics_service.py`
- [Badges and sharing](https://github.com/themconquer/knowgap-backend/blob/main/services/badge_service.py): `services/badge_service.py`
- [Skill videos](https://github.com/themconquer/knowgap-backend/blob/main/services/skill_video_service.py): `services/skill_video_service.py`

### Other components

- **Web frontend**
- **Canvas LMS**
- **YouTube**
- **MongoDB**

## Connections

- Web frontend → Auth routes: calls API (evidence: `README.md`)
- Web frontend → AchieveUp routes: calls API (evidence: `README.md`)
- Web frontend → Canvas routes: calls API (evidence: `README.md`)
- Web frontend → Video routes: calls API (evidence: `README.md`)
- Auth routes → Identity service: invokes (evidence: `routes/auth_routes.py`)
- AchieveUp routes → Matrix and skills: invokes (evidence: `routes/achieveup_routes.py`)
- AchieveUp routes → Badges and sharing: invokes (evidence: `routes/achieveup_routes.py`)
- AchieveUp routes → Course analytics: invokes (evidence: `routes/achieveup_routes.py`)
- AchieveUp routes → Sync status: invokes (evidence: `routes/achieveup_routes.py`)
- Canvas routes → Canvas integration: invokes (evidence: `routes/canvas_routes.py`)
- Video routes → Skill videos: invokes (evidence: `routes/skill_video_routes.py`)
- Matrix and skills → AI gateway client: uses (evidence: `services/achieveup_service.py`)
- Matrix and skills → Canvas integration: uses (evidence: `services/achieveup_service.py`)
- Matrix and skills → Identity service: verifies users (evidence: `services/achieveup_service.py`)
- AI suggestions → AI gateway client: uses (evidence: `services/achieveup_ai_service.py`)
- Submission processing → Canvas integration: fetches Canvas data (evidence: `services/canvas_submissions_service.py`)
- Submission processing → Mastery service: delegates (evidence: `services/canvas_submissions_service.py`)
- Sync status → Submission processing: runs sync (evidence: `services/sync_status_service.py`)
- Course analytics → Matrix and skills: reads skill data (evidence: `services/analytics_service.py`)
- Course analytics → Badge tiers: uses tiers (evidence: `services/analytics_service.py`)
- Badges and sharing → Badge tiers: uses tiers (evidence: `services/badge_service.py`)
- Badges and sharing → Canvas integration: gets course data (evidence: `services/badge_service.py`)
- Badges and sharing → Matrix and skills: checks instructor (evidence: `services/badge_service.py`)
- Skill videos → AI gateway client: requests suggestions (evidence: `services/skill_video_service.py`)
- Skill videos → YouTube client: uses (evidence: `services/skill_video_service.py`)
- Canvas integration → Canvas LMS: requests course data (evidence: `services/achieveup_canvas_service.py`)
- YouTube client → YouTube: queries videos (evidence: `utils/youtube_utils.py`)
- Identity service → MongoDB access: reads and writes (evidence: `services/achieveup_auth_service.py`)
- Matrix and skills → MongoDB access: reads and writes (evidence: `services/achieveup_service.py`)
- Submission processing → MongoDB access: stores results (evidence: `services/canvas_submissions_service.py`)
- Course analytics → MongoDB access: reads data (evidence: `services/analytics_service.py`)
- Badges and sharing → MongoDB access: reads and writes (evidence: `services/badge_service.py`)
- Skill videos → MongoDB access: reads and writes (evidence: `services/skill_video_service.py`)
- Sync status → MongoDB access: reads and writes (evidence: `services/sync_status_service.py`)
- MongoDB access → MongoDB: persists data (evidence: `mongodb.py`)