Interview Simulator

graph TB
    subgraph Client["Client Layer"]
        MOBILE["Mobile App<br/>React Native + Expo<br/>Flash cards, voice drills,<br/>progress dashboard"]
        DESKTOP["Desktop Web<br/>Next.js<br/>Full sessions, whiteboard,<br/>proctoring"]
    end

    subgraph Engines["Engine Layer"]
        VOICE["Voice Engine<br/>Hume AI EVI<br/>Emotion-sensitive<br/>interviewer voice"]
        BOARD["Whiteboard Engine<br/>tldraw + Claude Vision<br/>Diagram evaluation<br/>and scoring"]
        PROCTOR["Proctor Engine<br/>MediaPipe Face Mesh<br/>Gaze tracking,<br/>attention monitoring"]
    end

    subgraph Orchestrator["Session Orchestrator — Node.js"]
        ROUND["Round Selector<br/>Weakness-weighted<br/>random selection"]
        ADAPT["Adaptive Difficulty<br/>Performance-based<br/>question scaling"]
        DEBRIEF["Debrief Generator<br/>Transcript + emotion +<br/>proctor + whiteboard<br/>scored rubric"]
        SM2["SM-2 Scheduler<br/>Spaced repetition<br/>for concepts and stories"]
    end

    subgraph Data["Data Layer — Supabase"]
        SESSIONS[("sessions<br/>recordings, transcripts")]
        SCORES[("scores<br/>per-dimension breakdowns")]
        STORIES[("story_bank<br/>STAR-L entries")]
        CARDS[("flash_cards<br/>SM-2 intervals")]
    end

    MOBILE --> Orchestrator
    DESKTOP --> Orchestrator
    Orchestrator --> VOICE
    Orchestrator --> BOARD
    Orchestrator --> PROCTOR
    Orchestrator --> Data
    VOICE --> DEBRIEF
    BOARD --> DEBRIEF
    PROCTOR --> DEBRIEF

flowchart TD
    V{Voice AI?}
    V -->|"Emotion detection needed"| HUME["Hume AI EVI<br/>Emotion callbacks,<br/>adaptive persona,<br/>WebSocket streaming"]
    V -->|"Voice only, no emotion"| ELEVEN["ElevenLabs<br/>Fallback: high-quality<br/>TTS, no affect reading"]
    V -->|"Cost-constrained"| OPENAI_RT["OpenAI Realtime API<br/>Cheaper per minute,<br/>no emotion detection"]

    W{Whiteboard?}
    W -->|"React ecosystem, extensible"| TLDRAW["tldraw<br/>MIT license, React native,<br/>rich API, snapshot export"]
    W -->|"Simpler, self-hosted"| EXCALI["Excalidraw<br/>Good but harder to<br/>integrate programmatic<br/>screenshot capture"]

    P{Proctoring?}
    P -->|"Privacy-first, free"| MEDIAPIPE["MediaPipe Face Mesh<br/>Browser-based, 468 landmarks,<br/>iris tracking, no cloud"]
    P -->|"Commercial accuracy"| COMMERCIAL["Commercial proctoring<br/>Expensive, privacy concerns,<br/>overkill for self-practice"]

    style HUME fill:#2d5016,stroke:#333,color:#fff
    style TLDRAW fill:#2d5016,stroke:#333,color:#fff
    style MEDIAPIPE fill:#2d5016,stroke:#333,color:#fff

sequenceDiagram
    participant U as User
    participant O as Orchestrator
    participant V as Voice Engine
    participant W as Whiteboard
    participant P as Proctor
    participant D as Debrief

    U->>O: Start session
    O->>O: Select round type<br/>(weakness-weighted)
    O->>U: Confirm: ML Design, Difficulty 3/5,<br/>Persona: Collaborative
    U->>O: Accept / override

    O->>V: Initialize interviewer persona
    O->>P: Activate gaze tracking
    alt Design or Coding Round
        O->>W: Open whiteboard
    end

    loop During Session (30-45 min)
        V->>U: Ask question / follow-up
        U->>V: Respond (voice)
        V->>O: Emotion data (confidence, hesitation)
        O->>V: Adjust difficulty / tone
        P->>O: Gaze flags (second monitor, notes)
        alt Design Round
            W-->>O: Periodic screenshot (every 30s active)
            O-->>W: Evaluate diagram (Claude Vision)
        end
    end

    U->>O: End session
    O->>D: Compile transcript + emotion<br/>timeline + proctor flags +<br/>whiteboard evaluations
    D->>U: Scored debrief with<br/>strengths, weaknesses,<br/>specific improvement actions
    O->>O: Update weakness tracker,<br/>adjust next session focus

07:00  Open mobile app
07:00  3 flash cards — spaced repetition surfaces weakest concepts
       (ML concepts, system design patterns, Anthropic-specific topics)
07:05  1 behavioral story rehearsal — voice, 3 minutes max
       App plays the prompt, you respond aloud, app records duration
07:08  Quick self-check — rate confidence 1-5 on today's cards
07:10  Done — push notification schedules evening session

19:00  Open desktop app, orchestrator selects round type
19:02  Configure: confirm round, set proctor to Training mode
19:05  Session begins — voice AI drives conversation
       Whiteboard opens for design rounds
       Proctor tracks gaze, flags second monitor use
19:35  Session ends (30 min) or 19:50 (45 min)
19:35  Debrief displays: scored rubric, emotion timeline,
       proctor flags, whiteboard evaluation (if applicable)
19:45  Review debrief — spend 1/3 of practice time here
19:55  Update story bank with any new insights
20:00  Done — weakness tracker updated automatically

10:00  Full loop: 2-3 back-to-back rounds (different types)
       5-minute breaks between rounds (no phone, no notes)
       Proctor set to Simulation (strict) mode
11:30  Energy management practice — track cognitive fatigue
11:45  Cross-round story coherence review
       Did you tell the same project consistently across rounds?
12:00  Comprehensive weekly debrief — pattern analysis across sessions

# 1. Clone the simulator repo
git clone <your-simulator-repo>
cd interview-simulator

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env.local
# Edit .env.local with your API keys:
#   HUME_API_KEY=...
#   HUME_SECRET_KEY=...
#   ANTHROPIC_API_KEY=...
#   NEXT_PUBLIC_SUPABASE_URL=...
#   SUPABASE_SERVICE_KEY=...

# 4. Initialize database
npx supabase db push

# 5. Run first calibration session
npm run dev
# Navigate to localhost:3000/calibrate
# 10-minute session to establish baseline scores