# srujanbhirud/codeclash architecture

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

- Interactive diagram: https://gitdiagram.com/srujanbhirud/codeclash
- Repository: https://github.com/srujanbhirud/codeclash

## Overview

CodeClash is a browser-based platform for live coding and quiz contests, practice, problem authoring, and contest administration. Participants enter a contest or practice problem, submit code through the browser/API, and receive a verdict from a separate containerized judge; contest data is stored in MongoDB and Redis carries judge work. Setters can author problems and request test hardening, which runs asynchronously and produces proposals for approval. The graph preserves documented contest, scoring, integrity, and account capabilities. Several server routes and domain implementations were not sampled, so their internal call paths are not asserted.

Main entry points: [`server/src/http/app.ts`](https://github.com/srujanbhirud/codeclash/blob/main/server/src/http/app.ts) (HTTP API), [`client/src/App.tsx`](https://github.com/srujanbhirud/codeclash/blob/main/client/src/App.tsx) (CodeClash UI), [`judge/src/index.ts`](https://github.com/srujanbhirud/codeclash/blob/main/judge/src/index.ts) (Judge queue worker), [`agent/src/worker.ts`](https://github.com/srujanbhirud/codeclash/blob/main/agent/src/worker.ts) (Hardening worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser experience"]
  node_browser["CodeClash UI<br/>[App.tsx]"]
  node_auth_ui["Account access<br/>[Auth.tsx]"]
  node_contest_ui["Contest room<br/>[ContestRoom.tsx]"]
  node_problem_ui["Problemset<br/>[Problemset.tsx]"]
  node_author_ui["Problem authoring<br/>[Authoring.tsx]"]
  node_control_ui["Contest control<br/>[Control.tsx]"]
  node_integrity_ui["Integrity tools<br/>[Integrity.tsx]"]
  node_hardening_ui["Hardening review<br/>[Hardening.tsx]"]
end

subgraph group_api["Platform API"]
  node_http_api["HTTP API<br/>[app.ts]"]
  node_accounts["Accounts and auth<br/>[auth.ts]"]
  node_problem_domain["Problem lifecycle<br/>[problems.ts]"]
  node_contest_domain["Contest lifecycle<br/>[contests.ts]"]
  node_registration["Seat registration<br/>[registration.ts]"]
  node_scoring["Scoring and ratings<br/>[scoring.ts]"]
  node_similarity["Submission integrity<br/>[similarity.ts]"]
end

subgraph group_judge["Submission judging"]
  node_judge_worker["Judge queue worker<br/>[index.ts]"]
  node_sandbox["Docker sandbox<br/>[runner.ts]"]
  node_verdict["Verdict decisions<br/>[decide.ts]"]
end

subgraph group_hardening["Test hardening"]
  node_agent_worker["Hardening worker<br/>[worker.ts]"]
  node_hardening_pipeline["Mutation and attack analysis<br/>[pipeline.ts]"]
  node_mutations["Mutant generation<br/>[mutate.ts]"]
  node_ai_provider["Optional AI planning<br/>[providers.ts]"]
end

subgraph group_shared["Shared capabilities"]
  node_shared_spec["Input specification<br/>[spec.ts]"]
  node_shared_rules["Shared contest rules<br/>[index.ts]"]
end

node_participant(("Participant"))
node_setter(("Setter"))
node_organiser(("Organiser"))
node_mongo[("MongoDB")]
node_redis["Redis streams"]
node_docker["Docker runtime"]

node_participant -->|"uses"| node_browser
node_setter -->|"authors tests"| node_browser
node_organiser -->|"manages rounds"| node_browser
node_browser -->|"routes to"| node_auth_ui
node_browser -->|"routes to"| node_contest_ui
node_browser -->|"routes to"| node_problem_ui
node_browser -->|"calls"| node_http_api
node_author_ui -->|"saves problems"| node_http_api
node_hardening_ui -->|"requests review"| node_http_api
node_http_api -.->|"authenticates"| node_accounts
node_http_api -.->|"handles problem work"| node_problem_domain
node_http_api -.->|"handles contest work"| node_contest_domain
node_http_api -.->|"manages seats"| node_registration
node_http_api -.->|"scores contests"| node_scoring
node_http_api -.->|"checks integrity"| node_similarity
node_http_api -->|"stores platform data"| node_mongo
node_http_api -->|"queues judge work"| node_redis
node_judge_worker -->|"consumes jobs"| node_redis
node_judge_worker -->|"claims and saves submissions"| node_mongo
node_judge_worker -->|"runs submissions"| node_sandbox
node_sandbox -->|"executes in"| node_docker
node_judge_worker -->|"evaluates cases"| node_verdict
node_verdict -->|"returns verdict"| node_judge_worker
node_agent_worker -->|"consumes hardening jobs"| node_redis
node_agent_worker -->|"runs analysis"| node_hardening_pipeline
node_agent_worker -->|"stores proposals"| node_mongo
node_hardening_pipeline -->|"generates mutants"| node_mutations
node_hardening_pipeline -->|"validates inputs"| node_shared_spec
node_agent_worker -->|"configures optional AI"| node_ai_provider
node_hardening_pipeline -.->|"runs candidate code"| node_judge_worker
node_problem_domain -->|"uses shared rules"| node_shared_rules

click node_browser "https://github.com/srujanbhirud/codeclash/blob/main/client/src/App.tsx"
click node_auth_ui "https://github.com/srujanbhirud/codeclash/blob/main/client/src/pages/Auth.tsx"
click node_contest_ui "https://github.com/srujanbhirud/codeclash/blob/main/client/src/pages/ContestRoom.tsx"
click node_problem_ui "https://github.com/srujanbhirud/codeclash/blob/main/client/src/pages/Problemset.tsx"
click node_author_ui "https://github.com/srujanbhirud/codeclash/blob/main/client/src/pages/Authoring.tsx"
click node_control_ui "https://github.com/srujanbhirud/codeclash/blob/main/client/src/pages/Control.tsx"
click node_integrity_ui "https://github.com/srujanbhirud/codeclash/blob/main/client/src/pages/Integrity.tsx"
click node_hardening_ui "https://github.com/srujanbhirud/codeclash/blob/main/client/src/pages/Hardening.tsx"
click node_http_api "https://github.com/srujanbhirud/codeclash/blob/main/server/src/http/app.ts"
click node_accounts "https://github.com/srujanbhirud/codeclash/blob/main/server/src/http/auth.ts"
click node_problem_domain "https://github.com/srujanbhirud/codeclash/blob/main/server/src/domain/problems.ts"
click node_contest_domain "https://github.com/srujanbhirud/codeclash/blob/main/server/src/domain/contests.ts"
click node_registration "https://github.com/srujanbhirud/codeclash/blob/main/server/src/domain/registration.ts"
click node_scoring "https://github.com/srujanbhirud/codeclash/blob/main/server/src/domain/scoring.ts"
click node_similarity "https://github.com/srujanbhirud/codeclash/blob/main/server/src/domain/similarity.ts"
click node_judge_worker "https://github.com/srujanbhirud/codeclash/blob/main/judge/src/index.ts"
click node_sandbox "https://github.com/srujanbhirud/codeclash/blob/main/judge/src/runner.ts"
click node_verdict "https://github.com/srujanbhirud/codeclash/blob/main/judge/src/decide.ts"
click node_agent_worker "https://github.com/srujanbhirud/codeclash/blob/main/agent/src/worker.ts"
click node_hardening_pipeline "https://github.com/srujanbhirud/codeclash/blob/main/agent/src/engine/pipeline.ts"
click node_mutations "https://github.com/srujanbhirud/codeclash/blob/main/agent/src/engine/mutate.ts"
click node_ai_provider "https://github.com/srujanbhirud/codeclash/blob/main/agent/src/providers.ts"
click node_shared_spec "https://github.com/srujanbhirud/codeclash/blob/main/packages/shared/src/spec.ts"
click node_shared_rules "https://github.com/srujanbhirud/codeclash/blob/main/packages/shared/src/index.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_browser,node_auth_ui,node_contest_ui,node_problem_ui,node_author_ui,node_control_ui,node_integrity_ui,node_hardening_ui toneBlue
class node_http_api,node_accounts,node_problem_domain,node_contest_domain,node_registration,node_scoring,node_similarity,node_mongo,node_redis toneAmber
class node_judge_worker,node_sandbox,node_verdict toneMint
class node_agent_worker,node_hardening_pipeline,node_mutations,node_ai_provider toneRose
class node_shared_spec,node_shared_rules,node_participant,node_setter,node_organiser,node_docker toneIndigo
```

## Components

### Browser experience

- [CodeClash UI](https://github.com/srujanbhirud/codeclash/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Account access](https://github.com/srujanbhirud/codeclash/blob/main/client/src/pages/Auth.tsx): `client/src/pages/Auth.tsx`
- [Contest room](https://github.com/srujanbhirud/codeclash/blob/main/client/src/pages/ContestRoom.tsx): `client/src/pages/ContestRoom.tsx`
- [Problemset](https://github.com/srujanbhirud/codeclash/blob/main/client/src/pages/Problemset.tsx): `client/src/pages/Problemset.tsx`
- [Problem authoring](https://github.com/srujanbhirud/codeclash/blob/main/client/src/pages/Authoring.tsx): `client/src/pages/Authoring.tsx`
- [Contest control](https://github.com/srujanbhirud/codeclash/blob/main/client/src/pages/Control.tsx): `client/src/pages/Control.tsx`
- [Integrity tools](https://github.com/srujanbhirud/codeclash/blob/main/client/src/pages/Integrity.tsx): `client/src/pages/Integrity.tsx`
- [Hardening review](https://github.com/srujanbhirud/codeclash/blob/main/client/src/pages/Hardening.tsx): `client/src/pages/Hardening.tsx`

### Platform API

- [HTTP API](https://github.com/srujanbhirud/codeclash/blob/main/server/src/http/app.ts): `server/src/http/app.ts`
- [Accounts and auth](https://github.com/srujanbhirud/codeclash/blob/main/server/src/http/auth.ts): `server/src/http/auth.ts`
- [Problem lifecycle](https://github.com/srujanbhirud/codeclash/blob/main/server/src/domain/problems.ts): `server/src/domain/problems.ts`
- [Contest lifecycle](https://github.com/srujanbhirud/codeclash/blob/main/server/src/domain/contests.ts): `server/src/domain/contests.ts`
- [Seat registration](https://github.com/srujanbhirud/codeclash/blob/main/server/src/domain/registration.ts): `server/src/domain/registration.ts`
- [Scoring and ratings](https://github.com/srujanbhirud/codeclash/blob/main/server/src/domain/scoring.ts): `server/src/domain/scoring.ts`
- [Submission integrity](https://github.com/srujanbhirud/codeclash/blob/main/server/src/domain/similarity.ts): `server/src/domain/similarity.ts`

### Submission judging

- [Judge queue worker](https://github.com/srujanbhirud/codeclash/blob/main/judge/src/index.ts): `judge/src/index.ts`
- [Docker sandbox](https://github.com/srujanbhirud/codeclash/blob/main/judge/src/runner.ts): `judge/src/runner.ts`
- [Verdict decisions](https://github.com/srujanbhirud/codeclash/blob/main/judge/src/decide.ts): `judge/src/decide.ts`

### Test hardening

- [Hardening worker](https://github.com/srujanbhirud/codeclash/blob/main/agent/src/worker.ts): `agent/src/worker.ts`
- [Mutation and attack analysis](https://github.com/srujanbhirud/codeclash/blob/main/agent/src/engine/pipeline.ts): `agent/src/engine/pipeline.ts`
- [Mutant generation](https://github.com/srujanbhirud/codeclash/blob/main/agent/src/engine/mutate.ts): `agent/src/engine/mutate.ts`
- [Optional AI planning](https://github.com/srujanbhirud/codeclash/blob/main/agent/src/providers.ts): `agent/src/providers.ts`

### Shared capabilities

- [Input specification](https://github.com/srujanbhirud/codeclash/blob/main/packages/shared/src/spec.ts): `packages/shared/src/spec.ts`
- [Shared contest rules](https://github.com/srujanbhirud/codeclash/blob/main/packages/shared/src/index.ts): `packages/shared/src/index.ts`

### Other components

- **Participant**
- **Setter**
- **Organiser**
- **MongoDB**
- **Redis streams**
- **Docker runtime**

## Connections

- Participant → CodeClash UI: uses (evidence: `README.md`)
- Setter → CodeClash UI: authors tests (evidence: `README.md`)
- Organiser → CodeClash UI: manages rounds (evidence: `README.md`)
- CodeClash UI → Account access: routes to (evidence: `client/src/App.tsx`)
- CodeClash UI → Contest room: routes to (evidence: `client/src/App.tsx`)
- CodeClash UI → Problemset: routes to (evidence: `client/src/App.tsx`)
- CodeClash UI → HTTP API: calls (evidence: `README.md`)
- Problem authoring → HTTP API: saves problems (evidence: `client/src/pages/Authoring.tsx`)
- Hardening review → HTTP API: requests review (evidence: `README.md`)
- HTTP API → Accounts and auth: authenticates
- HTTP API → Problem lifecycle: handles problem work
- HTTP API → Contest lifecycle: handles contest work
- HTTP API → Seat registration: manages seats
- HTTP API → Scoring and ratings: scores contests
- HTTP API → Submission integrity: checks integrity
- HTTP API → MongoDB: stores platform data (evidence: `README.md`)
- HTTP API → Redis streams: queues judge work (evidence: `README.md`)
- Judge queue worker → Redis streams: consumes jobs (evidence: `README.md`)
- Judge queue worker → MongoDB: claims and saves submissions (evidence: `judge/src/index.ts`)
- Judge queue worker → Docker sandbox: runs submissions (evidence: `judge/src/index.ts`)
- Docker sandbox → Docker runtime: executes in (evidence: `README.md`)
- Judge queue worker → Verdict decisions: evaluates cases (evidence: `judge/src/index.ts`)
- Verdict decisions → Judge queue worker: returns verdict (evidence: `judge/src/index.ts`)
- Hardening worker → Redis streams: consumes hardening jobs
- Hardening worker → Mutation and attack analysis: runs analysis (evidence: `agent/src/worker.ts`)
- Hardening worker → MongoDB: stores proposals (evidence: `agent/src/worker.ts`)
- Mutation and attack analysis → Mutant generation: generates mutants (evidence: `agent/src/engine/pipeline.ts`)
- Mutation and attack analysis → Input specification: validates inputs (evidence: `agent/src/engine/pipeline.ts`)
- Hardening worker → Optional AI planning: configures optional AI (evidence: `agent/src/worker.ts`)
- Mutation and attack analysis → Judge queue worker: runs candidate code
- Problem lifecycle → Shared contest rules: uses shared rules (evidence: `server/src/domain/problems.ts`)