# abdulloh-dev03/ai-teach-atelier architecture

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

- Interactive diagram: https://gitdiagram.com/abdulloh-dev03/ai-teach-atelier
- Repository: https://github.com/abdulloh-dev03/ai-teach-atelier

## Overview

AI Teach Atelier combines coding practice, AI assistance, and judged execution. The main flow is sign-in, generate or browse a challenge, edit and run or submit code, then review stored results; persistent chat and image-assisted prompts form a parallel learning branch. The graph includes the documented frontend/API and backend layers, plus execution and AI internals visible in excerpts. Some service and controller links rely on README descriptions rather than sampled calls, so unsampled details are not expanded.

Main entry points: [`backend/src/app.ts`](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/app.ts) (Express app), [`frontend/src/store/api.ts`](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/frontend/src/store/api.ts) (API state layer), [`backend/src/services/problem.service.ts`](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/services/problem.service.ts) (Problem lifecycle), [`backend/src/services/executionRouter.ts`](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/services/executionRouter.ts) (Execution router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Learning interface"]
  node_pages["Learning pages"]
  node_workspace["Coding workspace<br/>[page.tsx]"]
  node_chatui["Chat interface"]
  node_authui["Sign-in forms"]
  node_rtk["API state layer<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_app["Express app<br/>[app.ts]"]
  node_authroutes["Auth routes<br/>[auth.route.ts]"]
  node_problemroutes["Problem routes<br/>[problem.route.ts]"]
  node_chatroutes["Chat routes<br/>[chat.routes.ts]"]
  node_execroutes["Run routes<br/>[executeRoutes.ts]"]
end

subgraph group_learning["Learning services"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_problems["Problem lifecycle<br/>[problem.service.ts]"]
  node_generation["AI generation<br/>[ai.service.ts]"]
  node_chat["Chat service<br/>[chat.service.ts]"]
end

subgraph group_execution["Code execution"]
  node_wrapper["Code wrapper<br/>[WrapperService.ts]"]
  node_router["Execution router<br/>[executionRouter.ts]"]
  node_judge["Submission judging<br/>[judgeService.ts]"]
end

subgraph group_state["Persistent state and media"]
  node_database[("PostgreSQL data<br/>[prisma.ts]")]
  node_cloudinary["Image and avatar uploads<br/>[cloudinary.ts]"]
end

node_learner(("Learner"))
node_hf{{"Hugging Face"}}
node_judge0{{"Judge0"}}
node_node{{"Node runtime"}}
node_media{{"Cloudinary service"}}

node_learner -->|"signs in"| node_authui
node_learner -->|"browses challenges"| node_pages
node_pages -->|"requests data"| node_rtk
node_workspace -->|"runs or submits"| node_rtk
node_chatui -->|"sends prompts"| node_rtk
node_authui -->|"authenticates"| node_rtk
node_rtk -->|"calls API"| node_app
node_app -->|"mounts routes"| node_authroutes
node_app -->|"mounts routes"| node_problemroutes
node_app -->|"mounts routes"| node_chatroutes
node_app -->|"mounts routes"| node_execroutes
node_chatroutes -->|"dispatches to"| node_chat
node_authroutes -.->|"handles auth"| node_auth
node_problemroutes -.->|"handles problems"| node_problems
node_problems -.->|"generates challenge"| node_generation
node_generation -->|"requests generation"| node_hf
node_chat -.->|"requests AI chat"| node_hf
node_problems -.->|"stores challenges"| node_database
node_chat -.->|"persists sessions"| node_database
node_auth -->|"reads and writes users"| node_database
node_workspace -.->|"prepares solution"| node_wrapper
node_wrapper -->|"wraps code for"| node_router
node_router -->|"executes JS and TS"| node_node
node_router -->|"dispatches Python"| node_judge0
node_judge -.->|"runs test code"| node_router
node_problems -.->|"submits solutions"| node_judge
node_judge -.->|"stores verdicts"| node_database
node_workspace -.->|"uploads images"| node_media
node_media -.->|"uses integration"| node_cloudinary

click node_pages "https://github.com/abdulloh-dev03/ai-teach-atelier/tree/Abdulloh/frontend/src/app/(protected)"
click node_workspace "https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/frontend/src/app/(protected)/problems/%5Bid%5D/page.tsx"
click node_chatui "https://github.com/abdulloh-dev03/ai-teach-atelier/tree/Abdulloh/frontend/src/components/chat"
click node_authui "https://github.com/abdulloh-dev03/ai-teach-atelier/tree/Abdulloh/frontend/src/app/(auth)"
click node_rtk "https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/frontend/src/store/api.ts"
click node_app "https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/app.ts"
click node_authroutes "https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/routes/auth.route.ts"
click node_problemroutes "https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/routes/problem.route.ts"
click node_chatroutes "https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/routes/chat.routes.ts"
click node_execroutes "https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/routes/executeRoutes.ts"
click node_auth "https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/services/auth.service.ts"
click node_problems "https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/services/problem.service.ts"
click node_generation "https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/services/ai.service.ts"
click node_chat "https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/services/chat.service.ts"
click node_wrapper "https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/services/WrapperService.ts"
click node_router "https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/services/executionRouter.ts"
click node_judge "https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/services/judgeService.ts"
click node_database "https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/lib/prisma.ts"
click node_cloudinary "https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/utils/cloudinary.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_pages,node_workspace,node_chatui,node_authui,node_rtk toneBlue
class node_app,node_authroutes,node_problemroutes,node_chatroutes,node_execroutes toneAmber
class node_auth,node_problems,node_generation,node_chat toneMint
class node_wrapper,node_router,node_judge toneRose
class node_database,node_cloudinary,node_learner,node_hf,node_judge0,node_node,node_media toneIndigo
```

## Components

### Learning interface

- [Learning pages](https://github.com/abdulloh-dev03/ai-teach-atelier/tree/Abdulloh/frontend/src/app/(protected)): `frontend/src/app/(protected)`
- [Coding workspace](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/frontend/src/app/(protected)/problems/%5Bid%5D/page.tsx): `frontend/src/app/(protected)/problems/[id]/page.tsx`
- [Chat interface](https://github.com/abdulloh-dev03/ai-teach-atelier/tree/Abdulloh/frontend/src/components/chat): `frontend/src/components/chat`
- [Sign-in forms](https://github.com/abdulloh-dev03/ai-teach-atelier/tree/Abdulloh/frontend/src/app/(auth)): `frontend/src/app/(auth)`
- [API state layer](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/frontend/src/store/api.ts): `frontend/src/store/api.ts`

### Backend API

- [Express app](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/app.ts): `backend/src/app.ts`
- [Auth routes](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/routes/auth.route.ts): `backend/src/routes/auth.route.ts`
- [Problem routes](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/routes/problem.route.ts): `backend/src/routes/problem.route.ts`
- [Chat routes](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/routes/chat.routes.ts): `backend/src/routes/chat.routes.ts`
- [Run routes](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/routes/executeRoutes.ts): `backend/src/routes/executeRoutes.ts`

### Learning services

- [Authentication](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/services/auth.service.ts): `backend/src/services/auth.service.ts`
- [Problem lifecycle](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/services/problem.service.ts): `backend/src/services/problem.service.ts`
- [AI generation](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/services/ai.service.ts): `backend/src/services/ai.service.ts`
- [Chat service](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/services/chat.service.ts): `backend/src/services/chat.service.ts`

### Code execution

- [Code wrapper](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/services/WrapperService.ts): `backend/src/services/WrapperService.ts`
- [Execution router](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/services/executionRouter.ts): `backend/src/services/executionRouter.ts`
- [Submission judging](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/services/judgeService.ts): `backend/src/services/judgeService.ts`

### Persistent state and media

- [PostgreSQL data](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/lib/prisma.ts): `backend/src/lib/prisma.ts`
- [Image and avatar uploads](https://github.com/abdulloh-dev03/ai-teach-atelier/blob/Abdulloh/backend/src/utils/cloudinary.ts): `backend/src/utils/cloudinary.ts`

### Other components

- **Learner**
- **Hugging Face**
- **Judge0**
- **Node runtime**
- **Cloudinary service**

## Connections

- Learner → Sign-in forms: signs in (evidence: `README.md`)
- Learner → Learning pages: browses challenges (evidence: `README.md`)
- Learning pages → API state layer: requests data (evidence: `README.md`)
- Coding workspace → API state layer: runs or submits (evidence: `README.md`)
- Chat interface → API state layer: sends prompts (evidence: `README.md`)
- Sign-in forms → API state layer: authenticates
- API state layer → Express app: calls API (evidence: `README.md`)
- Express app → Auth routes: mounts routes (evidence: `backend/src/app.ts`)
- Express app → Problem routes: mounts routes (evidence: `backend/src/app.ts`)
- Express app → Chat routes: mounts routes (evidence: `backend/src/app.ts`)
- Express app → Run routes: mounts routes (evidence: `backend/src/app.ts`)
- Chat routes → Chat service: dispatches to (evidence: `backend/src/routes/chat.routes.ts`)
- Auth routes → Authentication: handles auth (evidence: `README.md`)
- Problem routes → Problem lifecycle: handles problems (evidence: `README.md`)
- Problem lifecycle → AI generation: generates challenge (evidence: `README.md`)
- AI generation → Hugging Face: requests generation (evidence: `backend/src/services/ai.service.ts`)
- Chat service → Hugging Face: requests AI chat (evidence: `README.md`)
- Problem lifecycle → PostgreSQL data: stores challenges (evidence: `README.md`)
- Chat service → PostgreSQL data: persists sessions (evidence: `README.md`)
- Authentication → PostgreSQL data: reads and writes users (evidence: `backend/src/services/auth.service.ts`)
- Coding workspace → Code wrapper: prepares solution (evidence: `README.md`)
- Code wrapper → Execution router: wraps code for (evidence: `backend/src/services/ai.service.ts`)
- Execution router → Node runtime: executes JS and TS (evidence: `backend/src/services/executionRouter.ts`)
- Execution router → Judge0: dispatches Python (evidence: `backend/src/services/executionRouter.ts`)
- Submission judging → Execution router: runs test code (evidence: `README.md`)
- Problem lifecycle → Submission judging: submits solutions (evidence: `README.md`)
- Submission judging → PostgreSQL data: stores verdicts (evidence: `README.md`)
- Coding workspace → Cloudinary service: uploads images (evidence: `README.md`)
- Cloudinary service → Image and avatar uploads: uses integration (evidence: `README.md`)
