# souvikkundu0901/coding-arena architecture

> Architecture diagram of the GitHub repository souvikkundu0901/coding-arena, 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/souvikkundu0901/coding-arena
- Repository: https://github.com/souvikkundu0901/coding-arena

## Overview

Codess is a real-time competitive coding platform: players authenticate, enter ranked matchmaking or challenge a friend, solve a shared problem, and receive evaluated results and rating updates. Social features and account preferences support that core loop. The graph combines the supplied service excerpts with README-documented capabilities; unsampled subsystems use only their existing enclosing paths, and their internal wiring is not inferred.

Main entry points: [`src/main/java/com/codingarena/submission/service/SubmissionService.java`](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/submission/service/SubmissionService.java) (Submission evaluation), [`src/main/resources/static/js`](https://github.com/souvikkundu0901/coding-arena/tree/main/src/main/resources/static/js) (Web client), [`src/main/java/com/codingarena/auth/service/AuthService.java`](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/auth/service/AuthService.java) (Auth service), [`src/main/java/com/codingarena/challenge/service/ChallengeService.java`](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/challenge/service/ChallengeService.java) (Friend challenges)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Player interface"]
  node_browser["Web client"]
end

subgraph group_identity["Identity and social"]
  node_auth_api["Auth API"]
  node_auth_service["Auth service<br/>[AuthService.java]"]
  node_users[("User accounts")]
  node_captcha["CAPTCHA verification"]
  node_friendship["Friend relations"]
  node_friend_store[("Friend records")]
end

subgraph group_match["Match lifecycle"]
  node_challenge["Friend challenges"]
  node_challenge_store[("Challenge records")]
  node_queue_api["Queue API"]
  node_matchmaking["Matchmaking"]
  node_match_creation["Match creation"]
  node_match_service["Match lifecycle<br/>[MatchService.java]"]
  node_match_store[("Match records")]
  node_match_sessions["Disconnect and expiry"]
end

subgraph group_evaluation["Code evaluation"]
  node_submission_api["Submission API"]
  node_submission_service["Submission evaluation"]
  node_judge_client["Judge0 client<br/>[Judge0Client.java]"]
  node_testcases[("Problem tests")]
  node_submissions[("Submission records")]
  node_elo["Elo ratings<br/>[EloService.java]"]
end

subgraph group_platform["Runtime infrastructure"]
  node_redis[("Redis queue")]
  node_websocket["Live events"]
  node_postgres[("PostgreSQL")]
end

node_player(("Player"))
node_recaptcha["Google reCAPTCHA"]
node_judge0["Judge0 execution"]

node_player -->|"uses"| node_browser
node_browser -->|"authenticates"| node_auth_api
node_auth_api -->|"handles auth"| node_auth_service
node_auth_service -->|"reads and writes"| node_users
node_auth_service -->|"verifies registration"| node_captcha
node_captcha -.->|"validates token"| node_recaptcha
node_browser -->|"manages friends"| node_friendship
node_friendship -->|"reads and writes"| node_friend_store
node_browser -->|"sends challenge"| node_challenge
node_challenge -->|"reads and writes"| node_challenge_store
node_challenge -->|"creates match"| node_match_creation
node_browser -->|"joins queue"| node_queue_api
node_queue_api -->|"manages queue"| node_matchmaking
node_matchmaking -->|"pairs players"| node_redis
node_matchmaking -->|"loads players"| node_users
node_matchmaking -->|"creates match"| node_match_creation
node_match_creation -->|"persists match"| node_match_store
node_browser -->|"reads or forfeits"| node_match_service
node_match_service -->|"reads and updates"| node_match_store
node_match_service -->|"broadcasts match events"| node_websocket
node_match_sessions -->|"expires or forfeits"| node_match_service
node_browser -->|"submits code"| node_submission_api
node_submission_api -->|"evaluates submission"| node_submission_service
node_submission_service -->|"loads match"| node_match_store
node_submission_service -->|"loads test cases"| node_testcases
node_submission_service -->|"executes code"| node_judge_client
node_judge_client -->|"sends code"| node_judge0
node_submission_service -->|"stores results"| node_submissions
node_submission_service -->|"updates ratings"| node_elo
node_submission_service -->|"publishes results"| node_websocket
node_match_creation -->|"stores match data"| node_postgres
node_auth_service -->|"stores account data"| node_postgres
node_friendship -->|"stores friendships"| node_postgres
node_challenge -->|"stores challenges"| node_postgres
node_submission_service -->|"stores submissions"| node_postgres

click node_browser "https://github.com/souvikkundu0901/coding-arena/tree/main/src/main/resources/static/js"
click node_auth_api "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/auth/controller/AuthController.java"
click node_auth_service "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/auth/service/AuthService.java"
click node_users "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/auth/repository/UserRepository.java"
click node_captcha "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/auth/service/DefaultCaptchaService.java"
click node_friendship "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/friendship/service/FriendshipService.java"
click node_friend_store "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/friendship/repository/FriendshipRepository.java"
click node_challenge "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/challenge/service/ChallengeService.java"
click node_challenge_store "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/challenge/repository/ChallengeRepository.java"
click node_queue_api "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/matchmaking/controller/MatchmakingController.java"
click node_matchmaking "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/matchmaking/service/MatchmakingService.java"
click node_match_creation "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/match/service/MatchCreationService.java"
click node_match_service "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/match/service/MatchService.java"
click node_match_store "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/match/repository/MatchRepository.java"
click node_match_sessions "https://github.com/souvikkundu0901/coding-arena/tree/main/src/main/java/com/codingarena/match/service"
click node_submission_api "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/submission/controller/SubmissionController.java"
click node_submission_service "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/submission/service/SubmissionService.java"
click node_judge_client "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/submission/client/Judge0Client.java"
click node_testcases "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/match/repository/TestCaseRepository.java"
click node_submissions "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/submission/repository/SubmissionRepository.java"
click node_elo "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/submission/service/EloService.java"
click node_websocket "https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/config/WebSocketConfig.java"

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_browser toneBlue
class node_auth_api,node_auth_service,node_users,node_captcha,node_friendship,node_friend_store toneAmber
class node_challenge,node_challenge_store,node_queue_api,node_matchmaking,node_match_creation,node_match_service,node_match_store,node_match_sessions toneMint
class node_submission_api,node_submission_service,node_judge_client,node_testcases,node_submissions,node_elo toneRose
class node_redis,node_websocket,node_postgres,node_player,node_recaptcha,node_judge0 toneIndigo
```

## Components

### Player interface

- [Web client](https://github.com/souvikkundu0901/coding-arena/tree/main/src/main/resources/static/js): `src/main/resources/static/js`

### Identity and social

- [Auth API](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/auth/controller/AuthController.java): `src/main/java/com/codingarena/auth/controller/AuthController.java`
- [Auth service](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/auth/service/AuthService.java): `src/main/java/com/codingarena/auth/service/AuthService.java`
- [User accounts](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/auth/repository/UserRepository.java): `src/main/java/com/codingarena/auth/repository/UserRepository.java`
- [CAPTCHA verification](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/auth/service/DefaultCaptchaService.java): `src/main/java/com/codingarena/auth/service/DefaultCaptchaService.java`
- [Friend relations](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/friendship/service/FriendshipService.java): `src/main/java/com/codingarena/friendship/service/FriendshipService.java`
- [Friend records](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/friendship/repository/FriendshipRepository.java): `src/main/java/com/codingarena/friendship/repository/FriendshipRepository.java`

### Match lifecycle

- [Friend challenges](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/challenge/service/ChallengeService.java): `src/main/java/com/codingarena/challenge/service/ChallengeService.java`
- [Challenge records](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/challenge/repository/ChallengeRepository.java): `src/main/java/com/codingarena/challenge/repository/ChallengeRepository.java`
- [Queue API](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/matchmaking/controller/MatchmakingController.java): `src/main/java/com/codingarena/matchmaking/controller/MatchmakingController.java`
- [Matchmaking](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/matchmaking/service/MatchmakingService.java): `src/main/java/com/codingarena/matchmaking/service/MatchmakingService.java`
- [Match creation](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/match/service/MatchCreationService.java): `src/main/java/com/codingarena/match/service/MatchCreationService.java`
- [Match lifecycle](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/match/service/MatchService.java): `src/main/java/com/codingarena/match/service/MatchService.java`
- [Match records](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/match/repository/MatchRepository.java): `src/main/java/com/codingarena/match/repository/MatchRepository.java`
- [Disconnect and expiry](https://github.com/souvikkundu0901/coding-arena/tree/main/src/main/java/com/codingarena/match/service): `src/main/java/com/codingarena/match/service`

### Code evaluation

- [Submission API](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/submission/controller/SubmissionController.java): `src/main/java/com/codingarena/submission/controller/SubmissionController.java`
- [Submission evaluation](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/submission/service/SubmissionService.java): `src/main/java/com/codingarena/submission/service/SubmissionService.java`
- [Judge0 client](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/submission/client/Judge0Client.java): `src/main/java/com/codingarena/submission/client/Judge0Client.java`
- [Problem tests](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/match/repository/TestCaseRepository.java): `src/main/java/com/codingarena/match/repository/TestCaseRepository.java`
- [Submission records](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/submission/repository/SubmissionRepository.java): `src/main/java/com/codingarena/submission/repository/SubmissionRepository.java`
- [Elo ratings](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/submission/service/EloService.java): `src/main/java/com/codingarena/submission/service/EloService.java`

### Runtime infrastructure

- **Redis queue**
- [Live events](https://github.com/souvikkundu0901/coding-arena/blob/main/src/main/java/com/codingarena/config/WebSocketConfig.java): `src/main/java/com/codingarena/config/WebSocketConfig.java`
- **PostgreSQL**

### Other components

- **Player**
- **Google reCAPTCHA**
- **Judge0 execution**

## Connections

- Player → Web client: uses
- Web client → Auth API: authenticates
- Auth API → Auth service: handles auth
- Auth service → User accounts: reads and writes
- Auth service → CAPTCHA verification: verifies registration
- CAPTCHA verification → Google reCAPTCHA: validates token
- Web client → Friend relations: manages friends
- Friend relations → Friend records: reads and writes
- Web client → Friend challenges: sends challenge
- Friend challenges → Challenge records: reads and writes
- Friend challenges → Match creation: creates match
- Web client → Queue API: joins queue
- Queue API → Matchmaking: manages queue
- Matchmaking → Redis queue: pairs players
- Matchmaking → User accounts: loads players
- Matchmaking → Match creation: creates match
- Match creation → Match records: persists match
- Web client → Match lifecycle: reads or forfeits
- Match lifecycle → Match records: reads and updates
- Match lifecycle → Live events: broadcasts match events
- Disconnect and expiry → Match lifecycle: expires or forfeits
- Web client → Submission API: submits code
- Submission API → Submission evaluation: evaluates submission
- Submission evaluation → Match records: loads match
- Submission evaluation → Problem tests: loads test cases
- Submission evaluation → Judge0 client: executes code
- Judge0 client → Judge0 execution: sends code
- Submission evaluation → Submission records: stores results
- Submission evaluation → Elo ratings: updates ratings
- Submission evaluation → Live events: publishes results
- Match creation → PostgreSQL: stores match data
- Auth service → PostgreSQL: stores account data
- Friend relations → PostgreSQL: stores friendships
- Friend challenges → PostgreSQL: stores challenges
- Submission evaluation → PostgreSQL: stores submissions