# gokul-hawk/cobra_tutor architecture

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

- Interactive diagram: https://gitdiagram.com/gokul-hawk/cobra_tutor
- Repository: https://github.com/gokul-hawk/cobra_tutor

## Overview

CobraTutor is an agentic tutoring platform: learners use the React app to request instruction or practice, receive personalized tutoring and quizzes, work through code/debugging activities, and view concept mastery. The Django backend supplies agent orchestration, quiz and knowledge-graph features, and knowledge tracing. Edges are limited to relationships supported by the README or the shown imports/calls; the API view wiring and several frontend-to-backend routes are not shown, so those links are omitted.

Main entry points: [`frontend/src/App.jsx`](https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/App.jsx) (App routing), [`backend/chatbot/services/gkt_service.py`](https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/chatbot/services/gkt_service.py) (Graph knowledge tracing), [`frontend/src/components/AgentTutor.jsx`](https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/components/AgentTutor.jsx) (Agent tutor UI), [`frontend/src/components/AgentCode.jsx`](https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/components/AgentCode.jsx) (Agent coding UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learning interface"]
  node_app["App routing<br/>[App.jsx]"]
  node_agent_tutor_ui["Agent tutor UI<br/>[AgentTutor.jsx]"]
  node_agent_code_ui["Agent coding UI<br/>[AgentCode.jsx]"]
  node_agent_quiz_ui["Agent quiz UI<br/>[AgentQuiz.jsx]"]
  node_chat_service["Chat API client<br/>[chatService.js]"]
  node_editor["Code editor<br/>[CodeEditor.jsx]"]
  node_visualizer["Code visualizer"]
  node_knowledge_ui["Knowledge map<br/>[KnowledgeGraph.jsx]"]
end

subgraph group_agents["Tutor agents"]
  node_main_api["Main agent API<br/>[views.py]"]
  node_orchestrator["Agent orchestrator<br/>[orchestrator.py]"]
  node_router["Intent router<br/>[router_agent.py]"]
  node_persistent_tutor["Persistent tutor"]
  node_llm["Groq inference<br/>[groq_service.py]"]
end

subgraph group_learning["Learning services"]
  node_quiz_service["Quiz generation<br/>[gemini_service.py]"]
  node_quiz_store[("Quiz records<br/>[models.py]")]
  node_code_service["Code practice agent<br/>[agent_service.py]"]
  node_code_records[("Code practice records<br/>[models.py]")]
  node_context["Mastery context<br/>[context_service.py]"]
  node_gkt["Graph knowledge tracing<br/>[gkt_service.py]"]
  node_bkt["Bayesian tracing<br/>[bkt_service.py]"]
  node_gat["Graph attention<br/>[gat_service.py]"]
end

subgraph group_knowledge["Knowledge data"]
  node_kg_service["Graph query service<br/>[neo4j_services.py]"]
  node_neo4j[("Neo4j concept graph")]
  node_user_store[("User records<br/>[models.py]")]
  node_knowledge_api["Knowledge graph API<br/>[views.py]"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_app
node_app -->|"routes to"| node_agent_tutor_ui
node_app -->|"routes to"| node_agent_code_ui
node_app -->|"routes to"| node_agent_quiz_ui
node_agent_tutor_ui -->|"requests via"| node_chat_service
node_agent_tutor_ui -->|"renders"| node_visualizer
node_agent_code_ui -->|"renders"| node_editor
node_agent_code_ui -->|"renders"| node_visualizer
node_chat_service -->|"chat request"| node_persistent_tutor
node_learner -->|"requests lessons"| node_main_api
node_main_api -.->|"delegates to"| node_orchestrator
node_orchestrator -->|"routes with"| node_router
node_router -->|"classifies via"| node_llm
node_orchestrator -->|"delegates to"| node_persistent_tutor
node_persistent_tutor -.->|"generates with"| node_llm
node_quiz_service -->|"generates through"| node_llm
node_quiz_service -->|"saves questions"| node_quiz_store
node_code_service -->|"gets mastery"| node_context
node_code_service -->|"saves practice"| node_code_records
node_context -->|"reads mastery"| node_gkt
node_gkt -->|"queries graph"| node_kg_service
node_gkt -->|"updates tracing"| node_bkt
node_gkt -->|"propagates mastery"| node_gat
node_kg_service -->|"queries"| node_neo4j
node_learner -->|"views mastery map"| node_knowledge_ui
node_knowledge_ui -.->|"fetches graph"| node_knowledge_api
node_knowledge_api -.->|"reads concepts"| node_neo4j

click node_app "https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/App.jsx"
click node_agent_tutor_ui "https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/components/AgentTutor.jsx"
click node_agent_code_ui "https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/components/AgentCode.jsx"
click node_agent_quiz_ui "https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/components/AgentQuiz.jsx"
click node_chat_service "https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/services/chatService.js"
click node_editor "https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/components/CodeEditor.jsx"
click node_visualizer "https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/components/VisualizerRenderer.jsx"
click node_main_api "https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/main_agent/views.py"
click node_orchestrator "https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/main_agent/services/orchestrator.py"
click node_router "https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/main_agent/services/router_agent.py"
click node_persistent_tutor "https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/chatbot/services/persistent_tutor.py"
click node_llm "https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/chatbot/services/groq_service.py"
click node_quiz_service "https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/quizzes/services/gemini_service.py"
click node_quiz_store "https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/quizzes/models.py"
click node_code_service "https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/Code/services/agent_service.py"
click node_code_records "https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/Code/models.py"
click node_context "https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/chatbot/services/context_service.py"
click node_gkt "https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/chatbot/services/gkt_service.py"
click node_bkt "https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/chatbot/services/bkt_service.py"
click node_gat "https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/chatbot/services/gat_service.py"
click node_kg_service "https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/quizzes/services/neo4j_services.py"
click node_user_store "https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/users/models.py"
click node_knowledge_api "https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/knowledge_graph/views.py"
click node_knowledge_ui "https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/components/KnowledgeGraph.jsx"

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,node_agent_tutor_ui,node_agent_code_ui,node_agent_quiz_ui,node_chat_service,node_editor,node_visualizer,node_knowledge_ui toneBlue
class node_main_api,node_orchestrator,node_router,node_persistent_tutor,node_llm toneAmber
class node_quiz_service,node_quiz_store,node_code_service,node_code_records,node_context,node_gkt,node_bkt,node_gat toneMint
class node_kg_service,node_neo4j,node_user_store,node_knowledge_api toneRose
class node_learner toneIndigo
```

## Components

### Learning interface

- [App routing](https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Agent tutor UI](https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/components/AgentTutor.jsx): `frontend/src/components/AgentTutor.jsx`
- [Agent coding UI](https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/components/AgentCode.jsx): `frontend/src/components/AgentCode.jsx`
- [Agent quiz UI](https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/components/AgentQuiz.jsx): `frontend/src/components/AgentQuiz.jsx`
- [Chat API client](https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/services/chatService.js): `frontend/src/services/chatService.js`
- [Code editor](https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/components/CodeEditor.jsx): `frontend/src/components/CodeEditor.jsx`
- [Code visualizer](https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/components/VisualizerRenderer.jsx): `frontend/src/components/VisualizerRenderer.jsx`
- [Knowledge map](https://github.com/gokul-hawk/cobra_tutor/blob/main/frontend/src/components/KnowledgeGraph.jsx): `frontend/src/components/KnowledgeGraph.jsx`

### Tutor agents

- [Main agent API](https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/main_agent/views.py): `backend/main_agent/views.py`
- [Agent orchestrator](https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/main_agent/services/orchestrator.py): `backend/main_agent/services/orchestrator.py`
- [Intent router](https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/main_agent/services/router_agent.py): `backend/main_agent/services/router_agent.py`
- [Persistent tutor](https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/chatbot/services/persistent_tutor.py): `backend/chatbot/services/persistent_tutor.py`
- [Groq inference](https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/chatbot/services/groq_service.py): `backend/chatbot/services/groq_service.py`

### Learning services

- [Quiz generation](https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/quizzes/services/gemini_service.py): `backend/quizzes/services/gemini_service.py`
- [Quiz records](https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/quizzes/models.py): `backend/quizzes/models.py`
- [Code practice agent](https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/Code/services/agent_service.py): `backend/Code/services/agent_service.py`
- [Code practice records](https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/Code/models.py): `backend/Code/models.py`
- [Mastery context](https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/chatbot/services/context_service.py): `backend/chatbot/services/context_service.py`
- [Graph knowledge tracing](https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/chatbot/services/gkt_service.py): `backend/chatbot/services/gkt_service.py`
- [Bayesian tracing](https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/chatbot/services/bkt_service.py): `backend/chatbot/services/bkt_service.py`
- [Graph attention](https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/chatbot/services/gat_service.py): `backend/chatbot/services/gat_service.py`

### Knowledge data

- [Graph query service](https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/quizzes/services/neo4j_services.py): `backend/quizzes/services/neo4j_services.py`
- **Neo4j concept graph**
- [User records](https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/users/models.py): `backend/users/models.py`
- [Knowledge graph API](https://github.com/gokul-hawk/cobra_tutor/blob/main/backend/knowledge_graph/views.py): `backend/knowledge_graph/views.py`

### Other components

- **Learner**

## Connections

- Learner → App routing: uses
- App routing → Agent tutor UI: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Agent coding UI: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Agent quiz UI: routes to (evidence: `frontend/src/App.jsx`)
- Agent tutor UI → Chat API client: requests via (evidence: `frontend/src/components/AgentTutor.jsx`)
- Agent tutor UI → Code visualizer: renders (evidence: `frontend/src/components/AgentTutor.jsx`)
- Agent coding UI → Code editor: renders (evidence: `frontend/src/components/AgentCode.jsx`)
- Agent coding UI → Code visualizer: renders (evidence: `frontend/src/components/AgentCode.jsx`)
- Chat API client → Persistent tutor: chat request (evidence: `frontend/src/services/chatService.js`)
- Learner → Main agent API: requests lessons
- Main agent API → Agent orchestrator: delegates to
- Agent orchestrator → Intent router: routes with (evidence: `backend/main_agent/services/orchestrator.py`)
- Intent router → Groq inference: classifies via (evidence: `backend/main_agent/services/router_agent.py`)
- Agent orchestrator → Persistent tutor: delegates to (evidence: `backend/main_agent/services/orchestrator.py`)
- Persistent tutor → Groq inference: generates with
- Quiz generation → Groq inference: generates through (evidence: `backend/quizzes/services/gemini_service.py`)
- Quiz generation → Quiz records: saves questions (evidence: `backend/quizzes/services/gemini_service.py`)
- Code practice agent → Mastery context: gets mastery (evidence: `backend/Code/services/agent_service.py`)
- Code practice agent → Code practice records: saves practice (evidence: `backend/Code/services/agent_service.py`)
- Mastery context → Graph knowledge tracing: reads mastery (evidence: `backend/chatbot/services/context_service.py`)
- Graph knowledge tracing → Graph query service: queries graph (evidence: `backend/chatbot/services/gkt_service.py`)
- Graph knowledge tracing → Bayesian tracing: updates tracing (evidence: `backend/chatbot/services/gkt_service.py`)
- Graph knowledge tracing → Graph attention: propagates mastery (evidence: `backend/chatbot/services/gkt_service.py`)
- Graph query service → Neo4j concept graph: queries (evidence: `backend/quizzes/services/neo4j_services.py`)
- Learner → Knowledge map: views mastery map
- Knowledge map → Knowledge graph API: fetches graph
- Knowledge graph API → Neo4j concept graph: reads concepts
