# ah-muzahid/codearena architecture

> Architecture diagram of the GitHub repository ah-muzahid/codearena, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ah-muzahid/codearena
- Repository: https://github.com/ah-muzahid/codearena

## Overview

1. **Overall shape**
   - This repository is a **single Next.js application plus supporting execution infrastructure** for a competitive programming platform.
   - The main product surface lives in `src/app`, while backend behavior is split across App Router API routes, domain services/controllers, background workers, Redis, MongoDB, Socket.io, and Docker-based sandboxes.

2. **Frontend/application shell**
   - The user-facing app is built with **Next.js App Router** and React.
   - Route groups cover the major product areas: landing/home, problems, contests, leaderboard, profile, feed, interview, admin, docs, and auth.
   - Most screens are composed from feature modules under `src/features/*`, with shared UI and layout primitives in `src/components` and `src/shared`.

3. **Backend entrypoint: API routes**
   - The architectural backend boundary is `src/app/api/**/route.js`.
   - These route handlers expose all core capabilities: authentication, problem browsing/solving, submissions, leaderboards, contests, interview sessions, social feed, notifications, stats, admin operations, and execution/evaluation.
   - Route handlers delegate to controllers/services rather than embedding domain logic directly.

4. **Domain layer**
   - Core business logic is organized in:
     - `src/controllers` for request-oriented orchestration
     - `src/services` for reusable domain workflows
     - `src/middlewares` for auth, rate limiting, and role checks
   - This separation matters because the same domain concepts are reused by web pages, API routes, workers, and sockets.

5. **Persistence layer**
   - The primary data store is **MongoDB**, with models under `src/models`.
   - Major persisted domains include users, problems, submissions, contests, contest participants, leaderboards, posts, reactions, notifications, interview sessions/messages/snapshots, logs, stats history, and test cases.
   - There is also a **Redis** layer used for caching, queues, rate limiting, and transient realtime/session state.

6. **Code execution and judging pipeline**
   - Code execution is isolated from the main web app.
   - Language-specific Docker executors live under `docker/executors` with separate images and runner scripts for C++, Java, JavaScript, and Python, plus a seccomp profile for sandbox hardening.
   - The API layer sends execution/evaluation work into a queue and/or execution service, and the result is then persisted and pushed back to the user.
   - This is the critical trust boundary: untrusted user code never runs in the Next.js process.

7. **Background workers and async processing**
   - Long-running or high-throughput tasks are handled out of band via worker scripts and service workers in `src/services/*.worker.js` and `scripts/*`.
   - Likely worker responsibilities include submission judging, plagiarism checks, stats updates, AI processing, leaderboard maintenance, cache warming, and notification workflows.
   - Redis is the coordination point for these asynchronous pipelines.

8. **Realtime communication**
   - The app uses **Socket.io** for realtime features, with namespaces under `src/socket/namespaces`.
   - Realtime is used especially for interview sessions, live contest/arena updates, and submission status updates.
   - WebSocket authentication is explicitly supported through `src/lib/ws-token.js`, `src/lib/socket-auth.js`, and the `/api/auth/ws-token` route.

9. **Interview subsystem**
   - Interview mode is a distinct product area with its own pages, context, hooks, socket flows, and services.
   - It includes session lifecycle management, replay/rehydration/export, AI-driven conversation flow, voice input, execution during interview, and snapshot/history persistence.
   - The subsystem combines MongoDB-backed session records with realtime sockets and AI workers, making it one of the most stateful parts of the app.

10. **AI integration**
    - AI is used beyond marketing language: there are dedicated clients and prompts in `src/lib/ai`, `src/prompts`, and interview-focused worker/services.
    - The AI path appears to power interview coaching, feedback, summarization, and evaluation rather than being a generic chat feature.
    - This creates a separate external dependency boundary for model/API calls.

