# ai-catalyst-salman/kahani-events-lms-backend architecture

> Architecture diagram of the GitHub repository ai-catalyst-salman/kahani-events-lms-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ai-catalyst-salman/kahani-events-lms-backend
- Repository: https://github.com/ai-catalyst-salman/kahani-events-lms-backend

## Overview

Kahani Events Training Platform is a FastAPI backend for employee training. Learners sign in, browse courses and videos, record completions, and access quizzes subject to authentication and progress rules; administrators manage training content and users and review platform metrics. Supabase provides authentication and persistent data, while the API’s auth dependency resolves user roles and protects restricted operations. The tree and excerpts document analytics and an AI quiz-generation route as additional capabilities. The AI route is not included by the sampled application router setup, so its integration with the live API is uncertain.

Main entry points: [`app/main.py`](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/main.py) (FastAPI application), [`app/core/supabase_client.py`](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/core/supabase_client.py) (Supabase client), [`app/core/auth.py`](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/core/auth.py) (Token and role guard), [`app/api/auth.py`](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/api/auth.py) (Login and profile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API entry"]
  node_api["FastAPI application<br/>[main.py]"]
end

subgraph group_learning["Learner training"]
  node_courses["Course browsing<br/>[courses.py]"]
  node_progress["Completion tracking<br/>[progress.py]"]
  node_quizzes["Quiz access<br/>[quizzes.py]"]
end

subgraph group_admin["Administration"]
  node_analytics["Training analytics<br/>[analytics.py]"]
  node_admin_api["Admin operations<br/>[admin.py]"]
  node_admin_schema["Admin schemas<br/>[admin.py]"]
end

subgraph group_platform["Identity and data"]
  node_auth_api["Login and profile<br/>[auth.py]"]
  node_auth_guard["Token and role guard<br/>[auth.py]"]
  node_rate_limit["Login rate limiter<br/>[rate_limit.py]"]
  node_auth_schema["Auth schemas<br/>[auth.py]"]
  node_supabase_client["Supabase client<br/>[supabase_client.py]"]
  node_supabase[("Supabase")]
end

subgraph group_ai["AI quiz generation"]
  node_quiz_upload["Video quiz generation route<br/>[quiz_router.py]"]
  node_ai_service["Transcription and quiz AI<br/>[ai_quiz_service.py]"]
  node_quiz_schema["Generated quiz schemas<br/>[quiz_schemas.py]"]
  node_groq["Groq Whisper"]
  node_gemini["Google Gemini"]
end

node_learner(("Learner"))
node_admin_actor(("Administrator"))

node_learner -->|"sends requests"| node_api
node_admin_actor -->|"sends requests"| node_api
node_api -->|"dispatches routes"| node_auth_api
node_api -->|"dispatches routes"| node_courses
node_api -->|"dispatches routes"| node_progress
node_api -->|"dispatches routes"| node_quizzes
node_api -->|"dispatches routes"| node_admin_api
node_api -->|"dispatches routes"| node_analytics
node_auth_api -->|"checks attempts"| node_rate_limit
node_auth_api -->|"authenticates profile"| node_auth_guard
node_auth_api -->|"signs in"| node_supabase_client
node_auth_guard -->|"verifies token"| node_supabase_client
node_auth_api -->|"validates payload"| node_auth_schema
node_admin_api -->|"requires admin"| node_auth_guard
node_courses -->|"reads courses"| node_supabase_client
node_progress -->|"requires user"| node_auth_guard
node_progress -->|"records completion"| node_supabase_client
node_quizzes -->|"checks access"| node_auth_guard
node_quizzes -->|"reads quiz data"| node_supabase_client
node_analytics -->|"requires admin"| node_auth_guard
node_analytics -->|"reads metrics"| node_supabase_client
node_admin_api -->|"manages records"| node_supabase_client
node_admin_api -->|"validates payloads"| node_admin_schema
node_supabase_client -->|"queries"| node_supabase
node_quiz_upload -->|"transcribes and generates"| node_ai_service
node_quiz_upload -->|"saves questions"| node_supabase_client
node_ai_service -.->|"transcribes audio"| node_groq
node_ai_service -.->|"generates and grades"| node_gemini
node_ai_service -->|"validates output"| node_quiz_schema

click node_api "https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/main.py"
click node_auth_api "https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/api/auth.py"
click node_auth_guard "https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/core/auth.py"
click node_rate_limit "https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/core/rate_limit.py"
click node_courses "https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/api/courses.py"
click node_progress "https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/api/progress.py"
click node_quizzes "https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/api/quizzes.py"
click node_analytics "https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/api/analytics.py"
click node_admin_api "https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/api/admin.py"
click node_auth_schema "https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/schemas/auth.py"
click node_admin_schema "https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/schemas/admin.py"
click node_supabase_client "https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/core/supabase_client.py"
click node_quiz_upload "https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/api/quiz_router.py"
click node_ai_service "https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/services/ai_quiz_service.py"
click node_quiz_schema "https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/schemas/quiz_schemas.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_api toneBlue
class node_courses,node_progress,node_quizzes toneAmber
class node_analytics,node_admin_api,node_admin_schema toneMint
class node_auth_api,node_auth_guard,node_rate_limit,node_auth_schema,node_supabase_client,node_supabase toneRose
class node_quiz_upload,node_ai_service,node_quiz_schema,node_groq,node_gemini,node_learner,node_admin_actor toneIndigo
```

## Components

### API entry

- [FastAPI application](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/main.py): `app/main.py`

### Learner training

- [Course browsing](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/api/courses.py): `app/api/courses.py`
- [Completion tracking](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/api/progress.py): `app/api/progress.py`
- [Quiz access](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/api/quizzes.py): `app/api/quizzes.py`

### Administration

- [Training analytics](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/api/analytics.py): `app/api/analytics.py`
- [Admin operations](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/api/admin.py): `app/api/admin.py`
- [Admin schemas](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/schemas/admin.py): `app/schemas/admin.py`

### Identity and data

- [Login and profile](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/api/auth.py): `app/api/auth.py`
- [Token and role guard](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/core/auth.py): `app/core/auth.py`
- [Login rate limiter](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/core/rate_limit.py): `app/core/rate_limit.py`
- [Auth schemas](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/schemas/auth.py): `app/schemas/auth.py`
- [Supabase client](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/core/supabase_client.py): `app/core/supabase_client.py`
- **Supabase**

### AI quiz generation

- [Video quiz generation route](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/api/quiz_router.py): `app/api/quiz_router.py`
- [Transcription and quiz AI](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/services/ai_quiz_service.py): `app/services/ai_quiz_service.py`
- [Generated quiz schemas](https://github.com/ai-catalyst-salman/kahani-events-lms-backend/blob/main/app/schemas/quiz_schemas.py): `app/schemas/quiz_schemas.py`
- **Groq Whisper**
- **Google Gemini**

### Other components

- **Learner**
- **Administrator**

## Connections

- Learner → FastAPI application: sends requests
- Administrator → FastAPI application: sends requests
- FastAPI application → Login and profile: dispatches routes
- FastAPI application → Course browsing: dispatches routes
- FastAPI application → Completion tracking: dispatches routes
- FastAPI application → Quiz access: dispatches routes
- FastAPI application → Admin operations: dispatches routes
- FastAPI application → Training analytics: dispatches routes
- Login and profile → Login rate limiter: checks attempts
- Login and profile → Token and role guard: authenticates profile
- Login and profile → Supabase client: signs in
- Token and role guard → Supabase client: verifies token
- Login and profile → Auth schemas: validates payload
- Admin operations → Token and role guard: requires admin
- Course browsing → Supabase client: reads courses
- Completion tracking → Token and role guard: requires user
- Completion tracking → Supabase client: records completion
- Quiz access → Token and role guard: checks access
- Quiz access → Supabase client: reads quiz data
- Training analytics → Token and role guard: requires admin
- Training analytics → Supabase client: reads metrics
- Admin operations → Supabase client: manages records
- Admin operations → Admin schemas: validates payloads
- Supabase client → Supabase: queries
- Video quiz generation route → Transcription and quiz AI: transcribes and generates
- Video quiz generation route → Supabase client: saves questions
- Transcription and quiz AI → Groq Whisper: transcribes audio
- Transcription and quiz AI → Google Gemini: generates and grades
- Transcription and quiz AI → Generated quiz schemas: validates output