# kavya0224/codex architecture

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

- Interactive diagram: https://gitdiagram.com/kavya0224/codex
- Repository: https://github.com/kavya0224/codex

## Overview

CodeX is an AI coding assistant: users submit a problem and optional tests, then receive generated code, execution results, a verdict, retries, and metrics; they can also request a structured explanation. The backend orchestrates planning, generation, sandboxed execution, validation, and debugging, while the React UI presents results and run history. The README documents public/hidden test suites and telemetry; sampled source shows the orchestration and key calls. Some frontend behavior and supporting subsystem internals were not sampled, so those connections rely on README documentation.

Main entry points: [`backend/src/services/solveService.js`](https://github.com/kavya0224/codex/blob/main/backend/src/services/solveService.js) (Solve orchestrator), [`backend/src/llm/groqClient.js`](https://github.com/kavya0224/codex/blob/main/backend/src/llm/groqClient.js) (Groq LLM), [`backend/src/execution/codeExecutor.js`](https://github.com/kavya0224/codex/blob/main/backend/src/execution/codeExecutor.js) (Sandbox executor), [`frontend/src/App.jsx`](https://github.com/kavya0224/codex/blob/main/frontend/src/App.jsx) (React workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_app["React workspace<br/>[App.jsx]"]
end

subgraph group_api["API entry"]
  node_server["Express server<br/>[server.js]"]
  node_solve_route["Solve route<br/>[solveRoute.js]"]
  node_explain_route["Explain route<br/>[explainRoute.js]"]
  node_solve_controller["Solve handler<br/>[solveController.js]"]
  node_explain_controller["Explain handler"]
end

subgraph group_workflow["Solve workflow"]
  node_solve_service["Solve orchestrator<br/>[solveService.js]"]
  node_explain_service["Explanation service<br/>[explainService.js]"]
  node_planner["Problem planner<br/>[plannerAgent.js]"]
  node_generator["Code generator"]
  node_debugger["Debug agent<br/>[debugAgent.js]"]
end

subgraph group_runtime["Execution and checks"]
  node_file_manager["Workspace files<br/>[fileManager.js]"]
  node_executor["Sandbox executor<br/>[codeExecutor.js]"]
  node_test_runner["Test case runner<br/>[testCaseRunner.js]"]
  node_validator["Output validator<br/>[outputValidator.js]"]
end

subgraph group_support["AI and telemetry"]
  node_groq["Groq LLM<br/>[groqClient.js]"]
  node_sanitizer["Code sanitizer<br/>[codeSanitizer.js]"]
  node_telemetry["Run telemetry<br/>[executionLogger.js]"]
  node_performance["Performance tracker"]
end

node_user(("Problem solver"))
node_groq_service{{"Groq API"}}
node_docker{{"Docker sandbox"}}

node_user -->|"submits problem"| node_app
node_app -->|"POST /solve"| node_solve_route
node_app -->|"POST /explain"| node_explain_route
node_server -->|"mounts route"| node_solve_route
node_server -->|"mounts route"| node_explain_route
node_solve_route -->|"routes request"| node_solve_controller
node_explain_route -->|"routes request"| node_explain_controller
node_solve_controller -->|"calls"| node_solve_service
node_explain_controller -->|"calls"| node_explain_service
node_solve_service -->|"creates plan"| node_planner
node_solve_service -->|"generates code"| node_generator
node_solve_service -->|"repairs failures"| node_debugger
node_generator -->|"requests generation"| node_groq
node_debugger -.->|"requests fixes"| node_groq
node_explain_service -->|"requests explanation"| node_groq
node_groq -->|"calls model"| node_groq_service
node_solve_service -->|"saves code"| node_file_manager
node_executor -->|"writes input"| node_file_manager
node_solve_service -->|"executes code"| node_executor
node_executor -->|"runs container"| node_docker
node_solve_service -->|"runs test suites"| node_test_runner
node_test_runner -->|"executes cases"| node_executor
node_test_runner -->|"checks outputs"| node_validator
node_solve_service -->|"validates result"| node_validator
node_groq -->|"sanitizes code"| node_sanitizer
node_solve_service -->|"records stages"| node_telemetry
node_solve_service -->|"tracks timings"| node_performance

click node_app "https://github.com/kavya0224/codex/blob/main/frontend/src/App.jsx"
click node_server "https://github.com/kavya0224/codex/blob/main/backend/src/server.js"
click node_solve_route "https://github.com/kavya0224/codex/blob/main/backend/src/routes/solveRoute.js"
click node_explain_route "https://github.com/kavya0224/codex/blob/main/backend/src/routes/explainRoute.js"
click node_solve_controller "https://github.com/kavya0224/codex/blob/main/backend/src/controllers/solveController.js"
click node_explain_controller "https://github.com/kavya0224/codex/blob/main/backend/src/controllers/explainController.js"
click node_solve_service "https://github.com/kavya0224/codex/blob/main/backend/src/services/solveService.js"
click node_explain_service "https://github.com/kavya0224/codex/blob/main/backend/src/services/explainService.js"
click node_planner "https://github.com/kavya0224/codex/blob/main/backend/src/agents/plannerAgent.js"
click node_generator "https://github.com/kavya0224/codex/blob/main/backend/src/agents/codeGeneratorAgent.js"
click node_debugger "https://github.com/kavya0224/codex/blob/main/backend/src/agents/debugAgent.js"
click node_groq "https://github.com/kavya0224/codex/blob/main/backend/src/llm/groqClient.js"
click node_file_manager "https://github.com/kavya0224/codex/blob/main/backend/src/execution/fileManager.js"
click node_executor "https://github.com/kavya0224/codex/blob/main/backend/src/execution/codeExecutor.js"
click node_docker "https://github.com/kavya0224/codex/tree/main/backend/sandbox"
click node_test_runner "https://github.com/kavya0224/codex/blob/main/backend/src/utils/testCaseRunner.js"
click node_validator "https://github.com/kavya0224/codex/blob/main/backend/src/utils/outputValidator.js"
click node_sanitizer "https://github.com/kavya0224/codex/blob/main/backend/src/utils/codeSanitizer.js"
click node_telemetry "https://github.com/kavya0224/codex/blob/main/backend/src/utils/executionLogger.js"
click node_performance "https://github.com/kavya0224/codex/blob/main/backend/src/utils/performanceTracker.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_app toneBlue
class node_server,node_solve_route,node_explain_route,node_solve_controller,node_explain_controller toneAmber
class node_solve_service,node_explain_service,node_planner,node_generator,node_debugger,node_groq_service toneMint
class node_file_manager,node_executor,node_test_runner,node_validator toneRose
class node_groq,node_sanitizer,node_telemetry,node_performance,node_user toneIndigo
class node_docker toneTeal
```

## Components

### User interface

- [React workspace](https://github.com/kavya0224/codex/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### API entry

- [Express server](https://github.com/kavya0224/codex/blob/main/backend/src/server.js): `backend/src/server.js`
- [Solve route](https://github.com/kavya0224/codex/blob/main/backend/src/routes/solveRoute.js): `backend/src/routes/solveRoute.js`
- [Explain route](https://github.com/kavya0224/codex/blob/main/backend/src/routes/explainRoute.js): `backend/src/routes/explainRoute.js`
- [Solve handler](https://github.com/kavya0224/codex/blob/main/backend/src/controllers/solveController.js): `backend/src/controllers/solveController.js`
- [Explain handler](https://github.com/kavya0224/codex/blob/main/backend/src/controllers/explainController.js): `backend/src/controllers/explainController.js`

### Solve workflow

- [Solve orchestrator](https://github.com/kavya0224/codex/blob/main/backend/src/services/solveService.js): `backend/src/services/solveService.js`
- [Explanation service](https://github.com/kavya0224/codex/blob/main/backend/src/services/explainService.js): `backend/src/services/explainService.js`
- [Problem planner](https://github.com/kavya0224/codex/blob/main/backend/src/agents/plannerAgent.js): `backend/src/agents/plannerAgent.js`
- [Code generator](https://github.com/kavya0224/codex/blob/main/backend/src/agents/codeGeneratorAgent.js): `backend/src/agents/codeGeneratorAgent.js`
- [Debug agent](https://github.com/kavya0224/codex/blob/main/backend/src/agents/debugAgent.js): `backend/src/agents/debugAgent.js`

### Execution and checks

- [Workspace files](https://github.com/kavya0224/codex/blob/main/backend/src/execution/fileManager.js): `backend/src/execution/fileManager.js`
- [Sandbox executor](https://github.com/kavya0224/codex/blob/main/backend/src/execution/codeExecutor.js): `backend/src/execution/codeExecutor.js`
- [Test case runner](https://github.com/kavya0224/codex/blob/main/backend/src/utils/testCaseRunner.js): `backend/src/utils/testCaseRunner.js`
- [Output validator](https://github.com/kavya0224/codex/blob/main/backend/src/utils/outputValidator.js): `backend/src/utils/outputValidator.js`

### AI and telemetry

- [Groq LLM](https://github.com/kavya0224/codex/blob/main/backend/src/llm/groqClient.js): `backend/src/llm/groqClient.js`
- [Code sanitizer](https://github.com/kavya0224/codex/blob/main/backend/src/utils/codeSanitizer.js): `backend/src/utils/codeSanitizer.js`
- [Run telemetry](https://github.com/kavya0224/codex/blob/main/backend/src/utils/executionLogger.js): `backend/src/utils/executionLogger.js`
- [Performance tracker](https://github.com/kavya0224/codex/blob/main/backend/src/utils/performanceTracker.js): `backend/src/utils/performanceTracker.js`

### Other components

- **Problem solver**
- **Groq API**
- [Docker sandbox](https://github.com/kavya0224/codex/tree/main/backend/sandbox): `backend/sandbox`

## Connections

- Problem solver → React workspace: submits problem (evidence: `README.md`)
- React workspace → Solve route: POST /solve (evidence: `README.md`)
- React workspace → Explain route: POST /explain (evidence: `README.md`)
- Express server → Solve route: mounts route (evidence: `backend/src/server.js`)
- Express server → Explain route: mounts route (evidence: `backend/src/server.js`)
- Solve route → Solve handler: routes request (evidence: `backend/src/routes/solveRoute.js`)
- Explain route → Explain handler: routes request (evidence: `backend/src/routes/explainRoute.js`)
- Solve handler → Solve orchestrator: calls (evidence: `backend/src/controllers/solveController.js`)
- Explain handler → Explanation service: calls (evidence: `backend/src/controllers/explainController.js`)
- Solve orchestrator → Problem planner: creates plan (evidence: `backend/src/services/solveService.js`)
- Solve orchestrator → Code generator: generates code (evidence: `backend/src/services/solveService.js`)
- Solve orchestrator → Debug agent: repairs failures (evidence: `backend/src/services/solveService.js`)
- Code generator → Groq LLM: requests generation (evidence: `backend/src/agents/codeGeneratorAgent.js`)
- Debug agent → Groq LLM: requests fixes (evidence: `README.md`)
- Explanation service → Groq LLM: requests explanation (evidence: `backend/src/services/explainService.js`)
- Groq LLM → Groq API: calls model (evidence: `backend/src/llm/groqClient.js`)
- Solve orchestrator → Workspace files: saves code (evidence: `backend/src/services/solveService.js`)
- Sandbox executor → Workspace files: writes input (evidence: `backend/src/execution/codeExecutor.js`)
- Solve orchestrator → Sandbox executor: executes code (evidence: `backend/src/services/solveService.js`)
- Sandbox executor → Docker sandbox: runs container (evidence: `backend/src/execution/codeExecutor.js`)
- Solve orchestrator → Test case runner: runs test suites (evidence: `backend/src/services/solveService.js`)
- Test case runner → Sandbox executor: executes cases (evidence: `backend/src/utils/testCaseRunner.js`)
- Test case runner → Output validator: checks outputs (evidence: `backend/src/utils/testCaseRunner.js`)
- Solve orchestrator → Output validator: validates result (evidence: `backend/src/services/solveService.js`)
- Groq LLM → Code sanitizer: sanitizes code (evidence: `backend/src/llm/groqClient.js`)
- Solve orchestrator → Run telemetry: records stages (evidence: `backend/src/services/solveService.js`)
- Solve orchestrator → Performance tracker: tracks timings (evidence: `backend/src/services/solveService.js`)