11. **Contest, leaderboard, and problem-solving flows**
    - Competitive programming is a first-class domain:
      - problems, tags, submissions, reactions, and problem status in the solving flow
      - contests, registration, participation, live/final leaderboards, and results
      - global leaderboard and ranking/statistics views
    - The UI for these is split into dedicated feature modules, but all funnel through shared problem/submission/contest services and Mongo models.

12. **Social, notifications, and personalization**
    - The platform includes a feed, posts, comments, likes, follows/friends, push notifications, and user recommendations.
    - These features create cross-cutting data flow from user actions into stored social activity, notification generation, and personalized suggestions.
    - There is also browser-side push support via the service worker in `public/sw.js` and notification hooks/providers.

13. **Admin and operations surface**
    - `src/app/admin` and `src/app/api/admin` expose operational controls for contests, problems, users, metrics, logs, plagiarism, and interview moderation/flags.
    - This is a separate privileged boundary guarded by role middleware and intended for system maintenance and moderation rather than end-user workflows.

14. **Infrastructure and deployment**
    - The repo is designed for containerized deployment with `Dockerfile`, `docker-compose.yml`, `docker-compose.dev.yml`, Railway/Render configs, Redis config, and execution-service support.
    - The architecture assumes a Node.js runtime for the web app, MongoDB for durable state, Redis for coordination, Docker for sandboxing, and Socket.io/AI services for realtime and intelligent features.

