# ek1gra/preppilot architecture

> Architecture diagram of the GitHub repository ek1gra/preppilot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ek1gra/preppilot
- Repository: https://github.com/ek1gra/preppilot

## Overview

PrepPilot is an AI interview-preparation application. A user signs in, submits a job description, company URL, and interview timeline, then receives a researched kit with requirements, categorized questions, flashcards, and a schedule. The UI supports saving, editing, practice, and schedule viewing; the API handles authentication, kit ownership, generation, validation, and persistence. The README documents public interview research and state-preserving regeneration, but their implementation details are only partly sampled, so those links are documented rather than inferred from unseen code.

Main entry points: [`backend/src/routes/kits.ts`](https://github.com/ek1gra/preppilot/blob/main/backend/src/routes/kits.ts) (Kit routes), [`backend/src/pipeline/orchestrator.ts`](https://github.com/ek1gra/preppilot/blob/main/backend/src/pipeline/orchestrator.ts) (Kit orchestrator), [`frontend/src/app/page.tsx`](https://github.com/ek1gra/preppilot/blob/main/frontend/src/app/page.tsx) (Prep UI), [`backend/src/server.ts`](https://github.com/ek1gra/preppilot/blob/main/backend/src/server.ts) (Express server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend experience"]
  node_web["Prep UI<br/>[page.tsx]"]
  node_builder["Kit editor<br/>[Builder.tsx]"]
  node_practice["Practice mode<br/>[PracticeMode.tsx]"]
  node_scheduleview["Schedule view<br/>[ScheduleView.tsx]"]
  node_frontendtypes["Kit types<br/>[kit.ts]"]
end

subgraph group_api["API and identity"]
  node_server["Express server<br/>[server.ts]"]
  node_authroutes["Auth routes<br/>[auth.ts]"]
  node_kitroutes["Kit routes<br/>[kits.ts]"]
  node_auth["Session auth<br/>[auth.ts]"]
  node_users[("User records<br/>[user.ts]")]
end

subgraph group_research["Research and generation"]
  node_orchestrator["Kit orchestrator<br/>[orchestrator.ts]"]
  node_crawler["Company research<br/>[scraper.ts]"]
  node_extractor["Role extraction<br/>[extractor.ts]"]
  node_generator["Question generation<br/>[generator.ts]"]
  node_coverage["Coverage pass<br/>[coverage.ts]"]
end

subgraph group_kit["Kit lifecycle"]
  node_kitstore[("Kit records<br/>[kit.ts]")]
  node_schedule["Schedule allocator<br/>[scheduler.ts]"]
  node_validation["Kit validation<br/>[schema.ts]"]
  node_kittypes["Kit contract<br/>[kit.ts]"]
end

subgraph group_integrations["External services"]
  node_llm["LLM client<br/>[llm.ts]"]
  node_mongodb[("MongoDB")]
  node_gemini{{"Gemini"}}
end

node_user(("Candidate"))
node_companysites{{"Company sites"}}
node_publicresearch{{"Public interview research"}}

node_user -->|"uses"| node_web
node_web -->|"calls API"| node_server
node_server -->|"mounts"| node_authroutes
node_server -->|"mounts"| node_kitroutes
node_web -->|"renders"| node_builder
node_web -->|"renders"| node_practice
node_web -->|"renders"| node_scheduleview
node_builder -->|"uses"| node_frontendtypes
node_practice -->|"uses"| node_frontendtypes
node_scheduleview -->|"uses"| node_frontendtypes
node_authroutes -->|"checks session"| node_auth
node_authroutes -->|"reads and writes"| node_users
node_kitroutes -->|"requires session"| node_auth
node_kitroutes -->|"reads and writes"| node_kitstore
node_kitroutes -->|"generates kit"| node_orchestrator
node_orchestrator -->|"crawls company"| node_crawler
node_crawler -->|"fetches pages"| node_companysites
node_crawler -->|"searches discussions"| node_publicresearch
node_orchestrator -->|"extracts role"| node_extractor
node_orchestrator -->|"synthesizes brief"| node_extractor
node_orchestrator -->|"generates questions"| node_generator
node_orchestrator -->|"checks coverage"| node_coverage
node_orchestrator -->|"requests second pass"| node_coverage
node_orchestrator -->|"generates flashcards"| node_generator
node_orchestrator -->|"builds schedule"| node_schedule
node_orchestrator -->|"validates kit"| node_validation
node_extractor -->|"requests generation"| node_llm
node_generator -->|"requests generation"| node_llm
node_coverage -->|"requests second pass"| node_llm
node_llm -->|"generates content"| node_gemini
node_kitroutes -->|"rebuilds schedule"| node_schedule
node_kitroutes -->|"validates updates"| node_validation
node_kitroutes -->|"regenerates brief"| node_extractor
node_kitroutes -->|"refreshes research"| node_crawler
node_kitroutes -->|"regenerates category"| node_generator
node_kitroutes -->|"checks regenerated kit"| node_coverage
node_server -->|"connects"| node_mongodb
node_web -->|"saves kits via API"| node_kitstore

click node_web "https://github.com/ek1gra/preppilot/blob/main/frontend/src/app/page.tsx"
click node_builder "https://github.com/ek1gra/preppilot/blob/main/frontend/src/components/Builder.tsx"
click node_practice "https://github.com/ek1gra/preppilot/blob/main/frontend/src/components/PracticeMode.tsx"
click node_scheduleview "https://github.com/ek1gra/preppilot/blob/main/frontend/src/components/ScheduleView.tsx"
click node_frontendtypes "https://github.com/ek1gra/preppilot/blob/main/frontend/src/types/kit.ts"
click node_server "https://github.com/ek1gra/preppilot/blob/main/backend/src/server.ts"
click node_authroutes "https://github.com/ek1gra/preppilot/blob/main/backend/src/routes/auth.ts"
click node_kitroutes "https://github.com/ek1gra/preppilot/blob/main/backend/src/routes/kits.ts"
click node_auth "https://github.com/ek1gra/preppilot/blob/main/backend/src/middleware/auth.ts"
click node_users "https://github.com/ek1gra/preppilot/blob/main/backend/src/models/user.ts"
click node_kitstore "https://github.com/ek1gra/preppilot/blob/main/backend/src/models/kit.ts"
click node_orchestrator "https://github.com/ek1gra/preppilot/blob/main/backend/src/pipeline/orchestrator.ts"
click node_crawler "https://github.com/ek1gra/preppilot/blob/main/backend/src/crawler/scraper.ts"
click node_extractor "https://github.com/ek1gra/preppilot/blob/main/backend/src/pipeline/extractor.ts"
click node_generator "https://github.com/ek1gra/preppilot/blob/main/backend/src/pipeline/generator.ts"
click node_coverage "https://github.com/ek1gra/preppilot/blob/main/backend/src/pipeline/coverage.ts"
click node_schedule "https://github.com/ek1gra/preppilot/blob/main/backend/src/scheduler/scheduler.ts"
click node_validation "https://github.com/ek1gra/preppilot/blob/main/backend/src/types/schema.ts"
click node_kittypes "https://github.com/ek1gra/preppilot/blob/main/backend/src/types/kit.ts"
click node_llm "https://github.com/ek1gra/preppilot/blob/main/backend/src/config/llm.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_builder,node_practice,node_scheduleview,node_frontendtypes,node_publicresearch toneBlue
class node_server,node_authroutes,node_kitroutes,node_auth,node_users toneAmber
class node_orchestrator,node_crawler,node_extractor,node_generator,node_coverage toneMint
class node_kitstore,node_schedule,node_validation,node_kittypes toneRose
class node_llm,node_mongodb,node_gemini,node_user,node_companysites toneIndigo
```

## Components

### Frontend experience

- [Prep UI](https://github.com/ek1gra/preppilot/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Kit editor](https://github.com/ek1gra/preppilot/blob/main/frontend/src/components/Builder.tsx): `frontend/src/components/Builder.tsx`
- [Practice mode](https://github.com/ek1gra/preppilot/blob/main/frontend/src/components/PracticeMode.tsx): `frontend/src/components/PracticeMode.tsx`
- [Schedule view](https://github.com/ek1gra/preppilot/blob/main/frontend/src/components/ScheduleView.tsx): `frontend/src/components/ScheduleView.tsx`
- [Kit types](https://github.com/ek1gra/preppilot/blob/main/frontend/src/types/kit.ts): `frontend/src/types/kit.ts`

### API and identity

- [Express server](https://github.com/ek1gra/preppilot/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [Auth routes](https://github.com/ek1gra/preppilot/blob/main/backend/src/routes/auth.ts): `backend/src/routes/auth.ts`
- [Kit routes](https://github.com/ek1gra/preppilot/blob/main/backend/src/routes/kits.ts): `backend/src/routes/kits.ts`
- [Session auth](https://github.com/ek1gra/preppilot/blob/main/backend/src/middleware/auth.ts): `backend/src/middleware/auth.ts`
- [User records](https://github.com/ek1gra/preppilot/blob/main/backend/src/models/user.ts): `backend/src/models/user.ts`

### Research and generation

- [Kit orchestrator](https://github.com/ek1gra/preppilot/blob/main/backend/src/pipeline/orchestrator.ts): `backend/src/pipeline/orchestrator.ts`
- [Company research](https://github.com/ek1gra/preppilot/blob/main/backend/src/crawler/scraper.ts): `backend/src/crawler/scraper.ts`
- [Role extraction](https://github.com/ek1gra/preppilot/blob/main/backend/src/pipeline/extractor.ts): `backend/src/pipeline/extractor.ts`
- [Question generation](https://github.com/ek1gra/preppilot/blob/main/backend/src/pipeline/generator.ts): `backend/src/pipeline/generator.ts`
- [Coverage pass](https://github.com/ek1gra/preppilot/blob/main/backend/src/pipeline/coverage.ts): `backend/src/pipeline/coverage.ts`

### Kit lifecycle

- [Kit records](https://github.com/ek1gra/preppilot/blob/main/backend/src/models/kit.ts): `backend/src/models/kit.ts`
- [Schedule allocator](https://github.com/ek1gra/preppilot/blob/main/backend/src/scheduler/scheduler.ts): `backend/src/scheduler/scheduler.ts`
- [Kit validation](https://github.com/ek1gra/preppilot/blob/main/backend/src/types/schema.ts): `backend/src/types/schema.ts`
- [Kit contract](https://github.com/ek1gra/preppilot/blob/main/backend/src/types/kit.ts): `backend/src/types/kit.ts`

### External services

- [LLM client](https://github.com/ek1gra/preppilot/blob/main/backend/src/config/llm.ts): `backend/src/config/llm.ts`
- **MongoDB**
- **Gemini**

### Other components

- **Candidate**
- **Company sites**
- **Public interview research**

## Connections

- Candidate → Prep UI: uses (evidence: `README.md`)
- Prep UI → Express server: calls API (evidence: `README.md`)
- Express server → Auth routes: mounts (evidence: `backend/src/server.ts`)
- Express server → Kit routes: mounts (evidence: `backend/src/server.ts`)
- Prep UI → Kit editor: renders (evidence: `frontend/src/app/page.tsx`)
- Prep UI → Practice mode: renders (evidence: `frontend/src/app/page.tsx`)
- Prep UI → Schedule view: renders (evidence: `frontend/src/app/page.tsx`)
- Kit editor → Kit types: uses (evidence: `frontend/src/components/Builder.tsx`)
- Practice mode → Kit types: uses (evidence: `frontend/src/components/PracticeMode.tsx`)
- Schedule view → Kit types: uses (evidence: `frontend/src/components/ScheduleView.tsx`)
- Auth routes → Session auth: checks session (evidence: `backend/src/routes/auth.ts`)
- Auth routes → User records: reads and writes (evidence: `backend/src/routes/auth.ts`)
- Kit routes → Session auth: requires session (evidence: `backend/src/routes/kits.ts`)
- Kit routes → Kit records: reads and writes (evidence: `backend/src/routes/kits.ts`)
- Kit routes → Kit orchestrator: generates kit (evidence: `backend/src/routes/kits.ts`)
- Kit orchestrator → Company research: crawls company (evidence: `backend/src/pipeline/orchestrator.ts`)
- Company research → Company sites: fetches pages (evidence: `backend/src/crawler/scraper.ts`)
- Company research → Public interview research: searches discussions (evidence: `backend/src/crawler/scraper.ts`)
- Kit orchestrator → Role extraction: extracts role (evidence: `backend/src/pipeline/orchestrator.ts`)
- Kit orchestrator → Role extraction: synthesizes brief (evidence: `backend/src/pipeline/orchestrator.ts`)
- Kit orchestrator → Question generation: generates questions (evidence: `backend/src/pipeline/orchestrator.ts`)
- Kit orchestrator → Coverage pass: checks coverage (evidence: `backend/src/pipeline/orchestrator.ts`)
- Kit orchestrator → Coverage pass: requests second pass (evidence: `backend/src/pipeline/orchestrator.ts`)
- Kit orchestrator → Question generation: generates flashcards (evidence: `backend/src/pipeline/orchestrator.ts`)
- Kit orchestrator → Schedule allocator: builds schedule (evidence: `backend/src/pipeline/orchestrator.ts`)
- Kit orchestrator → Kit validation: validates kit (evidence: `backend/src/pipeline/orchestrator.ts`)
- Role extraction → LLM client: requests generation (evidence: `backend/src/pipeline/extractor.ts`)
- Question generation → LLM client: requests generation (evidence: `backend/src/pipeline/generator.ts`)
- Coverage pass → LLM client: requests second pass (evidence: `backend/src/pipeline/coverage.ts`)
- LLM client → Gemini: generates content (evidence: `backend/src/config/llm.ts`)
- Kit routes → Schedule allocator: rebuilds schedule (evidence: `backend/src/routes/kits.ts`)
- Kit routes → Kit validation: validates updates (evidence: `backend/src/routes/kits.ts`)
- Kit routes → Role extraction: regenerates brief (evidence: `backend/src/routes/kits.ts`)
- Kit routes → Company research: refreshes research (evidence: `backend/src/routes/kits.ts`)
- Kit routes → Question generation: regenerates category (evidence: `backend/src/routes/kits.ts`)
- Kit routes → Coverage pass: checks regenerated kit (evidence: `backend/src/routes/kits.ts`)
- Express server → MongoDB: connects (evidence: `backend/src/server.ts`)
- Prep UI → Kit records: saves kits via API (evidence: `README.md`)