How gurkalra/labta works
LabTA is a full-stack web application whose core value is a closed-loop “code execution → diagnostics → AI hint/patch” pipeline for programming labs, plus a teacher analytics view.
Agent “Brain” (Gemini + RAG over local JSON knowledge)
Additionally there is a Knowledge/Data layer (JSON files) used for both RAG context and problem/test definitions and session analytics persistence.
• Runtime request/data flows (student submits code → container run → diagnostics → optional LLM → response w/ hints + git-diff patch)
• Static/module boundaries (what lives where in the repo and why)
Backend (Orchestration Layer) — backend/
• app.py (FastAPI entry + routes)
• agent.py (Gemini calls, RAG retrieval, patch generation)
• sandbox.py (Docker lifecycle + execute)
• diagnostics.py (error parsing/prioritization)
• __init__.py
• Inside it (or adjacent subcomponents), explicitly split:
• “Request Router / Session Coordinator” (app.py)
• “Diagnostics Engine” (diagnostics.py)
• “Sandbox Executor” (sandbox.py)
• “AI Agent (RAG + Patch Logic)” (agent.py)
• Router → Sandbox Executor (run code)
• Sandbox Executor → Diagnostics Engine (stderr/stdout + exit code → classified errors)
• Router → AI Agent (conditional / “only when necessary”)
• AI Agent ↔ Knowledge JSONs (RAG inputs)
• Router ↔ Sessions store (read/write analytics)
Knowledge/Data Layer — data/
• problems.json (problem definitions + hidden tests per README)
• error_dictionary.json (weighted error priority rules)
• lab_manual_index.json (course material index for RAG)
• sessions.json (persistent student analytics)
• “Problem Bank + Hidden Tests (JSON)”
• “Error Priority Rules (JSON)”
• “RAG Index / Course KB (JSON)”
• “Session Analytics Store (JSON file)”
• Backend reads problems.json to serve problem list + to assemble sandbox run context (tests)
• Diagnostics reads error_dictionary.json
• Agent reads lab_manual_index.json
• Backend reads/writes sessions.json (for dashboard)
(Important: since these are JSON files in-repo, represent as local storage rather than a DB; optionally annotate “future: DB”.)
Sandbox / Infrastructure Layer — runner/
• runner/Dockerfile builds lab-ta-runner
• “Docker Host (Codespaces)” (or “Backend Host”)
• “Ephemeral Runner Container: lab-ta-runner”
• Backend → Docker Engine API (spawn container, mount code+tests)
• Container → Backend (logs, exit status)
• Container lifecycle note: “destroy after execution”
• Execution limits annotation: “256MB, 0.5 CPU, 5s timeout”
• “Google Gemini 2.5 Flash API” (external SaaS)
• “LLM_API_KEY from .env” (secret/config)
• AI Agent → Gemini API (prompt + context)
• Gemini API → AI Agent (hint + patch/diff)
Backend composes execution payload
• fetches problem + hidden tests from data/problems.json
Backend executes in Docker sandbox via backend/sandbox.py
• creates lab-ta-runner container
• mounts student code + tests
• runs with CPU/RAM/time limits
Diagnostics (backend/diagnostics.py) classifies
• Syntax vs Runtime vs Logic (as per README)
• uses data/error_dictionary.json to prioritize messaging
Decision gate: “AI needed?”
• If trivial/known: backend returns deterministic hint
• If complex/stuck: call Agent
Agent (backend/agent.py) does RAG
• pulls relevant snippets/index entries from data/lab_manual_index.json
• crafts prompt, calls Gemini
• returns: structured hints + optionally a git-diff patch
Frontend renders result and if patch present
• Apply Fix Engine parses diff and applies to editor buffer
For the teacher dashboard flow
• dashboard.html → Backend → reads sessions.json → returns aggregates → Chart.js renders heatmap/trends.
These two flows (student closed-loop + teacher analytics) should be separately visible.
Architectural patterns to highlight (because they’re central to LabTA)
• Closed-loop execution & diagnosis: deterministic execution first, AI second
• Modular decoupling: UI / Orchestration / Execution / AI reasoning / Knowledge
• Policy & safety boundary: Docker sandbox as a hard isolation barrier
• Conditional AI routing: “AI calls only when necessary” decision node
• Patch-based assistance: output format includes git-diff enabling selective application
Actors: Student, Instructor
Systems: Frontend (Vercel), Backend (Codespaces), Gemini API
Containers: Browser UI, FastAPI service, Docker runner container, JSON data store(s), External Gemini.
This is where you show Docker isolation and data JSONs clearly.
Components: app.py routes, sandbox.py, diagnostics.py, agent.py, “data access layer (JSON)”.
“AI needed?” decision node here.
“Don’t overthink it”: maximally separate components (what “detailed” means here)
To be very detailed (as requested), separate these items into distinct nodes instead of lumping them:
• Student Portal pages (index/selection/problem) vs Teacher Dashboard
• Backend router vs diagnostics vs sandbox vs agent
• Each JSON store as its own datastore node
• Docker “host runtime” vs “ephemeral runner container”
• “Hidden tests” as a labeled artifact mounted into the container (even if sourced from problems.json)