Main entry points: [`src/app/api`](https://github.com/ah-muzahid/codearena/tree/development/src/app/api) (API routes), [`src/services`](https://github.com/ah-muzahid/codearena/tree/development/src/services) (Services), [`src/lib/queue.js`](https://github.com/ah-muzahid/codearena/blob/development/src/lib/queue.js) (Queue), [`src/services/interviewAI.worker.js`](https://github.com/ah-muzahid/codearena/blob/development/src/services/interviewAI.worker.js) (Interview worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Next app"]
  node_home["Home<br/>page<br/>[page.js]"]
  node_problems["Problems<br/>page<br/>[page.js]"]
  node_contests["Contests<br/>page<br/>[page.js]"]
  node_interview["Interview<br/>page<br/>[page.jsx]"]
  node_profile["Profile<br/>page<br/>[page.jsx]"]
  node_admin["Admin<br/>page<br/>[page.jsx]"]
end

subgraph group_backend["Backend"]
  node_api["API routes<br/>route layer"]
  node_controllers["Controllers<br/>orchestration"]
  node_services["Services<br/>domain workflows"]
  node_middlewares["Middleware<br/>policy"]
end

subgraph group_runtime["Execution"]
  node_queue["Queue<br/>job dispatch<br/>[queue.js]"]
  node_docker["Executors<br/>sandbox runtime<br/>[Dockerfile.cpp]"]
  node_subworker["Submission worker<br/>async worker"]
  node_intworker["Interview worker<br/>async worker"]
end

subgraph group_state["State"]
  node_models[("Models<br/>mongodb schemas")]
  node_mongo[("MongoDB<br/>database<br/>[mongodb.js]")]
  node_redis[("Redis<br/>coordination store<br/>[redis.js]")]
  node_socket(("Interview socket<br/>realtime namespace<br/>[interview.js]"))
  node_ai{{"AI client<br/>external model<br/>[groqClient.js]"}}
end

subgraph group_infra["Infra"]
  node_sw["Service worker<br/>browser support<br/>[sw.js]"]
end

node_home -->|"fetches"| node_api
node_problems -->|"solves via"| node_api
node_contests -->|"queries"| node_api
node_interview -->|"drives"| node_api
node_profile -->|"syncs"| node_api
node_admin -->|"operates on"| node_api
node_api -->|"guards"| node_middlewares
node_api -->|"delegates to"| node_controllers
node_controllers -->|"calls"| node_services
node_services -->|"persists"| node_models
node_services -->|"connects"| node_mongo
node_services -->|"coordinates"| node_redis
node_services -->|"enqueues"| node_queue
node_queue -->|"runs"| node_subworker
node_queue -->|"runs"| node_intworker
node_subworker -->|"executes in"| node_docker
node_intworker -->|"uses"| node_ai
node_intworker -->|"pushes updates"| node_socket
node_api -->|"authenticates"| node_socket
node_api -->|"notifies"| node_sw
node_services -->|"streams"| node_redis

click node_home "https://github.com/ah-muzahid/codearena/blob/development/src/app/page.js"
click node_problems "https://github.com/ah-muzahid/codearena/blob/development/src/app/problems/page.js"
click node_contests "https://github.com/ah-muzahid/codearena/blob/development/src/app/contests/page.js"
click node_interview "https://github.com/ah-muzahid/codearena/blob/development/src/app/interview/page.jsx"
click node_profile "https://github.com/ah-muzahid/codearena/blob/development/src/app/profile/page.jsx"
click node_admin "https://github.com/ah-muzahid/codearena/blob/development/src/app/admin/dashboard/page.jsx"
click node_api "https://github.com/ah-muzahid/codearena/tree/development/src/app/api"
click node_controllers "https://github.com/ah-muzahid/codearena/tree/development/src/controllers"
click node_services "https://github.com/ah-muzahid/codearena/tree/development/src/services"
click node_middlewares "https://github.com/ah-muzahid/codearena/tree/development/src/middlewares"
click node_models "https://github.com/ah-muzahid/codearena/tree/development/src/models"
click node_mongo "https://github.com/ah-muzahid/codearena/blob/development/src/lib/mongodb.js"
click node_redis "https://github.com/ah-muzahid/codearena/blob/development/src/lib/redis.js"
click node_socket "https://github.com/ah-muzahid/codearena/blob/development/src/socket/namespaces/interview.js"
click node_ai "https://github.com/ah-muzahid/codearena/blob/development/src/lib/ai/groqClient.js"
click node_queue "https://github.com/ah-muzahid/codearena/blob/development/src/lib/queue.js"
click node_docker "https://github.com/ah-muzahid/codearena/blob/development/docker/executors/Dockerfile.cpp"
click node_subworker "https://github.com/ah-muzahid/codearena/blob/development/src/services/submission.worker.js"
click node_intworker "https://github.com/ah-muzahid/codearena/blob/development/src/services/interviewAI.worker.js"
click node_sw "https://github.com/ah-muzahid/codearena/blob/development/public/sw.js"

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_home,node_problems,node_contests,node_interview,node_profile,node_admin toneBlue
class node_api,node_controllers,node_services,node_middlewares toneAmber
class node_queue,node_docker,node_subworker,node_intworker toneMint
class node_models,node_mongo,node_redis,node_socket,node_ai toneRose
class node_sw toneIndigo
```

## Components

### Next app

User-facing routes and pages

- [Home](https://github.com/ah-muzahid/codearena/blob/development/src/app/page.js): page · Landing and dashboard entry · `src/app/page.js`
- [Problems](https://github.com/ah-muzahid/codearena/blob/development/src/app/problems/page.js): page · Problem browsing and solving area · `src/app/problems/page.js`
- [Contests](https://github.com/ah-muzahid/codearena/blob/development/src/app/contests/page.js): page · Contest browsing and participation area · `src/app/contests/page.js`
- [Interview](https://github.com/ah-muzahid/codearena/blob/development/src/app/interview/page.jsx): page · Interview workspace and history · `src/app/interview/page.jsx`
- [Profile](https://github.com/ah-muzahid/codearena/blob/development/src/app/profile/page.jsx): page · User profile and settings · `src/app/profile/page.jsx`
- [Admin](https://github.com/ah-muzahid/codearena/blob/development/src/app/admin/dashboard/page.jsx): page · Privileged operations surface · `src/app/admin/dashboard/page.jsx`

### Backend

API handlers and domain orchestration

- [API routes](https://github.com/ah-muzahid/codearena/tree/development/src/app/api): route layer · App Router handlers for all core capabilities · `src/app/api`
- [Controllers](https://github.com/ah-muzahid/codearena/tree/development/src/controllers): orchestration · Request-oriented domain coordination · `src/controllers`
- [Services](https://github.com/ah-muzahid/codearena/tree/development/src/services): domain workflows · Reusable business logic and workers · `src/services`
- [Middleware](https://github.com/ah-muzahid/codearena/tree/development/src/middlewares): policy · Auth, rate limiting, and role checks · `src/middlewares`

### Execution

Sandboxing, queues, and workers

- [Queue](https://github.com/ah-muzahid/codearena/blob/development/src/lib/queue.js): job dispatch · Asynchronous job coordination · `src/lib/queue.js`
- [Executors](https://github.com/ah-muzahid/codearena/blob/development/docker/executors/Dockerfile.cpp): sandbox runtime · Containerized code execution boundary · `docker/executors/Dockerfile.cpp`
- [Submission worker](https://github.com/ah-muzahid/codearena/blob/development/src/services/submission.worker.js): async worker · Judging and submission processing · `src/services/submission.worker.js`
- [Interview worker](https://github.com/ah-muzahid/codearena/blob/development/src/services/interviewAI.worker.js): async worker · AI, execution, and summarization work · `src/services/interviewAI.worker.js`

### State

Datastores and realtime channels

- [Models](https://github.com/ah-muzahid/codearena/tree/development/src/models): mongodb schemas · Durable domain records · `src/models`
- [MongoDB](https://github.com/ah-muzahid/codearena/blob/development/src/lib/mongodb.js): database · Primary persistent store · `src/lib/mongodb.js`
- [Redis](https://github.com/ah-muzahid/codearena/blob/development/src/lib/redis.js): coordination store · Cache, queues, and transient state · `src/lib/redis.js`
- [Interview socket](https://github.com/ah-muzahid/codearena/blob/development/src/socket/namespaces/interview.js): realtime namespace · Realtime interview channel · `src/socket/namespaces/interview.js`
- [AI client](https://github.com/ah-muzahid/codearena/blob/development/src/lib/ai/groqClient.js): external model · Model access for interview and feedback flows · `src/lib/ai/groqClient.js`

### Infra

Deployment and browser-side support

- [Service worker](https://github.com/ah-muzahid/codearena/blob/development/public/sw.js): browser support · Push notifications and client-side updates · `public/sw.js`

## Connections

- Home → API routes: fetches · Pages load application data through route handlers
- Problems → API routes: solves via · Problem screens submit and retrieve judge data
- Contests → API routes: queries · Contest screens consume contest and leaderboard APIs
- Interview → API routes: drives · Interview pages create and manage sessions
- Profile → API routes: syncs · Profile and settings screens read/write user state
- Admin → API routes: operates on · Admin screens call privileged ops endpoints
- API routes → Middleware: guards · API handlers enforce auth and role policies
- API routes → Controllers: delegates to · Route handlers hand off orchestration
- Controllers → Services: calls · Controllers compose reusable workflows
- Services → Models: persists · Business logic reads and writes Mongo models
- Services → MongoDB: connects · MongoDB is the durable backing store
- Services → Redis: coordinates · Caching, rate limits, and transient state
- Services → Queue: enqueues · Long-running work is dispatched asynchronously
- Queue → Submission worker: runs · Submission jobs are processed out of band
- Queue → Interview worker: runs · Interview jobs are processed out of band
- Submission worker → Executors: executes in · Untrusted code runs inside sandboxed containers
- Interview worker → AI client: uses · Interview flows call model APIs and prompts
- Interview worker → Interview socket: pushes updates · Realtime interview state is broadcast to clients
- API routes → Interview socket: authenticates · WebSocket token and socket auth support realtime access
- API routes → Service worker: notifies · Push notification flows are supported by the browser worker
- Services → Redis: streams · Workers and services coordinate through Redis