LeapCode

AI fluency interview platform. Candidates direct an AI agent to fix bugs in a real codebase. Token consumption and tool call count are tracked as first-class metrics alongside test results.

For a full description of the product and its design decisions (MVP only), see docs/REQUIREMENTS.md.

---

How it works

An interviewer creates a session, supplies an OpenAI API key, and sends a candidate invite link. The candidate opens the link and is dropped directly into the interview — no account needed. The candidate types natural-language prompts that instruct an AI agent to read, edit, and test the codebase. When the candidate submits, the agent runs the test suite and the session is finalized. The interviewer sees full metrics: tokens used, tool calls made, and per-test pass/fail results.

See docs/architecture/DESIGN.md for the full system architecture and docs/architecture/VIEWS.md for the UI layout.

---

Prerequisites

• Python 3.11+
• Node.js 18+ and npm
• Docker (must be running — one container is spun up per interview session)
• A Supabase project (for interviewer authentication only; candidates do not need a Supabase account)

---

Setup

1. Clone the repo

git clone <repo-url>
cd LeapCode

2. Configure environment variables

Create backend/.env with the following values:

SUPABASE_URL=https://<your-project-ref>.supabase.co
SUPABASE_KEY=<your-supabase-service-role-key>
JWT_SECRET=<a-long-random-secret-string>

• SUPABASE_URL and SUPABASE_KEY come from your Supabase project's Settings → API page. Use the service role key (not the anon key). Reach out to Deniz Kirca (kircad20@gmail.com) for these credentials.
• JWT_SECRET is an arbitrary secret used to sign candidate JWTs. Set it to any long random string (e.g. the output of openssl rand -hex 32).

3. Create an interviewer account

Interviewers must be created manually in Supabase — there is no self-serve signup. Go to your Supabase project's Authentication → Users page and create an account with email/password.

4. Install backend dependencies

cd backend
pip install -r requirements.txt

Using a virtual environment is recommended:

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

5. Install frontend dependencies

cd frontend
npm install

---

Running the app

Start both servers. Each needs its own terminal.

Backend (runs on http://localhost:8000):

cd backend
python src/run.py

Frontend (runs on http://localhost:5173):

cd frontend
npm run dev

Open http://localhost:5173 in your browser.

---

Running an interview

As the interviewer

1. Log in with your Supabase email/password.
2. Select a problem and create a session — you will be prompted for the candidate's email and your OpenAI API key. The API key is held in server memory only and is never stored to disk or a database.
3. Copy the invite URL from the session page and send it to the candidate (e.g. via email or Slack). Currently, no email is sent automatically.
4. Observe the session live: the right panel shows tokens used, tool calls made, and test results as they update.
5. Click End Session when the interview is complete.

As the candidate

1. Open the invite URL you received from the interviewer.
2. You are dropped directly into the session — no login or account creation required.
3. Type prompts in the chat panel to instruct the agent. The agent can read files, write files, list directories, and run the test suite.
4. The Monaco editor shows the current state of the codebase. It is read-only — all edits must go through the agent.
5. Click Submit when you are ready to finalize. The test suite runs and your results are displayed immediately.

---

Running tests

cd backend
pytest

---

Project structure

backend/src/leapcode_app/   # FastAPI backend
frontend/src/               # React + Vite frontend
docs/architecture/          # Design documents
  DESIGN.md                 # System architecture and data models
  API.md                    # Backend endpoint reference
  VIEWS.md                  # Frontend component and layout spec
docs/REQUIREMENTS.md        # Product spec and constraints

---

Technical reference

Topic	Document
System architecture, data models, security	docs/architecture/DESIGN.md
All API endpoints, request/response shapes	docs/architecture/API.md
Frontend layout and component spec	docs/architecture/VIEWS.md
Full product requirements and constraints	docs/REQUIREMENTS.md