Socra

An AI-powered study app that keeps students cognitively engaged during study sessions. Upload your lecture notes as a PDF, and Socra extracts 8 core concepts, fires random timed checkpoint questions as you study, scores your answers with Claude, and shows a live leaderboard across everyone in your session. At the end you get a gap report with targeted revision actions.

Built at Durham Build Day 2025.

---

What You Need Before Starting

Install these if you don't have them:

Requirement	Version	Download
Python	3.11 or higher	https://www.python.org/downloads/
Node.js	18 or higher	https://nodejs.org/
Git	Any	https://git-scm.com/
Anthropic API key	—	https://console.anthropic.com/

To check if you already have them:

python3 --version
node --version
git --version

---

Step 1 — Clone the Repo

git clone https://github.com/remade09/Durham-Build-Day-Project.git
cd Durham-Build-Day-Project

---

Step 2 — Set Up the Backend

cd socra/backend
python3 -m venv venv

Activate the virtual environment:

• Mac / Linux: source venv/bin/activate
• Windows: venv\Scripts\activate

You should see (venv) appear at the start of your terminal line.

pip install -r requirements.txt

This installs: FastAPI, Uvicorn, Anthropic SDK, PyMuPDF, and a few other dependencies.

API key (optional): If you want to skip entering it in the browser every time, create a file called .env inside socra/backend/ with:

ANTHROPIC_API_KEY=sk-ant-your-key-here

If you skip this, you'll be prompted to paste your key in the app's UI instead — either way works.

---

Step 3 — Set Up the Frontend

Open a new terminal window (keep the backend terminal open):

cd Durham-Build-Day-Project/socra/frontend
npm install

This will take a minute or two to download dependencies.

---

Step 4 — Run the App

You need two terminal windows running at the same time.

Terminal 1 — Backend:

cd socra/backend
source venv/bin/activate        # Windows: venv\Scripts\activate
uvicorn main:app --reload --port 8000

You should see: Uvicorn running on http://0.0.0.0:8000

Terminal 2 — Frontend:

cd socra/frontend
npm run dev

You should see: Local: http://localhost:3000

Open your browser and go to: http://localhost:3000

---

Step 5 — Using the App

1. Enter your Anthropic API key at the top (saved in your browser, never sent anywhere except directly to the API)
2. Enter your name and the topic you're studying
3. Choose a session duration (10, 25, or 45 minutes)
4. Upload a PDF of your lecture notes (drag and drop or click to browse)
5. Create a session — a 6-character code and QR code will appear
6. Click Start Studying
7. A checkpoint question will fire automatically during your session — or hit ⚡ Trigger Checkpoint to test it immediately
8. At the end, you'll see your gap report with revision actions

---

Multiplayer (Study With Others)

To let someone on the same Wi-Fi join your session:

# Terminal 1 — backend
uvicorn main:app --reload --port 8000 --host 0.0.0.0

# Terminal 2 — frontend
npm run dev -- --hostname 0.0.0.0

Find your IP address:

• Mac: ifconfig | grep "inet " (look for something like 192.168.x.x)
• Windows: ipconfig (look for IPv4 Address)

Share this URL with your study partner: http://<your-ip>:3000?join=<SESSION_CODE>

They scan the QR code or paste the URL and their name will appear in your waiting room.

---

Common Issues

command not found: python3 — Install Python from https://www.python.org/downloads/ and restart your terminal.

command not found: npm — Install Node.js from https://nodejs.org/ and restart your terminal.

ModuleNotFoundError — Make sure you activated the virtual environment (source venv/bin/activate) before running uvicorn.

Backend not connecting — Make sure both terminals are running. The backend must be on port 8000 and the frontend on port 3000.

"Upload failed — check backend is running" — The backend terminal crashed or was closed. Restart it.

---

Tech Stack

Layer	Technology
Frontend	Next.js 14 + TypeScript + Tailwind CSS
Backend	FastAPI (Python)
AI	Anthropic Claude (claude-sonnet-4-20250514)
PDF parsing	PyMuPDF

---

Features

• PDF upload → Claude extracts 8 core concepts + maps embedded images to concepts
• Flashcard deck to self-rate understanding before the sprint
• Adaptive checkpoint questions (difficulty scales with your score trend)
• Timed question modal (45 / 70 / 90s) graded by Claude with feedback
• Live leaderboard with score trend arrows and join notifications
• Session sharing via QR code and ?join=CODE URL
• End-of-session gap report with mastery grid and revision actions
• Winner banner with top scorer highlighted