# vivekjadhav2001/dev-arena architecture

> Architecture diagram of the GitHub repository vivekjadhav2001/dev-arena, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vivekjadhav2001/dev-arena
- Repository: https://github.com/vivekjadhav2001/dev-arena

## Overview

DevArena turns a developer’s GitHub and LeetCode activity into a deterministic identity, then lets them compete in authoritative live coding battles and carry results into XP, badges, rankings, profiles, and seasonal recaps. The frontend routes users through those experiences and calls typed API clients; the backend routes requests to feature controllers, persists product state, and uses Socket.IO for live presence and updates. The README documents several capabilities whose implementation was not sampled; those are represented at their documented subsystem level, with uncertain internal wiring omitted.

Main entry points: [`backend/src/models/user.model.ts`](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/models/user.model.ts) (User records), [`backend/src/controllers/arena.controller.ts`](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/controllers/arena.controller.ts) (Battle operations), [`backend/src/routes/auth.routes.ts`](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/routes/auth.routes.ts) (OAuth routes), [`backend/src/models/battle.model.ts`](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/models/battle.model.ts) (Battle records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Frontend experience"]
  node_frontend["App routes<br/>[routes.tsx]"]
  node_frontend_api["API clients"]
end

subgraph group_identity["Identity and insights"]
  node_auth_routes["OAuth routes<br/>[auth.routes.ts]"]
  node_auth_controller["Session auth<br/>[auth.controller.ts]"]
  node_github_sync["GitHub import<br/>[github.service.ts]"]
  node_leetcode["LeetCode sync"]
  node_dna_controller["DNA endpoint<br/>[dna.controller.ts]"]
  node_dna_logic["DNA scoring<br/>[dna.service.ts]"]
  node_dashboard["Dashboard data"]
end

subgraph group_arena["Arena and battles"]
  node_arena_routes["Arena routes<br/>[arena.routes.ts]"]
  node_arena_controller["Battle operations"]
  node_battle_questions["Question selection"]
  node_execution["Code grading"]
  node_sockets["Live events<br/>[index.ts]"]
end

subgraph group_progress["Progress and sharing"]
  node_stats["Battle rewards"]
  node_leaderboard["Rankings"]
  node_wrapped["Season recap"]
  node_share["Share previews"]
  node_user_controller["Profiles and settings<br/>[user.controller.ts]"]
end

subgraph group_platform["Backend platform"]
  node_mongo[("MongoDB")]
  node_server["HTTP server<br/>[server.ts]"]
  node_user_model["User records<br/>[user.model.ts]"]
  node_battle_model["Battle records<br/>[battle.model.ts]"]
end

node_developer(("Developer"))
node_github(("GitHub"))
node_leetcode_service(("LeetCode"))
node_judge0(("Judge0"))

node_developer -->|"uses"| node_frontend
node_frontend -->|"requests data"| node_frontend_api
node_frontend_api -->|"calls API"| node_server
node_server -->|"mounts routes"| node_auth_routes
node_server -->|"mounts routes"| node_arena_routes
node_developer -->|"starts OAuth"| node_auth_routes
node_auth_routes -->|"handles session"| node_auth_controller
node_auth_routes -->|"starts background sync"| node_github_sync
node_github_sync -.->|"imports activity"| node_github
node_github_sync -->|"updates stats"| node_user_model
node_leetcode -.->|"syncs username"| node_leetcode_service
node_dna_controller -->|"calculates DNA"| node_dna_logic
node_dna_controller -->|"reads activity"| node_user_model
node_dna_logic -->|"derives traits"| node_user_model
node_dashboard -->|"reads stats"| node_user_model
node_arena_routes -->|"dispatches requests"| node_arena_controller
node_arena_controller -->|"selects questions"| node_battle_questions
node_arena_controller -->|"runs and grades code"| node_execution
node_execution -.->|"executes tests"| node_judge0
node_arena_controller -->|"reads and writes battles"| node_battle_model
node_arena_controller -->|"reads players"| node_user_model
node_arena_controller -->|"completes battle"| node_stats
node_arena_controller -->|"emits updates"| node_sockets
node_stats -->|"awards XP"| node_user_model
node_leaderboard -->|"ranks developers"| node_user_model
node_wrapped -->|"summarizes results"| node_battle_model
node_wrapped -->|"reads profile stats"| node_user_model
node_share -->|"builds recap"| node_wrapped
node_share -->|"reads finished battles"| node_battle_model
node_share -->|"reads public profile"| node_user_model
node_user_controller -->|"updates settings"| node_user_model
node_user_model -->|"persists users"| node_mongo
node_battle_model -->|"persists battles"| node_mongo

click node_frontend "https://github.com/vivekjadhav2001/dev-arena/blob/main/frontend/src/app/routes.tsx"
click node_frontend_api "https://github.com/vivekjadhav2001/dev-arena/tree/main/frontend/src/services"
click node_auth_routes "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/routes/auth.routes.ts"
click node_auth_controller "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/controllers/auth.controller.ts"
click node_github_sync "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/services/github.service.ts"
click node_leetcode "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/services/leetcode.service.ts"
click node_dna_controller "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/controllers/dna.controller.ts"
click node_dna_logic "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/services/dna.service.ts"
click node_dashboard "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/controllers/dashboard.controller.ts"
click node_arena_routes "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/routes/arena.routes.ts"
click node_arena_controller "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/controllers/arena.controller.ts"
click node_battle_questions "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/services/battle-questions.service.ts"
click node_execution "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/services/code-execution.service.ts"
click node_sockets "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/sockets/index.ts"
click node_stats "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/services/battle-stats.service.ts"
click node_leaderboard "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/controllers/leaderboard.controller.ts"
click node_wrapped "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/controllers/wrapped.controller.ts"
click node_share "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/controllers/share.controller.ts"
click node_user_controller "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/controllers/user.controller.ts"
click node_server "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/server.ts"
click node_user_model "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/models/user.model.ts"
click node_battle_model "https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/models/battle.model.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_frontend,node_frontend_api toneBlue
class node_auth_routes,node_auth_controller,node_github_sync,node_leetcode,node_dna_controller,node_dna_logic,node_dashboard toneAmber
class node_arena_routes,node_arena_controller,node_battle_questions,node_execution,node_sockets toneMint
class node_stats,node_leaderboard,node_wrapped,node_share,node_user_controller toneRose
class node_mongo,node_server,node_user_model,node_battle_model,node_developer,node_github,node_leetcode_service,node_judge0 toneIndigo
```

## Components

### Frontend experience

- [App routes](https://github.com/vivekjadhav2001/dev-arena/blob/main/frontend/src/app/routes.tsx): `frontend/src/app/routes.tsx`
- [API clients](https://github.com/vivekjadhav2001/dev-arena/tree/main/frontend/src/services): `frontend/src/services`

### Identity and insights

- [OAuth routes](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/routes/auth.routes.ts): `backend/src/routes/auth.routes.ts`
- [Session auth](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/controllers/auth.controller.ts): `backend/src/controllers/auth.controller.ts`
- [GitHub import](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/services/github.service.ts): `backend/src/services/github.service.ts`
- [LeetCode sync](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/services/leetcode.service.ts): `backend/src/services/leetcode.service.ts`
- [DNA endpoint](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/controllers/dna.controller.ts): `backend/src/controllers/dna.controller.ts`
- [DNA scoring](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/services/dna.service.ts): `backend/src/services/dna.service.ts`
- [Dashboard data](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/controllers/dashboard.controller.ts): `backend/src/controllers/dashboard.controller.ts`

### Arena and battles

- [Arena routes](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/routes/arena.routes.ts): `backend/src/routes/arena.routes.ts`
- [Battle operations](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/controllers/arena.controller.ts): `backend/src/controllers/arena.controller.ts`
- [Question selection](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/services/battle-questions.service.ts): `backend/src/services/battle-questions.service.ts`
- [Code grading](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/services/code-execution.service.ts): `backend/src/services/code-execution.service.ts`
- [Live events](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/sockets/index.ts): `backend/src/sockets/index.ts`

### Progress and sharing

- [Battle rewards](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/services/battle-stats.service.ts): `backend/src/services/battle-stats.service.ts`
- [Rankings](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/controllers/leaderboard.controller.ts): `backend/src/controllers/leaderboard.controller.ts`
- [Season recap](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/controllers/wrapped.controller.ts): `backend/src/controllers/wrapped.controller.ts`
- [Share previews](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/controllers/share.controller.ts): `backend/src/controllers/share.controller.ts`
- [Profiles and settings](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/controllers/user.controller.ts): `backend/src/controllers/user.controller.ts`

### Backend platform

- **MongoDB**
- [HTTP server](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [User records](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/models/user.model.ts): `backend/src/models/user.model.ts`
- [Battle records](https://github.com/vivekjadhav2001/dev-arena/blob/main/backend/src/models/battle.model.ts): `backend/src/models/battle.model.ts`

### Other components

- **Developer**
- **GitHub**
- **LeetCode**
- **Judge0**

## Connections

- Developer → App routes: uses
- App routes → API clients: requests data
- API clients → HTTP server: calls API
- HTTP server → OAuth routes: mounts routes
- HTTP server → Arena routes: mounts routes
- Developer → OAuth routes: starts OAuth
- OAuth routes → Session auth: handles session
- OAuth routes → GitHub import: starts background sync
- GitHub import → GitHub: imports activity
- GitHub import → User records: updates stats
- LeetCode sync → LeetCode: syncs username
- DNA endpoint → DNA scoring: calculates DNA
- DNA endpoint → User records: reads activity
- DNA scoring → User records: derives traits
- Dashboard data → User records: reads stats
- Arena routes → Battle operations: dispatches requests
- Battle operations → Question selection: selects questions
- Battle operations → Code grading: runs and grades code
- Code grading → Judge0: executes tests
- Battle operations → Battle records: reads and writes battles
- Battle operations → User records: reads players
- Battle operations → Battle rewards: completes battle
- Battle operations → Live events: emits updates
- Battle rewards → User records: awards XP
- Rankings → User records: ranks developers
- Season recap → Battle records: summarizes results
- Season recap → User records: reads profile stats
- Share previews → Season recap: builds recap
- Share previews → Battle records: reads finished battles
- Share previews → User records: reads public profile
- Profiles and settings → User records: updates settings
- User records → MongoDB: persists users
- Battle records → MongoDB: persists battles