# iamkach/careerpilot-ai architecture

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

- Interactive diagram: https://gitdiagram.com/iamkach/careerpilot-ai
- Repository: https://github.com/iamkach/careerpilot-ai

## Overview

Careerpilot AI is a deterministic job-search pipeline: it gathers and scores listings, lets the user review them in Notion, then produces tailored application materials and follow-up guidance. Its optional apply workflow plans answers and can prefill a live form without submitting it. The graph preserves the documented stages and the substantial apply subsystem; some extension-to-server wiring is not shown in the excerpts, so that relationship is marked unverified.

Main entry points: [`run.py`](https://github.com/iamkach/careerpilot-ai/blob/main/run.py) (Stage Runner), [`scripts/utils.py`](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/utils.py) (Notion Tracker), [`scripts/stage2_tailor.py`](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/stage2_tailor.py) (Resume Tailoring), [`scripts/stage6_negotiate.py`](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/stage6_negotiate.py) (Offer Negotiation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Pipeline Control"]
  node_runner["Stage Runner<br/>[run.py]"]
end

subgraph group_discovery["Job Discovery"]
  node_sources["Job Sources<br/>[sources.py]"]
  node_scrape["Scrape &amp; Score<br/>[stage1_scrape.py]"]
  node_review(("Human Review"))
end

subgraph group_career["Career Workflow"]
  node_tailor["Resume Tailoring<br/>[stage2_tailor.py]"]
  node_docx["DOCX Editing<br/>[render_docx.py]"]
  node_outreach["Outreach Drafts<br/>[stage3_outreach.py]"]
  node_digest["Job Digest<br/>[stage4_digest.py]"]
  node_interview["Interview Prep"]
  node_negotiate["Offer Negotiation"]
end

subgraph group_apply["Application Assist"]
  node_apply["Application Planner<br/>[autoapply.py]"]
  node_profile["Apply Profile"]
  node_browser["Browser Prefill"]
  node_bridge["Local HTTP Bridge"]
  node_extension["Browser Extension<br/>[content.js]"]
end

subgraph group_shared["Shared Services"]
  node_settings["Profile &amp; Settings<br/>[settings.py]"]
  node_notion[("Notion Tracker<br/>[utils.py]")]
  node_ai["AI Dispatcher<br/>[utils.py]"]
  node_provision["Notion Provisioning"]
end

node_user(("Job Seeker"))
node_boards["Job Boards"]
node_models["AI Providers"]
node_gmail["Gmail"]
node_resume["Base Resume<br/>[resume.example.txt]"]
node_artifacts["Generated Files"]

node_user -->|"runs stages"| node_runner
node_settings -->|"configures"| node_runner
node_runner -->|"dispatches"| node_scrape
node_runner -->|"dispatches"| node_tailor
node_runner -->|"dispatches"| node_outreach
node_runner -->|"dispatches"| node_digest
node_runner -->|"dispatches"| node_interview
node_runner -->|"dispatches"| node_negotiate
node_runner -->|"dispatches"| node_apply
node_runner -->|"initializes"| node_provision
node_scrape -->|"fetches listings"| node_sources
node_sources -->|"queries"| node_boards
node_scrape -->|"scores jobs"| node_ai
node_ai -->|"dispatches calls"| node_models
node_scrape -->|"records jobs"| node_notion
node_user -->|"reviews listings"| node_review
node_review -->|"updates status"| node_notion
node_tailor -->|"reads reviewed jobs"| node_notion
node_tailor -->|"requests edits"| node_ai
node_tailor -->|"applies edits"| node_docx
node_tailor -->|"uses template"| node_resume
node_tailor -->|"writes resumes"| node_artifacts
node_tailor -->|"updates status"| node_notion
node_outreach -->|"drafts messages"| node_ai
node_outreach -->|"writes drafts"| node_artifacts
node_outreach -->|"records confirmed send"| node_notion
node_digest -->|"collects jobs"| node_notion
node_digest -->|"writes digest"| node_artifacts
node_digest -.->|"sends optionally"| node_gmail
node_interview -->|"generates guide"| node_ai
node_interview -->|"writes guide"| node_artifacts
node_interview -->|"updates status"| node_notion
node_negotiate -->|"looks up offer"| node_notion
node_negotiate -->|"generates brief"| node_ai
node_negotiate -->|"writes brief"| node_artifacts
node_negotiate -->|"updates status"| node_notion
node_apply -.->|"reads ready jobs"| node_notion
node_apply -.->|"uses profile"| node_profile
node_apply -->|"hands off plan"| node_browser
node_browser -->|"captures form"| node_artifacts
node_bridge -->|"builds plans"| node_apply
node_bridge -.->|"invokes prefill"| node_browser
node_extension -.->|"exchanges form data"| node_bridge
node_user -.->|"uses extension"| node_extension
node_provision -->|"creates workspace"| node_notion

click node_runner "https://github.com/iamkach/careerpilot-ai/blob/main/run.py"
click node_settings "https://github.com/iamkach/careerpilot-ai/blob/main/config/settings.py"
click node_sources "https://github.com/iamkach/careerpilot-ai/blob/main/scripts/sources.py"
click node_scrape "https://github.com/iamkach/careerpilot-ai/blob/main/scripts/stage1_scrape.py"
click node_notion "https://github.com/iamkach/careerpilot-ai/blob/main/scripts/utils.py"
click node_ai "https://github.com/iamkach/careerpilot-ai/blob/main/scripts/utils.py"
click node_tailor "https://github.com/iamkach/careerpilot-ai/blob/main/scripts/stage2_tailor.py"
click node_docx "https://github.com/iamkach/careerpilot-ai/blob/main/scripts/render_docx.py"
click node_outreach "https://github.com/iamkach/careerpilot-ai/blob/main/scripts/stage3_outreach.py"
click node_digest "https://github.com/iamkach/careerpilot-ai/blob/main/scripts/stage4_digest.py"
click node_interview "https://github.com/iamkach/careerpilot-ai/blob/main/scripts/stage5_interview_prep.py"
click node_negotiate "https://github.com/iamkach/careerpilot-ai/blob/main/scripts/stage6_negotiate.py"
click node_apply "https://github.com/iamkach/careerpilot-ai/blob/main/scripts/autoapply.py"
click node_profile "https://github.com/iamkach/careerpilot-ai/blob/main/scripts/autoapply_profile.py"
click node_browser "https://github.com/iamkach/careerpilot-ai/blob/main/scripts/autoapply_browser.py"
click node_bridge "https://github.com/iamkach/careerpilot-ai/blob/main/scripts/autoapply_server.py"
click node_extension "https://github.com/iamkach/careerpilot-ai/blob/main/extension/content.js"
click node_provision "https://github.com/iamkach/careerpilot-ai/blob/main/scripts/provision_notion.py"
click node_resume "https://github.com/iamkach/careerpilot-ai/blob/main/config/resume.example.txt"

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_runner toneBlue
class node_sources,node_scrape,node_review toneAmber
class node_tailor,node_docx,node_outreach,node_digest,node_interview,node_negotiate toneMint
class node_apply,node_profile,node_browser,node_bridge,node_extension toneRose
class node_settings,node_notion,node_ai,node_provision,node_user,node_boards,node_models,node_gmail,node_artifacts toneIndigo
class node_resume toneTeal
```

## Components

### Pipeline Control

- [Stage Runner](https://github.com/iamkach/careerpilot-ai/blob/main/run.py): `run.py`

### Job Discovery

- [Job Sources](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/sources.py): `scripts/sources.py`
- [Scrape & Score](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/stage1_scrape.py): `scripts/stage1_scrape.py`
- **Human Review**

### Career Workflow

- [Resume Tailoring](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/stage2_tailor.py): `scripts/stage2_tailor.py`
- [DOCX Editing](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/render_docx.py): `scripts/render_docx.py`
- [Outreach Drafts](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/stage3_outreach.py): `scripts/stage3_outreach.py`
- [Job Digest](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/stage4_digest.py): `scripts/stage4_digest.py`
- [Interview Prep](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/stage5_interview_prep.py): `scripts/stage5_interview_prep.py`
- [Offer Negotiation](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/stage6_negotiate.py): `scripts/stage6_negotiate.py`

### Application Assist

- [Application Planner](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/autoapply.py): `scripts/autoapply.py`
- [Apply Profile](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/autoapply_profile.py): `scripts/autoapply_profile.py`
- [Browser Prefill](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/autoapply_browser.py): `scripts/autoapply_browser.py`
- [Local HTTP Bridge](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/autoapply_server.py): `scripts/autoapply_server.py`
- [Browser Extension](https://github.com/iamkach/careerpilot-ai/blob/main/extension/content.js): `extension/content.js`

### Shared Services

- [Profile & Settings](https://github.com/iamkach/careerpilot-ai/blob/main/config/settings.py): `config/settings.py`
- [Notion Tracker](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/utils.py): `scripts/utils.py`
- [AI Dispatcher](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/utils.py): `scripts/utils.py`
- [Notion Provisioning](https://github.com/iamkach/careerpilot-ai/blob/main/scripts/provision_notion.py): `scripts/provision_notion.py`

### Other components

- **Job Seeker**
- **Job Boards**
- **AI Providers**
- **Gmail**
- [Base Resume](https://github.com/iamkach/careerpilot-ai/blob/main/config/resume.example.txt): `config/resume.example.txt`
- **Generated Files**

## Connections

- Job Seeker → Stage Runner: runs stages (evidence: `README.md`)
- Profile & Settings → Stage Runner: configures (evidence: `README.md`)
- Stage Runner → Scrape & Score: dispatches (evidence: `run.py`)
- Stage Runner → Resume Tailoring: dispatches (evidence: `run.py`)
- Stage Runner → Outreach Drafts: dispatches (evidence: `run.py`)
- Stage Runner → Job Digest: dispatches (evidence: `run.py`)
- Stage Runner → Interview Prep: dispatches (evidence: `run.py`)
- Stage Runner → Offer Negotiation: dispatches (evidence: `run.py`)
- Stage Runner → Application Planner: dispatches (evidence: `run.py`)
- Stage Runner → Notion Provisioning: initializes (evidence: `run.py`)
- Scrape & Score → Job Sources: fetches listings (evidence: `scripts/stage1_scrape.py`)
- Job Sources → Job Boards: queries (evidence: `scripts/sources.py`)
- Scrape & Score → AI Dispatcher: scores jobs (evidence: `README.md`)
- AI Dispatcher → AI Providers: dispatches calls (evidence: `scripts/utils.py`)
- Scrape & Score → Notion Tracker: records jobs (evidence: `README.md`)
- Job Seeker → Human Review: reviews listings (evidence: `README.md`)
- Human Review → Notion Tracker: updates status (evidence: `README.md`)
- Resume Tailoring → Notion Tracker: reads reviewed jobs (evidence: `README.md`)
- Resume Tailoring → AI Dispatcher: requests edits (evidence: `scripts/stage2_tailor.py`)
- Resume Tailoring → DOCX Editing: applies edits (evidence: `scripts/stage2_tailor.py`)
- Resume Tailoring → Base Resume: uses template (evidence: `README.md`)
- Resume Tailoring → Generated Files: writes resumes (evidence: `README.md`)
- Resume Tailoring → Notion Tracker: updates status (evidence: `README.md`)
- Outreach Drafts → AI Dispatcher: drafts messages (evidence: `README.md`)
- Outreach Drafts → Generated Files: writes drafts (evidence: `README.md`)
- Outreach Drafts → Notion Tracker: records confirmed send (evidence: `README.md`)
- Job Digest → Notion Tracker: collects jobs (evidence: `README.md`)
- Job Digest → Generated Files: writes digest (evidence: `README.md`)
- Job Digest → Gmail: sends optionally (evidence: `README.md`)
- Interview Prep → AI Dispatcher: generates guide (evidence: `README.md`)
- Interview Prep → Generated Files: writes guide (evidence: `README.md`)
- Interview Prep → Notion Tracker: updates status (evidence: `README.md`)
- Offer Negotiation → Notion Tracker: looks up offer (evidence: `scripts/stage6_negotiate.py`)
- Offer Negotiation → AI Dispatcher: generates brief (evidence: `README.md`)
- Offer Negotiation → Generated Files: writes brief (evidence: `README.md`)
- Offer Negotiation → Notion Tracker: updates status (evidence: `scripts/stage6_negotiate.py`)
- Application Planner → Notion Tracker: reads ready jobs (evidence: `scripts/autoapply.py`)
- Application Planner → Apply Profile: uses profile
- Application Planner → Browser Prefill: hands off plan (evidence: `scripts/autoapply.py`)
- Browser Prefill → Generated Files: captures form (evidence: `scripts/autoapply_browser.py`)
- Local HTTP Bridge → Application Planner: builds plans (evidence: `scripts/autoapply_server.py`)
- Local HTTP Bridge → Browser Prefill: invokes prefill (evidence: `scripts/autoapply_server.py`)
- Browser Extension → Local HTTP Bridge: exchanges form data
- Job Seeker → Browser Extension: uses extension
- Notion Provisioning → Notion Tracker: creates workspace (evidence: `scripts/provision_notion.py`)
