# bspreddy/coding-platfrom architecture

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

- Interactive diagram: https://gitdiagram.com/bspreddy/coding-platfrom
- Repository: https://github.com/bspreddy/coding-platfrom

## Overview

This is a multi-role online coding platform: students solve problems and contests, while college staff and platform administrators manage learning activities and monitor outcomes. The central student path runs from authenticated API access through submission evaluation to persisted results and XP, streak, and leaderboard updates; dashboards and analytics then expose progress. The tree also documents assignments, proctoring, notifications, and bulk administration. Connections are limited to relationships demonstrated by excerpts or SOURCE INDEX references; unsampled feature branches are retained without speculative call chains.

Main entry points: [`src/app/college`](https://github.com/bspreddy/coding-platfrom/tree/main/src/app/college) (College portal), [`src/app/api/submissions/route.ts`](https://github.com/bspreddy/coding-platfrom/blob/main/src/app/api/submissions/route.ts) (Submission endpoint), [`src/db/index.ts`](https://github.com/bspreddy/coding-platfrom/blob/main/src/db/index.ts) (PostgreSQL database), [`src/lib/xpService.ts`](https://github.com/bspreddy/coding-platfrom/blob/main/src/lib/xpService.ts) (XP progression)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experiences"]
  node_student["Student portal"]
  node_college["College portal"]
  node_admin["Admin portal"]
  node_contestui["Contest workbench"]
end

subgraph group_learning["Learning workflows"]
  node_problemapi["Problem catalog<br/>[route.ts]"]
  node_submission["Submission endpoint<br/>[route.ts]"]
  node_contestapi["Contest APIs"]
  node_assignments["Assignments<br/>[route.ts]"]
  node_proctor["Contest proctoring"]
  node_dashboard["Student dashboard<br/>[route.ts]"]
end

subgraph group_operations["Administration"]
  node_analytics["College analytics<br/>[route.ts]"]
  node_collegecontests["College contests<br/>[route.ts]"]
  node_collegeproblems["College problems<br/>[route.ts]"]
  node_studentadmin["Student management<br/>[route.ts]"]
  node_adminapi["Admin APIs"]
end

subgraph group_services["Platform services"]
  node_runner["Code runner<br/>[docker-runner.ts]"]
  node_judge0["Judge0 client<br/>[judge0Client.ts]"]
  node_auth["Session and auth<br/>[auth.ts]"]
  node_xp["XP progression<br/>[xpService.ts]"]
  node_streak["Streak service<br/>[streakService.ts]"]
  node_leaderboard["Leaderboard service"]
  node_problemstats["Problem statistics<br/>[problemStats.ts]"]
end

subgraph group_persistence["Persistence"]
  node_redis["Redis cache<br/>[redis.ts]"]
  node_db[("PostgreSQL database<br/>[index.ts]")]
  node_schema["Platform data schema<br/>[schema.ts]"]
end

node_learner(("Student"))
node_collegeuser(("College staff"))
node_administrator(("Platform admin"))
node_judge0service["Judge0 service"]

node_learner -->|"uses"| node_student
node_student -.->|"opens workbench"| node_contestui
node_contestui -.->|"submits code"| node_submission
node_student -.->|"browses problems"| node_problemapi
node_submission -->|"gets session"| node_auth
node_submission -->|"executes code"| node_runner
node_runner -.->|"delegates execution"| node_judge0
node_judge0 -->|"submits and polls"| node_judge0service
node_submission -.->|"reads and writes"| node_db
node_submission -->|"awards progress"| node_xp
node_submission -->|"updates activity"| node_streak
node_submission -->|"updates rankings"| node_leaderboard
node_dashboard -->|"gets session"| node_auth
node_dashboard -->|"loads level data"| node_xp
node_xp -->|"caches progression"| node_redis
node_xp -->|"references service"| node_leaderboard
node_streak -->|"awards bonus XP"| node_xp
node_leaderboard -->|"invalidates cache"| node_redis
node_problemapi -->|"gets session"| node_auth
node_problemapi -->|"loads statistics"| node_problemstats
node_collegeuser -->|"uses"| node_college
node_college -.->|"views analytics"| node_analytics
node_college -.->|"manages contests"| node_collegecontests
node_college -.->|"manages problems"| node_collegeproblems
node_college -.->|"manages assignments"| node_assignments
node_college -.->|"manages students"| node_studentadmin
node_analytics -->|"gets session"| node_auth
node_analytics -->|"queries analytics"| node_db
node_collegecontests -->|"gets session"| node_auth
node_collegeproblems -->|"gets session"| node_auth
node_collegeproblems -.->|"manages records"| node_db
node_college -.->|"uses contest controls"| node_proctor
node_administrator -->|"uses"| node_admin
node_admin -.->|"manages platform"| node_adminapi
node_db -->|"loads schema"| node_schema
node_dashboard -->|"reads learner data"| node_db
node_leaderboard -->|"reads and updates ranks"| node_db
node_streak -->|"reads activity"| node_db
node_xp -->|"reads and writes XP"| node_db

click node_student "https://github.com/bspreddy/coding-platfrom/tree/main/src/app/user"
click node_college "https://github.com/bspreddy/coding-platfrom/tree/main/src/app/college"
click node_admin "https://github.com/bspreddy/coding-platfrom/tree/main/src/app/admin"
click node_contestui "https://github.com/bspreddy/coding-platfrom/blob/main/src/components/contest/FullScreenContestWorkbench.tsx"
click node_problemapi "https://github.com/bspreddy/coding-platfrom/blob/main/src/app/api/problems/route.ts"
click node_submission "https://github.com/bspreddy/coding-platfrom/blob/main/src/app/api/submissions/route.ts"
click node_runner "https://github.com/bspreddy/coding-platfrom/blob/main/src/lib/docker-runner.ts"
click node_judge0 "https://github.com/bspreddy/coding-platfrom/blob/main/src/lib/compilers/judge0Client.ts"
click node_contestapi "https://github.com/bspreddy/coding-platfrom/tree/main/src/app/api/contests"
click node_assignments "https://github.com/bspreddy/coding-platfrom/blob/main/src/app/api/college/assignments/route.ts"
click node_proctor "https://github.com/bspreddy/coding-platfrom/blob/main/src/components/contest/ContestProctorWrapper.tsx"
click node_dashboard "https://github.com/bspreddy/coding-platfrom/blob/main/src/app/api/student/dashboard/route.ts"
click node_analytics "https://github.com/bspreddy/coding-platfrom/blob/main/src/app/api/college/analytics/route.ts"
click node_collegecontests "https://github.com/bspreddy/coding-platfrom/blob/main/src/app/api/college/contests/route.ts"
click node_collegeproblems "https://github.com/bspreddy/coding-platfrom/blob/main/src/app/api/college/problems/route.ts"
click node_studentadmin "https://github.com/bspreddy/coding-platfrom/blob/main/src/app/api/college/students/route.ts"
click node_adminapi "https://github.com/bspreddy/coding-platfrom/tree/main/src/app/api/admin"
click node_auth "https://github.com/bspreddy/coding-platfrom/blob/main/src/lib/auth.ts"
click node_xp "https://github.com/bspreddy/coding-platfrom/blob/main/src/lib/xpService.ts"
click node_streak "https://github.com/bspreddy/coding-platfrom/blob/main/src/lib/streakService.ts"
click node_leaderboard "https://github.com/bspreddy/coding-platfrom/blob/main/src/lib/leaderboardService.ts"
click node_problemstats "https://github.com/bspreddy/coding-platfrom/blob/main/src/lib/problemStats.ts"
click node_redis "https://github.com/bspreddy/coding-platfrom/blob/main/src/lib/redis.ts"
click node_db "https://github.com/bspreddy/coding-platfrom/blob/main/src/db/index.ts"
click node_schema "https://github.com/bspreddy/coding-platfrom/blob/main/src/db/postgres/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_student,node_college,node_admin,node_contestui toneBlue
class node_problemapi,node_submission,node_contestapi,node_assignments,node_proctor,node_dashboard toneAmber
class node_analytics,node_collegecontests,node_collegeproblems,node_studentadmin,node_adminapi toneMint
class node_runner,node_judge0,node_auth,node_xp,node_streak,node_leaderboard,node_problemstats toneRose
class node_redis,node_db,node_schema,node_learner,node_collegeuser,node_administrator,node_judge0service toneIndigo
```

## Components

### User experiences

- [Student portal](https://github.com/bspreddy/coding-platfrom/tree/main/src/app/user): `src/app/user`
- [College portal](https://github.com/bspreddy/coding-platfrom/tree/main/src/app/college): `src/app/college`
- [Admin portal](https://github.com/bspreddy/coding-platfrom/tree/main/src/app/admin): `src/app/admin`
- [Contest workbench](https://github.com/bspreddy/coding-platfrom/blob/main/src/components/contest/FullScreenContestWorkbench.tsx): `src/components/contest/FullScreenContestWorkbench.tsx`

### Learning workflows

- [Problem catalog](https://github.com/bspreddy/coding-platfrom/blob/main/src/app/api/problems/route.ts): `src/app/api/problems/route.ts`
- [Submission endpoint](https://github.com/bspreddy/coding-platfrom/blob/main/src/app/api/submissions/route.ts): `src/app/api/submissions/route.ts`
- [Contest APIs](https://github.com/bspreddy/coding-platfrom/tree/main/src/app/api/contests): `src/app/api/contests`
- [Assignments](https://github.com/bspreddy/coding-platfrom/blob/main/src/app/api/college/assignments/route.ts): `src/app/api/college/assignments/route.ts`
- [Contest proctoring](https://github.com/bspreddy/coding-platfrom/blob/main/src/components/contest/ContestProctorWrapper.tsx): `src/components/contest/ContestProctorWrapper.tsx`
- [Student dashboard](https://github.com/bspreddy/coding-platfrom/blob/main/src/app/api/student/dashboard/route.ts): `src/app/api/student/dashboard/route.ts`

### Administration

- [College analytics](https://github.com/bspreddy/coding-platfrom/blob/main/src/app/api/college/analytics/route.ts): `src/app/api/college/analytics/route.ts`
- [College contests](https://github.com/bspreddy/coding-platfrom/blob/main/src/app/api/college/contests/route.ts): `src/app/api/college/contests/route.ts`
- [College problems](https://github.com/bspreddy/coding-platfrom/blob/main/src/app/api/college/problems/route.ts): `src/app/api/college/problems/route.ts`
- [Student management](https://github.com/bspreddy/coding-platfrom/blob/main/src/app/api/college/students/route.ts): `src/app/api/college/students/route.ts`
- [Admin APIs](https://github.com/bspreddy/coding-platfrom/tree/main/src/app/api/admin): `src/app/api/admin`

### Platform services

- [Code runner](https://github.com/bspreddy/coding-platfrom/blob/main/src/lib/docker-runner.ts): `src/lib/docker-runner.ts`
- [Judge0 client](https://github.com/bspreddy/coding-platfrom/blob/main/src/lib/compilers/judge0Client.ts): `src/lib/compilers/judge0Client.ts`
- [Session and auth](https://github.com/bspreddy/coding-platfrom/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [XP progression](https://github.com/bspreddy/coding-platfrom/blob/main/src/lib/xpService.ts): `src/lib/xpService.ts`
- [Streak service](https://github.com/bspreddy/coding-platfrom/blob/main/src/lib/streakService.ts): `src/lib/streakService.ts`
- [Leaderboard service](https://github.com/bspreddy/coding-platfrom/blob/main/src/lib/leaderboardService.ts): `src/lib/leaderboardService.ts`
- [Problem statistics](https://github.com/bspreddy/coding-platfrom/blob/main/src/lib/problemStats.ts): `src/lib/problemStats.ts`

### Persistence

- [Redis cache](https://github.com/bspreddy/coding-platfrom/blob/main/src/lib/redis.ts): `src/lib/redis.ts`
- [PostgreSQL database](https://github.com/bspreddy/coding-platfrom/blob/main/src/db/index.ts): `src/db/index.ts`
- [Platform data schema](https://github.com/bspreddy/coding-platfrom/blob/main/src/db/postgres/schema.ts): `src/db/postgres/schema.ts`

### Other components

- **Student**
- **College staff**
- **Platform admin**
- **Judge0 service**

## Connections

- Student → Student portal: uses
- Student portal → Contest workbench: opens workbench
- Contest workbench → Submission endpoint: submits code
- Student portal → Problem catalog: browses problems
- Submission endpoint → Session and auth: gets session (evidence: `src/app/api/submissions/route.ts`)
- Submission endpoint → Code runner: executes code (evidence: `src/app/api/submissions/route.ts`)
- Code runner → Judge0 client: delegates execution
- Judge0 client → Judge0 service: submits and polls (evidence: `src/lib/compilers/judge0Client.ts`)
- Submission endpoint → PostgreSQL database: reads and writes (evidence: `src/app/api/submissions/route.ts`)
- Submission endpoint → XP progression: awards progress (evidence: `src/app/api/submissions/route.ts`)
- Submission endpoint → Streak service: updates activity (evidence: `src/app/api/submissions/route.ts`)
- Submission endpoint → Leaderboard service: updates rankings (evidence: `src/app/api/submissions/route.ts`)
- Student dashboard → Session and auth: gets session (evidence: `src/app/api/student/dashboard/route.ts`)
- Student dashboard → XP progression: loads level data (evidence: `src/app/api/student/dashboard/route.ts`)
- XP progression → Redis cache: caches progression (evidence: `src/lib/xpService.ts`)
- XP progression → Leaderboard service: references service (evidence: `src/lib/xpService.ts`)
- Streak service → XP progression: awards bonus XP (evidence: `src/lib/streakService.ts`)
- Leaderboard service → Redis cache: invalidates cache (evidence: `src/lib/leaderboardService.ts`)
- Problem catalog → Session and auth: gets session (evidence: `src/app/api/problems/route.ts`)
- Problem catalog → Problem statistics: loads statistics (evidence: `src/app/api/problems/route.ts`)
- College staff → College portal: uses
- College portal → College analytics: views analytics
- College portal → College contests: manages contests
- College portal → College problems: manages problems
- College portal → Assignments: manages assignments
- College portal → Student management: manages students
- College analytics → Session and auth: gets session (evidence: `src/app/api/college/analytics/route.ts`)
- College analytics → PostgreSQL database: queries analytics (evidence: `src/app/api/college/analytics/route.ts`)
- College contests → Session and auth: gets session (evidence: `src/app/api/college/contests/route.ts`)
- College problems → Session and auth: gets session (evidence: `src/app/api/college/problems/route.ts`)
- College problems → PostgreSQL database: manages records (evidence: `src/app/api/college/problems/route.ts`)
- College portal → Contest proctoring: uses contest controls
- Platform admin → Admin portal: uses
- Admin portal → Admin APIs: manages platform
- PostgreSQL database → Platform data schema: loads schema (evidence: `src/db/index.ts`)
- Student dashboard → PostgreSQL database: reads learner data (evidence: `src/app/api/student/dashboard/route.ts`)
- Leaderboard service → PostgreSQL database: reads and updates ranks (evidence: `src/lib/leaderboardService.ts`)
- Streak service → PostgreSQL database: reads activity (evidence: `src/lib/streakService.ts`)
- XP progression → PostgreSQL database: reads and writes XP (evidence: `src/lib/xpService.ts`)
