RolePrep.ai - System Architecture & Data Flow

Product Surfaces / Web + Authenticated Workspace intake / gap report / practice / interview / progress

Intake Flow

Users upload a resume, paste a job description, and set the target interview timeline.

Starting point

Five-Pane Brief

Snapshot, overlap, gaps, prep plan, and learning stack show what is proven and what needs work.

Gap report

Saved Dashboard

Saved briefs, active selection, daily prep cards, and quick resume access persist over time.

Workspace

Practice Drills

Role-aware flip cards turn skill gaps into repeatable active-recall sessions.

Gap repair

Mock Interview

Adaptive interview sessions use the saved role context and return scored debriefs.

Simulation

Progress & Streaks

Points, checklist progress, resource completion, streaks, badges, and email preferences stay visible.

Momentum

Down / User intentResume gap analysis, practice sessions, mock interviews, refinements, and reminders all converge on the application layer.

Application Orchestration / Next.js on Vercel validate -> analyze -> persist -> practice -> engage

Access & Role Gate

Entry

Validates resume intake, signed-user ownership, anonymous limits, and supported role coverage.
Routes recognized roles into the gap analysis pipeline while keeping unsupported cases explicit.

Gap Analysis Pipeline

Core

Detects role family and sub-role, then compares the resume against a curated skill taxonomy.
Uses AI assessment results to identify missing, partial, and proven evidence per requirement.
Applies deterministic scoring to build the five-pane brief, checklist, resource path, and learning plan.

Practice Engine

Generative

Turns gaps into reusable drill cards and prioritizes unresolved or missed items.
Builds daily prep cards and sessions from the active brief.
Runs adaptive mock interviews and stores scored debriefs for later review.

Override Loop

Trust

Lets users dispute verdicts, add evidence, or mark a requirement as not applicable.
Re-runs the gap report with overrides so visible recommendations stay current.

Engagement System

Follow-up

Schedules countdown, dropoff, and weekly digest messages with timezone-aware logic.
Deduplicates sends and writes outcomes back into the durable record.

MCP Surface

Extension

Exposes the same business logic to AI clients so first-party and external workflows stay aligned.
Keeps saved gap context portable without creating a second source of truth.

Down / Grounded intelligenceThe server sends structured resume, job, and skill context to the provider cascade, then applies deterministic scoring before anything becomes user-facing.

Provider Cascade / Same Contracts assessment / extraction / drills / mock interviews / debriefs

Primary Google Gemini Primary reasoning path for skill assessment, narratives, drills, and interview generation.

Retry

Fallback GitHub Models Maintains continuity with compatible contracts when the primary path fails.

Failover

Tertiary OpenAI Final provider path kept at parity for continuity across core workflows.

Grounded context

Prompts receive resume text, role requirements, matched skills, and saved gap context.

Structured output

Skill verdicts, confidence, evidence, debriefs, and practice data return in predictable shapes.

Thin coverage

When taxonomy coverage is weak, the pipeline can extract role requirements directly from the job description.

Adaptive interview

Mock sessions use full conversation history to ask follow-ups and score the final debrief.

Narrative layer

The same provider chain supports headlines, prep guidance, countdown copy, and user-facing explanations.

Down / Durable recordEvery gap report, override, drill attempt, mock transcript, reminder, and badge writes back into the same preparation record.

Data Foundation / Turso SQLite identity / analyses / practice / progress / audit

Users & Auth

Identity, sessions, verification, timezone, email preferences, and active brief selection.

Ownership

Analyses

Resume PDF, job description, scored gap report, status, overrides, and refine history.

Prep record

Practice Artifacts

Prep cards, drill cards, attempts, mock sessions, transcripts, and scored debriefs.

Active learning

Progress

Checklists, resource completion, daily activity, streaks, and earned badges.

Momentum

Reminder Audit

Sent-email history, deduplication keys, delivery outcomes, and engagement state.

Traceable

Cross-cut / EngagementSaved analyses and user timezone data drive reminders, progress loops, streaks, and badge updates without fragmenting the core record.

Engagement System / Cron + Resend timezone-aware / deduplicated / auditable

Countdown Emails

Timeline-aware reminders keep users moving as interview dates approach.

Timely

Dropoff Nudges

Re-engagement checks detect stalled preparation and route users back to the active brief.

Recovery

Weekly Digest

Progress summaries turn completed work, missed drills, and next actions into a readable update.

Summary

Streaks & Badges

Activity milestones make preparation progress visible and durable.

Motivation

Flow Diagrams / Left to Right gap analysis / practice / interview / refine

Run Gap Analysis

Upload resume
+ paste JD

Validate and
detect role

Assess gap
coverage

Return five
pane brief

Practice Drills

Select skill
gap

Generate or
reuse cards

Flip and
self-grade

Prioritize
missed work

Mock Interview

Start mock
session

Ask adaptive
questions

Preserve
history

Store scored
debrief

Refine & Engage

Add evidence
or dispute

Re-run with
overrides

Update plan
and checklist

Trigger
reminders

Primary data / process flow

Retry / failover / persisted state

Durable / confirmed / trusted path

Gap / attention / intervention point

Back to the case study