Project Info
This project did not submit a demo video on Devpost.
Sandbox: An AI-Powered Teach-Back Workspace That Measures Understanding, Not Recall
Inspiration
As college students in computational biology and pre-med tracks, we constantly work through dense, complex material - metabolic pathways, signaling cascades, regulatory networks. We realized something unsettling: we could memorize definitions and still struggle to explain the system from scratch. Flashcards optimize for recall. Exams demand reconstruction. The moment that inspired Sandbox was this: If you can’t draw it and teach it without notes, you don’t fully understand it. In a world where AI can instantly give answers, the real differentiator is the ability to explain your thinking. We didn’t want another tool that generates solutions - we wanted a tool that evaluates understanding. Sandbox was built to turn students from answer-consumers into idea-builders.
What it does
Sandbox is an AI-powered teach-back workspace designed to help students learn by explaining ideas visually and verbally. Instead of asking, “What’s the answer?”, Sandbox asks, “Can you reconstruct the idea?” The core belief is that true understanding comes from being able to teach a concept - not just recall it. The user flow begins with signing in through Supabase authentication and organizing content into folders by subject or topic. Students upload dense material such as PDFs, lecture slides, or notes. When they start a learning session, they ask a question based on their uploaded content and then record themselves drawing and explaining their reasoning. Rather than returning a solution, Sandbox evaluates the student’s explanation. It analyzes conceptual coverage, structural clarity, logical flow, missing components, and potential misconceptions. The goal is not to check whether the answer is correct, but to measure how deeply the student understands the system. We model understanding as something more nuanced than binary accuracy. Instead of grading correctness, Sandbox evaluates understanding as a function of coverage, structure, causal reasoning, and conceptual connections: U = f(coverage, structure, causal reasoning, connections) Sandbox gives feedback on how well a student rebuilt the system from memory - not whether they memorized it.
How we built it
We architected Sandbox as a full-stack, AI-powered system centered around grounded document understanding and multimodal evaluation. The system is designed to tightly integrate structured content ingestion, semantic retrieval, and real-time teach-back analysis into a single cohesive learning workflow. Rather than building a simple Q&A interface, we engineered a pipeline that transforms static documents into structured, retrievable knowledge representations that power evaluation of student reasoning. On the frontend, we built a modular web application using React and Next.js (v16 with Turbopack), written in TypeScript for type safety and maintainability. The application follows a folder-based architectural structure that mirrors the cognitive model of learning: subjects contain folders, folders contain documents, and documents power sessions. The codebase reflects this modular philosophy, with clearly separated concerns across components such as a custom Canvas for drawing explanations, folder upload panels for document ingestion, dashboard sidebars for structured navigation, subject and folder dialog modals, sandbox session cards, and authentication providers. The frontend handles user authentication (via Supabase), session management, subject/folder organization, document uploads, and recording of drawing-based explanations. Each teach-back session is structured as a stateful interaction, ensuring that visual explanations, prompts, and user metadata are stored in a way that downstream AI evaluation can interpret semantically rather than superficially. On the backend and AI infrastructure layer, we implemented a semantic retrieval system using Pinecone as our vector database. Every uploaded document (PDFs, lecture slides, notes) is parsed, chunked, and embedded into high-dimensional vector representations. These embeddings are stored in Pinecone, enabling contextual retrieval grounded strictly in the user’s uploaded material. This allows Sandbox to generate session questions and evaluate explanations based on semantically relevant content rather than generic model knowledge. By combining structured document ingestion, vector-based retrieval, and multimodal explanation capture (drawing + speech/thought process), Sandbox moves beyond correctness-based grading. The system evaluates conceptual coverage, structural coherence, causal reasoning, and knowledge connections. In other words, we model understanding as a reconstruction problem, not an answer-matching problem. Technically, the architecture cleanly separates: 1) UI/interaction layer (Next.js + React + TypeScript), 2) Authentication and session persistence (Supabase), 3) Document ingestion and preprocessing pipeline, 4) Vector storage and semantic retrieval (Pinecone), 5) AI reasoning layer for teach-back evaluation
Challenges we ran into
One of our biggest challenges was defining and measuring “understanding.” Grading correctness is easy, but evaluating structure, reasoning, and conceptual completeness is not. We had to formalize what conceptual coverage means, design heuristics for structural feedback, and avoid leaking the “right answer.” This required shifting from answer-generation to reasoning-analysis - building a system that critiques reconstruction instead of outputs. Grounding the AI properly was another core challenge. Our retrieval system needed to be fast, strictly scoped to user-uploaded content, and isolated across users and folders. Designing clean namespace logic in Pinecone was critical to preventing cross-contamination and ensuring context-aware, hallucination-resistant feedback. We also faced multimodal complexity. Aligning drawing input, transcribed speech, and document-grounded retrieval is far more complex than a text-only chat interface. The system had to interpret structure and conceptual flow across modalities. Finally, full-stack integration under hackathon time pressure was intense. We were configuring Supabase authentication, Pinecone indexing, embedding pipelines, Next.js (Turbopack + TypeScript), environment variables, and resolving server conflicts. But the system now runs fully end-to-end.
Accomplishments we're proud of
First, we built a fully functional teach-back evaluation engine - not a prototype, but a working end-to-end system. A student can upload dense material, trigger document ingestion and embedding, store vectors in Pinecone with clean namespace isolation, start a learning session, ask a grounded question, record a visual explanation, and receive structured reasoning feedback. The pipeline runs seamlessly from embedding to similarity retrieval to evaluation - all grounded strictly in the student’s uploaded content. Second, we successfully integrated a complex full-stack architecture under tight constraints. We combined Supabase authentication and database storage, Pinecone vector indexing, a modular ingestion and embedding pipeline, transcription services, and a React + Next.js (TypeScript, Turbopack) frontend with organized subject/folder/session management. Each backend service — embedding, retrieval, ingestion, evaluation, Supabase access - is modularized, allowing the system to scale and evolve cleanly. Third, and most importantly, we shifted the role of AI in learning. We deliberately avoided building “just another AI tutor” that generates answers. Instead, we built a cognitive feedback system. Sandbox evaluates reasoning - conceptual coverage, structure, causal flow, and connections - rather than correctness. That philosophical shift reframes AI from answer-provider to thinking evaluator, and that’s the core innovation we’re proud of.
What we learned
Through building Sandbox, we learned that AI is exceptionally good at generating answers - but very few systems are designed to measure thinking. If AI is going to meaningfully support learning, it can’t just produce explanations; it has to evaluate how a student reconstructs ideas. Retrieval grounding proved essential for trust - without strict context isolation and vector-based retrieval, feedback becomes generic or unreliable. We also realized that learning requires productive friction. Students don’t need more information; they need structured reflection that forces them to organize, connect, and rebuild concepts themselves. We also grew as engineers. We architected a modular backend, integrated vector search with user-scoped namespaces, and tested the system using both white-box validation of service logic and black-box simulation of full user workflows. Under time pressure, we debugged environment variables, API key issues, and index mismatches while maintaining system integrity. More importantly, we learned how to communicate clearly when systems broke, divide responsibilities based on team strengths, and make architectural decisions collaboratively. Building Sandbox wasn’t just about writing code - it was about thinking systematically, testing rigorously, and executing as a team.
What's next
Looking ahead, our vision for Sandbox is to transform it from a powerful prototype into the default way students test mastery. We plan to introduce structured evaluation dashboards that score and visualize conceptual coverage over time, allowing students to compare teach-back sessions and track longitudinal gaps in understanding. We also want to add a collaborative “teach each other” mode and expand beyond STEM into domains like law, language learning, and test preparation - making Sandbox a universal cognitive feedback platform. On the AI side, we aim to deepen multimodal alignment between drawing and speech, enabling more precise interpretation of diagram structure and conceptual flow. We plan to implement concept graph reconstruction, automated misconception detection, and adaptive follow-up questioning that dynamically probes weak areas. The goal is to evolve Sandbox from structured feedback into an intelligent reasoning coach. From a systems perspective, we plan to optimize our Pinecone indexing strategy for scale, introduce caching layers to reduce retrieval latency, refine embedding chunking strategies for better semantic coherence, and expand our Supabase schema to support richer session analytics. We also intend to move toward production-grade infrastructure beyond a development server, preparing Sandbox for scalable deployment. Loom Video: https://www.loom.com/share/5001005d45774bc4a88b705fb97ed9fa
Interactive Study Tool
A production-ready MVP web application for interactive studying with voice practice, visual notes, and AI-powered feedback.
Project Structure
treehacks/
├── web/ # Next.js 14+ frontend (App Router, TypeScript, Tailwind)
└── api/ # FastAPI backend (Python)
Features
- Document Upload: Support for PDF, TXT, and DOCX files
- Link Processing: Extract content from URLs using Perplexity API
- Interactive Study Session:
- Blank note page with typed notes and canvas drawing
- AI-generated study questions
- 3-minute timed speaking practice
- Real-time speech transcription (Web Speech API with audio fallback)
- Automatic snapshot capture every 5 seconds
- AI Feedback: Structured evaluation with scores, strengths, gaps, and suggestions
Prerequisites
- Node.js 18+ and npm/yarn
- Python 3.9+
- API Keys:
- Pinecone (for vector storage)
- Anthropic Claude (for question generation and evaluation)
- Perplexity (for link content extraction)
- OpenAI (for embeddings)
Setup Instructions
Backend (FastAPI)
- Navigate to the API directory:
cd api
- Create a virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
- Install dependencies:
pip install -r requirements.txt
- Create
.envfile (copy from.env.example):
cp .env.example .env
- Edit
.envand add your API keys:
PINECONE_API_KEY=your_key_here
PINECONE_INDEX=your_index_name
PINECONE_ENV=us-east-1-aws
ANTHROPIC_API_KEY=your_key_here
PERPLEXITY_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here
EMBEDDING_MODEL=text-embedding-3-small
- Start the FastAPI server:
python main.py
# Or: uvicorn main:app --reload --host 0.0.0.0 --port 8000
The API will be available at http://localhost:8000
Frontend (Next.js)
- Navigate to the web directory:
cd web
- Install dependencies:
npm install
# Or: yarn install
- Create
.env.localfile:
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
- Start the development server:
npm run dev
# Or: yarn dev
The app will be available at http://localhost:3000
Usage
- Upload Documents: Go to the home page and upload PDF/TXT/DOCX files or paste URLs
- Start Session: Click "Process & Start Session" to begin
- Study: On the session page, you'll see a generated question
- Take Notes: Type notes and draw on the canvas
- Practice: Click "Start 3-min Response" to begin recording
- Review Feedback: After recording, view AI-generated feedback
API Endpoints
POST /ingest
Upload documents and links for processing.
Request:
files: Multipart form data (PDF, TXT, DOCX)links: JSON array of URLs
Response:
{
"session_id": "uuid",
"chunks_processed": 10
}
GET /question?session_id={session_id}
Get a generated study question.
Response:
{
"question": "Explain the key concepts..."
}
POST /evaluate
Evaluate a response with transcript and snapshots.
Request:
{
"transcript": "User's spoken response...",
"snapshots": [
{
"t": 1234567890,
"mime": "image/jpeg",
"dataBase64": "base64_encoded_image"
}
],
"session_id": "uuid",
"audio_base64": "optional_base64_audio"
}
Response:
{
"score_overall": 8,
"strengths": ["Clear explanation", "Good structure"],
"gaps": ["Missing examples", "Could be more detailed"],
"suggested_better_structure": ["Start with overview", "Use examples"],
"next_question": "Follow-up question..."
}
Canvas Features
- Pen Tool: Draw with adjustable thickness
- Eraser Tool: Erase parts of the drawing
- Undo: Undo last stroke
- Clear: Clear entire canvas
Speech Transcription
- Primary: Web Speech API (browser-native, real-time)
- Fallback: Audio recording sent to backend for processing (if Web Speech API unavailable)
Notes
- Snapshots are captured every 5 seconds during recording
- All API keys are stored server-side for security
- CORS is configured to allow the Next.js frontend origin
- The app uses Pinecone for vector storage and retrieval
Troubleshooting
- CORS Errors: Ensure the FastAPI server allows your frontend origin
- Microphone Access: Grant browser permissions for microphone
- API Errors: Check that all API keys are correctly set in
.env - Pinecone: Ensure your Pinecone index exists and has the correct dimension (1536 for text-embedding-3-small)
License
MIT
Analysis
View
Metric
- 10
- 2
Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.
Technology
- AnthropicIn code
- CSSIn code
- FastAPIIn code
- JavaScriptIn code
- Next.jsIn code
- OpenAIIn code
- PythonIn code
- ReactIn code
- SQLIn code
- SupabaseIn code
- Tailwind CSSIn code
- TypeScriptIn code
- Node.jsClaimed
12 of 13 appear in the indexed code. 1 claimed on Devpost could not be matched to code, which may simply mean the tool leaves no trace in the repository.
AI coding agents
No AI coding agent signals were found in this repository.
Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.
Codebase size
Source size
178 KB
Source files
52
Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.
Repository
Gracemxli/treehacks
59 files · 260 KB · @ b40e834
Structure
Interface
21 files · 36%Screens, components and styles rendered to the user.
API & routing
15 files · 25%Request entry points: routes, handlers and controllers.
Application logic
1 file · 2%Domain rules, services and shared utilities.
Data & schema
6 files · 10%Schema definitions, migrations and data access.
Supporting
Layers are inferred from where files sit in the tree, not from reading the code. A project that names its directories unconventionally will read oddly here — open the file browser to check anything the diagram implies.
Languages
- TypeScript59%
- Python23%
- Markdown13%
- SQL4%
- CSS1%
- JavaScript0%
Share of indexed source by file size. Binary and vendored files are excluded.
Dependencies
web/package.json
npm · 17- @supabase/ssr
- @supabase/supabase-js
- clsx
- html2canvas
- lucide-react
- next
- react
- react-dom
- tailwind-merge
- zustand
- +7 more
api/requirements.txt
pypi · 14- anthropic
- fastapi
- httpx
- numpy
- openai
- pinecone-client
- pydantic
- pypdf
- python-docx
- python-dotenv
- python-multipart
- supabase
- tiktoken
- uvicorn[standard]
Declared in the repository’s manifests at the indexed commit. A declared package is not proof it is used, and runtime dependencies are listed first.
This project’s features have not been analysed yet.
Export this project's context (description, README, evidence, key source files) to chat with an AI agent elsewhere.