# codinghub27/adaptive-coding-agent architecture

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

## Overview

Adaptive Coding & Problem-Solving Agent is a web-based AI tutor, debugger, reviewer, and problem solver. A learner submits text, code, or an image; the backend interprets the input and intent, consults learner memory, plans assistance, and routes to a specialized capability. Retrieval and sandbox verification support relevant answers and code claims; response generation returns guidance, while learning events can update the learner model. The README documents this end-to-end flow; sampled code confirms routing, hint-ladder behavior, RAG indexing, sandbox setup, and auth persistence, but not every runtime call between subsystems.

Main entry points: [`app/graph/api.py`](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/graph/api.py) (Chat endpoint), [`app/graph/routing.py`](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/graph/routing.py) (Agent routing), [`app/execution/runner.py`](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/execution/runner.py) (Sandbox runner), [`app/knowledge/retrieve.py`](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/knowledge/retrieve.py) (Hybrid retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learner Interface"]
  node_web["Web UI<br/>[App.tsx]"]
  node_web_api["HTTP client<br/>[api.js]"]
end

subgraph group_understanding["Input and Planning"]
  node_chat_api["Chat endpoint<br/>[api.py]"]
  node_input["Input understanding<br/>[api.py]"]
  node_intent["Intent classifier<br/>[intent.py]"]
  node_memory["Learner memory<br/>[api.py]"]
  node_planner["Teaching planner<br/>[planner.py]"]
  node_graph["Graph workflow<br/>[build.py]"]
  node_routing["Agent routing<br/>[routing.py]"]
end

subgraph group_teaching["Teaching Capabilities"]
  node_dsa["DSA solver<br/>[dsa_solver.py]"]
  node_hints["Hint ladder<br/>[hint_engine.py]"]
  node_debugger["Debugger<br/>[debugger.py]"]
  node_explainer["Code explainer<br/>[explainer.py]"]
  node_reviewer["Code reviewer<br/>[reviewer.py]"]
  node_response["Response generation<br/>[generate.py]"]
end

subgraph group_support["Knowledge and Verification"]
  node_knowledge["Hybrid retrieval<br/>[retrieve.py]"]
  node_qdrant[("Qdrant index")]
  node_execution["Sandbox runner<br/>[runner.py]"]
  node_sandbox["Docker sandbox<br/>[sandbox.py]"]
  node_verification["Code verification<br/>[verification.py]"]
end

subgraph group_platform["Platform Services"]
  node_app["FastAPI app<br/>[main.py]"]
  node_llm["LLM provider"]
  node_database[("PostgreSQL")]
  node_auth["Authentication<br/>[routes.py]"]
end

node_learner(("Learner"))

node_learner -->|"submits request"| node_web
node_web -->|"uses client"| node_web_api
node_web_api -->|"HTTP requests"| node_app
node_app -->|"mounts endpoint"| node_chat_api
node_app -->|"mounts routes"| node_auth
node_chat_api -->|"interprets input"| node_input
node_input -->|"classifies intent"| node_intent
node_chat_api -->|"loads learner context"| node_memory
node_chat_api -->|"plans assistance"| node_planner
node_chat_api -->|"runs workflow"| node_graph
node_graph -->|"selects capability"| node_routing
node_routing -->|"dispatches DSA"| node_dsa
node_routing -->|"dispatches debug"| node_debugger
node_routing -->|"dispatches explain"| node_explainer
node_dsa -->|"chooses hint rung"| node_hints
node_dsa -->|"retrieves context"| node_knowledge
node_debugger -->|"retrieves context"| node_knowledge
node_explainer -->|"retrieves context"| node_knowledge
node_reviewer -->|"runs code checks"| node_execution
node_debugger -->|"runs code"| node_execution
node_execution -->|"executes request"| node_sandbox
node_execution -->|"verifies result"| node_verification
node_knowledge -->|"searches index"| node_qdrant
node_chat_api -->|"generates answer"| node_response
node_response -->|"requests generation"| node_llm
node_planner -->|"requests planning"| node_llm
node_memory -->|"reads and writes"| node_database
node_auth -->|"persists accounts"| node_database
node_response -->|"returns answer"| node_web_api

click node_web "https://github.com/codinghub27/adaptive-coding-agent/blob/main/frontend/src/App.tsx"
click node_web_api "https://github.com/codinghub27/adaptive-coding-agent/blob/main/frontend/js/api.js"
click node_app "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/main.py"
click node_chat_api "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/graph/api.py"
click node_input "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/input/api.py"
click node_intent "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/input/intent.py"
click node_memory "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/memory/api.py"
click node_planner "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/agents/planner.py"
click node_graph "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/graph/build.py"
click node_routing "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/graph/routing.py"
click node_dsa "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/agents/dsa_solver.py"
click node_hints "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/agents/hint_engine.py"
click node_debugger "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/agents/debugger.py"
click node_explainer "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/agents/explainer.py"
click node_reviewer "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/agents/reviewer.py"
click node_knowledge "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/knowledge/retrieve.py"
click node_execution "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/execution/runner.py"
click node_sandbox "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/execution/sandbox.py"
click node_verification "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/execution/verification.py"
click node_response "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/response/generate.py"
click node_auth "https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/auth/routes.py"

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_web,node_web_api toneBlue
class node_chat_api,node_input,node_intent,node_memory,node_planner,node_graph,node_routing toneAmber
class node_dsa,node_hints,node_debugger,node_explainer,node_reviewer,node_response toneMint
class node_knowledge,node_qdrant,node_execution,node_sandbox,node_verification toneRose
class node_app,node_llm,node_database,node_auth,node_learner toneIndigo
```

## Components

### Learner Interface

- [Web UI](https://github.com/codinghub27/adaptive-coding-agent/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [HTTP client](https://github.com/codinghub27/adaptive-coding-agent/blob/main/frontend/js/api.js): `frontend/js/api.js`

### Input and Planning

- [Chat endpoint](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/graph/api.py): `app/graph/api.py`
- [Input understanding](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/input/api.py): `app/input/api.py`
- [Intent classifier](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/input/intent.py): `app/input/intent.py`
- [Learner memory](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/memory/api.py): `app/memory/api.py`
- [Teaching planner](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/agents/planner.py): `app/agents/planner.py`
- [Graph workflow](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/graph/build.py): `app/graph/build.py`
- [Agent routing](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/graph/routing.py): `app/graph/routing.py`

### Teaching Capabilities

- [DSA solver](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/agents/dsa_solver.py): `app/agents/dsa_solver.py`
- [Hint ladder](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/agents/hint_engine.py): `app/agents/hint_engine.py`
- [Debugger](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/agents/debugger.py): `app/agents/debugger.py`
- [Code explainer](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/agents/explainer.py): `app/agents/explainer.py`
- [Code reviewer](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/agents/reviewer.py): `app/agents/reviewer.py`
- [Response generation](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/response/generate.py): `app/response/generate.py`

### Knowledge and Verification

- [Hybrid retrieval](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/knowledge/retrieve.py): `app/knowledge/retrieve.py`
- **Qdrant index**
- [Sandbox runner](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/execution/runner.py): `app/execution/runner.py`
- [Docker sandbox](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/execution/sandbox.py): `app/execution/sandbox.py`
- [Code verification](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/execution/verification.py): `app/execution/verification.py`

### Platform Services

- [FastAPI app](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/main.py): `app/main.py`
- **LLM provider**
- **PostgreSQL**
- [Authentication](https://github.com/codinghub27/adaptive-coding-agent/blob/main/app/auth/routes.py): `app/auth/routes.py`

### Other components

- **Learner**

## Connections

- Learner → Web UI: submits request
- Web UI → HTTP client: uses client
- HTTP client → FastAPI app: HTTP requests
- FastAPI app → Chat endpoint: mounts endpoint
- FastAPI app → Authentication: mounts routes
- Chat endpoint → Input understanding: interprets input
- Input understanding → Intent classifier: classifies intent
- Chat endpoint → Learner memory: loads learner context
- Chat endpoint → Teaching planner: plans assistance
- Chat endpoint → Graph workflow: runs workflow
- Graph workflow → Agent routing: selects capability
- Agent routing → DSA solver: dispatches DSA
- Agent routing → Debugger: dispatches debug
- Agent routing → Code explainer: dispatches explain
- DSA solver → Hint ladder: chooses hint rung
- DSA solver → Hybrid retrieval: retrieves context
- Debugger → Hybrid retrieval: retrieves context
- Code explainer → Hybrid retrieval: retrieves context
- Code reviewer → Sandbox runner: runs code checks
- Debugger → Sandbox runner: runs code
- Sandbox runner → Docker sandbox: executes request
- Sandbox runner → Code verification: verifies result
- Hybrid retrieval → Qdrant index: searches index
- Chat endpoint → Response generation: generates answer
- Response generation → LLM provider: requests generation
- Teaching planner → LLM provider: requests planning
- Learner memory → PostgreSQL: reads and writes
- Authentication → PostgreSQL: persists accounts
- Response generation → HTTP client: returns answer