Code Defense

Code Defense is an AI-powered mock interview platform for developers. Paste a GitHub repository URL (or a specific PR/commit), choose your difficulty level, answer 6 repo-aware technical questions by voice or text, and receive structured AI feedback on each answer.

---

Features

Core Flow

1. Paste a GitHub URL — full repository or a specific PR / commit
2. Choose difficulty — Junior, Mid, Senior, or Staff
3. Answer 6 AI-generated questions — by microphone (Groq Whisper transcription) or by typing
4. Receive structured feedback — scored on Clarity, Depth, Correctness, and Communication

PR-Level Analysis

Instead of analyzing the whole repository, you can target a specific PR or commit diff.

• PR URL format: https://github.com/owner/repo/pull/42
• Commit URL format: https://github.com/owner/repo/commit/abc1234

When a PR/commit URL is provided, the AI fetches the unified diff and generates questions focused exclusively on the code changes in that diff — ideal for code review prep or learning from a specific contribution.

Toggle between Full Repo and PR / Commit mode using the buttons on the dashboard.

Difficulty Selector

Choose the depth of questions to match your level:

Level	Experience	Focus
Junior	0–2 years	Basic understanding, concepts, "what does this do?"
Mid	2–5 years	Design decisions, basic trade-offs
Senior	5–10 years	Deep architectural reasoning, scalability, cross-concerns
Staff	10+ years	System-level thinking, organizational impact, blast radius

The difficulty setting affects both question generation and the evaluation scoring bar.

AI Feedback

Each answer is evaluated and scored across four dimensions:

• Clarity — how well-structured your explanation is
• Depth — whether you explain "why" not just "what"
• Correctness — technical accuracy given the codebase context
• Communication — verbal clarity of technical concepts

You also receive:

• Identified strengths and weaknesses
• A model "ideal answer" showing what a great response looks like at your level

Practice vs Test Mode

Choose how you want to run your interview session from the dashboard:

Mode	Description
Practice	Reveals an on-demand "Ideal Answer" panel for each question. Use it to study the expected answer before or after you respond. No pressure — hints and ideal answers are available freely.
Test	Simulates a real interview. No ideal answer panel. A per-question countdown timer is active and auto-advances when time runs out. Hints are still available but carry score penalties.

Per-Question Timer

Each question has a live countdown timer. The elapsed time per question is recorded from when the question is displayed to when you submit your answer, and is included in the results summary.

Hints System

During the interview, you can request an AI-generated hint for the current question. Each hint used deducts a penalty from your final score for that question, so use them sparingly.

PDF Report Export

After completing the interview, you can download a full After Action Report as a PDF. The report includes:

• Overall score and total time
• Per-question breakdown with your answer, metrics, strengths, weaknesses, and the model answer
• Hint penalty summary
• Mode and difficulty metadata

---

Tech Stack

Layer	Technology
Frontend	React + Vite + Tailwind CSS + shadcn/ui + @react-pdf/renderer
Backend	Node.js + Express + TypeScript
AI	Groq API — llama-3.3-70b-versatile (Q&A) + whisper-large-v3 (transcription)
API Spec	OpenAPI 3.1 → Orval codegen (Zod + React Query)
Monorepo	npm workspaces

---

Project Structure

server/
  app/                 Express API server
    src/
      services/
        github.ts      GitHub repo + PR/commit fetcher and analyzer
        groq.ts        Question generation, answer evaluation, transcription
      routes/
        repo.routes.ts        POST /api/repo/analyze
        interview.routes.ts   POST /api/interview/questions
        evaluation.routes.ts  POST /api/evaluation/answer + /transcribe

  lib/
    api-spec/          OpenAPI 3.1 spec + Orval config
    api-zod/           Generated Zod validators
    db/                Database helpers/schema

client/
  app/                 React frontend
    src/
      pages/
        Dashboard.tsx   Repo/PR input + difficulty selector
        Interview.tsx   Question-by-question interview flow
        Results.tsx     Feedback and scores
      components/
        GithubRepoInput.tsx   Main input form (repo/PR toggle + difficulty)
        QuestionCard.tsx      Individual question display
        AudioRecorder.tsx     Microphone recorder + Whisper transcription
        ProgressBar.tsx       Interview progress indicator
        FeedbackPanel.tsx     Per-answer feedback display
      report/
        ReportPdfDocument.tsx PDF "After Action Report" layout (react-pdf)
      store/
        interview.tsx         React context — repo analysis, questions, answers, difficulty
  lib/
    api-client-react/  Generated React Query hooks

---

API Endpoints

POST /api/repo/analyze

Analyze a GitHub repository or PR/commit diff.

{
  "repoUrl": "https://github.com/owner/repo",
  "prUrl": "https://github.com/owner/repo/pull/42"   // optional
}

Returns a RepoAnalysis object including language, framework, architecture patterns, key file contents, and optionally the PR diff.

POST /api/interview/questions

Generate 6 interview questions from a repo analysis.

{
  "repoAnalysis": { ... },
  "difficulty": "senior"   // "junior" | "mid" | "senior" | "staff" — defaults to "mid"
}

POST /api/evaluation/answer

Evaluate a candidate's answer.

{
  "question": "Why did you choose X pattern here?",
  "answer": "I chose X because...",
  "repoContext": "...",
  "difficulty": "senior"   // optional, affects scoring bar
}

POST /api/evaluation/transcribe

Transcribe audio to text (base64-encoded audio).

{
  "audioBase64": "...",
  "mimeType": "audio/webm"
}

---

Environment Variables

Variable	Required	Description
GROQ_API_KEY	Yes	Groq API key for LLM and Whisper
GITHUB_TOKEN	No	GitHub personal access token (raises rate limit 60→5000/hr)
SESSION_SECRET	Yes	Session signing secret for the Express server

---

Running Locally

Prerequisites

• Node.js 20+ (npm ships with Node)

Setup

# Clone the repository
git clone https://github.com/your-username/code-defense.git
cd code-defense

# Install dependencies
npm install

# Set environment variables
cp .env.example .env
# Edit .env and add your GROQ_API_KEY

# Run codegen (generates TypeScript types from OpenAPI spec)
npm run codegen -w @workspace/api-spec

# Start the API server (default port 8080)
npm run dev -w @workspace/api-server

# Start the frontend (default port 5173)
npm run dev -w @workspace/code-defense

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

Downloading the Project Files

To download the full project from Replit to your local machine:

1. Open your Replit project
2. Click the three-dot menu (⋮) in the Files panel (top-left sidebar)
3. Select "Download as ZIP"
4. Extract the ZIP to your desired local folder
5. Run npm install to restore all dependencies

Alternatively, if you have the Replit CLI:

replit clone <your-repl-url>

---

Notes

• The app is intentionally stateless — no database is used. All state lives in React context for the duration of the session.
• Groq Whisper transcription requires browser microphone permission.
• GitHub's public API allows 60 requests/hour without a token. Add a GITHUB_TOKEN to avoid rate limiting on large repositories.