# princetyagisec/careerforge-ai architecture

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

- Interactive diagram: https://gitdiagram.com/princetyagisec/careerforge-ai
- Repository: https://github.com/princetyagisec/careerforge-ai

## Overview

CareerForge AI is a local-first career platform whose workflow spans resume intake and analysis, job discovery and normalization, evidence-backed matching, tailored application materials, and application tracking. The React interface communicates with a FastAPI backend; backend product areas persist career and job records locally, while scheduled saved-search monitoring can notify through Telegram. The map preserves README-described capabilities even where implementation excerpts were unavailable; dashed, uncited links mark those unverified runtime relationships.

Main entry points: [`frontend/src/App.tsx`](https://github.com/princetyagisec/careerforge-ai/blob/main/frontend/src/App.tsx) (Workspace UI), [`backend/app/main.py`](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/api/resumes.py`](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/api/resumes.py) (Resume endpoints), [`backend/app/services/resume/tailor_engine.py`](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/resume/tailor_engine.py) (Tailoring and ATS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Career workspace"]
  node_webapp["Workspace UI<br/>[App.tsx]"]
  node_client["API client<br/>[api.ts]"]
  node_jobviews["Job views<br/>[JobsView.tsx]"]
  node_resumeviews["Resume views<br/>[ResumeView.tsx]"]
  node_qualityview["Quality view"]
  node_applicationview["Application view"]
  node_searchview["Saved searches"]
  node_telegramview["Telegram settings<br/>[TelegramView.tsx]"]
end

subgraph group_api["Backend API"]
  node_apiapp["FastAPI app<br/>[main.py]"]
  node_jobapi["Job endpoints<br/>[jobs.py]"]
  node_resumeapi["Resume endpoints<br/>[resumes.py]"]
  node_applicationapi["Application endpoints<br/>[applications.py]"]
  node_searchapi["Search endpoints<br/>[saved_searches.py]"]
end

subgraph group_jobs["Job discovery and matching"]
  node_provider["Provider manager<br/>[manager.py]"]
  node_quality["Job quality<br/>[normalizer.py]"]
  node_freshness["Freshness tracking<br/>[freshness.py]"]
  node_matching["Match engine<br/>[engine.py]"]
end

subgraph group_resume["Resume intelligence"]
  node_parser["Resume processing<br/>[parser.py]"]
  node_resumequality["Resume quality<br/>[quality_engine.py]"]
  node_tailoring["Tailoring and ATS<br/>[tailor_engine.py]"]
  node_exporter["Resume export<br/>[exporter.py]"]
  node_ollama["Local AI<br/>[ollama_client.py]"]
end

subgraph group_state["Career data and automation"]
  node_applications[("Application records<br/>[application.py]")]
  node_jobsdata[("Job records<br/>[job.py]")]
  node_resumedata[("Resume and claims<br/>[resume.py]")]
  node_database[("Local database<br/>[database.py]")]
  node_taskrunner["Search scheduler<br/>[task_runner.py]"]
  node_notifier["Telegram notifier<br/>[notifier.py]"]
end

node_user(("Career seeker"))
node_telegram(("Telegram"))

node_user -->|"uses"| node_webapp
node_webapp -->|"calls"| node_client
node_webapp -->|"renders"| node_jobviews
node_webapp -->|"renders"| node_resumeviews
node_webapp -->|"renders"| node_qualityview
node_webapp -->|"renders"| node_applicationview
node_webapp -->|"renders"| node_searchview
node_webapp -->|"renders"| node_telegramview
node_client -.->|"HTTP requests"| node_apiapp
node_apiapp -->|"registers"| node_jobapi
node_apiapp -->|"registers"| node_resumeapi
node_apiapp -->|"registers"| node_applicationapi
node_apiapp -->|"registers"| node_searchapi
node_jobapi -->|"invokes"| node_provider
node_jobapi -->|"invokes"| node_matching
node_provider -->|"normalizes"| node_quality
node_provider -->|"updates"| node_freshness
node_provider -->|"writes"| node_jobsdata
node_matching -->|"reads claims"| node_resumedata
node_matching -->|"reads requirements"| node_jobsdata
node_resumeapi -.->|"processes uploads"| node_parser
node_resumeapi -.->|"analyzes"| node_resumequality
node_resumeapi -.->|"requests tailoring"| node_tailoring
node_tailoring -.->|"uses match evidence"| node_matching
node_tailoring -.->|"may use AI"| node_ollama
node_tailoring -->|"reads candidate facts"| node_resumedata
node_tailoring -->|"reads job requirements"| node_jobsdata
node_resumeapi -.->|"exports resumes"| node_exporter
node_applicationapi -->|"records activity"| node_applications
node_searchapi -->|"configures searches"| node_taskrunner
node_taskrunner -->|"retrieves listings"| node_provider
node_taskrunner -->|"scores relevance"| node_matching
node_taskrunner -->|"sends alerts"| node_notifier
node_notifier -.->|"notifies"| node_telegram
node_database -->|"backs"| node_jobsdata
node_database -->|"backs"| node_resumedata
node_database -->|"backs"| node_applications

click node_webapp "https://github.com/princetyagisec/careerforge-ai/blob/main/frontend/src/App.tsx"
click node_client "https://github.com/princetyagisec/careerforge-ai/blob/main/frontend/src/api.ts"
click node_jobviews "https://github.com/princetyagisec/careerforge-ai/blob/main/frontend/src/components/JobsView.tsx"
click node_resumeviews "https://github.com/princetyagisec/careerforge-ai/blob/main/frontend/src/components/ResumeView.tsx"
click node_qualityview "https://github.com/princetyagisec/careerforge-ai/blob/main/frontend/src/components/ResumeQualityView.tsx"
click node_applicationview "https://github.com/princetyagisec/careerforge-ai/blob/main/frontend/src/components/ApplicationsView.tsx"
click node_searchview "https://github.com/princetyagisec/careerforge-ai/blob/main/frontend/src/components/SavedSearchesView.tsx"
click node_telegramview "https://github.com/princetyagisec/careerforge-ai/blob/main/frontend/src/components/TelegramView.tsx"
click node_apiapp "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/main.py"
click node_jobapi "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/api/jobs.py"
click node_resumeapi "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/api/resumes.py"
click node_applicationapi "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/api/applications.py"
click node_searchapi "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/api/saved_searches.py"
click node_provider "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/job_providers/manager.py"
click node_quality "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/job_quality/normalizer.py"
click node_freshness "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/job_quality/freshness.py"
click node_matching "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/matching/engine.py"
click node_parser "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/resume/parser.py"
click node_resumequality "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/resume/quality_engine.py"
click node_tailoring "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/resume/tailor_engine.py"
click node_exporter "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/resume/exporter.py"
click node_ollama "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/ai/ollama_client.py"
click node_applications "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/models/application.py"
click node_jobsdata "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/models/job.py"
click node_resumedata "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/models/resume.py"
click node_database "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/core/database.py"
click node_taskrunner "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/scheduler/task_runner.py"
click node_notifier "https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/telegram/notifier.py"

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_webapp,node_client,node_jobviews,node_resumeviews,node_qualityview,node_applicationview,node_searchview,node_telegramview toneBlue
class node_apiapp,node_jobapi,node_resumeapi,node_applicationapi,node_searchapi toneAmber
class node_provider,node_quality,node_freshness,node_matching toneMint
class node_parser,node_resumequality,node_tailoring,node_exporter,node_ollama toneRose
class node_applications,node_jobsdata,node_resumedata,node_database,node_taskrunner,node_notifier,node_user,node_telegram toneIndigo
```

## Components

### Career workspace

- [Workspace UI](https://github.com/princetyagisec/careerforge-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/princetyagisec/careerforge-ai/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Job views](https://github.com/princetyagisec/careerforge-ai/blob/main/frontend/src/components/JobsView.tsx): `frontend/src/components/JobsView.tsx`
- [Resume views](https://github.com/princetyagisec/careerforge-ai/blob/main/frontend/src/components/ResumeView.tsx): `frontend/src/components/ResumeView.tsx`
- [Quality view](https://github.com/princetyagisec/careerforge-ai/blob/main/frontend/src/components/ResumeQualityView.tsx): `frontend/src/components/ResumeQualityView.tsx`
- [Application view](https://github.com/princetyagisec/careerforge-ai/blob/main/frontend/src/components/ApplicationsView.tsx): `frontend/src/components/ApplicationsView.tsx`
- [Saved searches](https://github.com/princetyagisec/careerforge-ai/blob/main/frontend/src/components/SavedSearchesView.tsx): `frontend/src/components/SavedSearchesView.tsx`
- [Telegram settings](https://github.com/princetyagisec/careerforge-ai/blob/main/frontend/src/components/TelegramView.tsx): `frontend/src/components/TelegramView.tsx`

### Backend API

- [FastAPI app](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Job endpoints](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/api/jobs.py): `backend/app/api/jobs.py`
- [Resume endpoints](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/api/resumes.py): `backend/app/api/resumes.py`
- [Application endpoints](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/api/applications.py): `backend/app/api/applications.py`
- [Search endpoints](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/api/saved_searches.py): `backend/app/api/saved_searches.py`

### Job discovery and matching

- [Provider manager](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/job_providers/manager.py): `backend/app/services/job_providers/manager.py`
- [Job quality](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/job_quality/normalizer.py): `backend/app/services/job_quality/normalizer.py`
- [Freshness tracking](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/job_quality/freshness.py): `backend/app/services/job_quality/freshness.py`
- [Match engine](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/matching/engine.py): `backend/app/services/matching/engine.py`

### Resume intelligence

- [Resume processing](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/resume/parser.py): `backend/app/services/resume/parser.py`
- [Resume quality](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/resume/quality_engine.py): `backend/app/services/resume/quality_engine.py`
- [Tailoring and ATS](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/resume/tailor_engine.py): `backend/app/services/resume/tailor_engine.py`
- [Resume export](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/resume/exporter.py): `backend/app/services/resume/exporter.py`
- [Local AI](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/ai/ollama_client.py): `backend/app/services/ai/ollama_client.py`

### Career data and automation

- [Application records](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/models/application.py): `backend/app/models/application.py`
- [Job records](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/models/job.py): `backend/app/models/job.py`
- [Resume and claims](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/models/resume.py): `backend/app/models/resume.py`
- [Local database](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Search scheduler](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/scheduler/task_runner.py): `backend/app/services/scheduler/task_runner.py`
- [Telegram notifier](https://github.com/princetyagisec/careerforge-ai/blob/main/backend/app/services/telegram/notifier.py): `backend/app/services/telegram/notifier.py`

### Other components

- **Career seeker**
- **Telegram**

## Connections

- Career seeker → Workspace UI: uses
- Workspace UI → API client: calls (evidence: `frontend/src/App.tsx`)
- Workspace UI → Job views: renders (evidence: `frontend/src/App.tsx`)
- Workspace UI → Resume views: renders (evidence: `frontend/src/App.tsx`)
- Workspace UI → Quality view: renders (evidence: `frontend/src/App.tsx`)
- Workspace UI → Application view: renders (evidence: `frontend/src/App.tsx`)
- Workspace UI → Saved searches: renders (evidence: `frontend/src/App.tsx`)
- Workspace UI → Telegram settings: renders (evidence: `frontend/src/App.tsx`)
- API client → FastAPI app: HTTP requests
- FastAPI app → Job endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI app → Resume endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI app → Application endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI app → Search endpoints: registers (evidence: `backend/app/main.py`)
- Job endpoints → Provider manager: invokes (evidence: `backend/app/api/jobs.py`)
- Job endpoints → Match engine: invokes (evidence: `backend/app/api/jobs.py`)
- Provider manager → Job quality: normalizes (evidence: `backend/app/services/job_providers/manager.py`)
- Provider manager → Freshness tracking: updates (evidence: `backend/app/services/job_providers/manager.py`)
- Provider manager → Job records: writes (evidence: `backend/app/services/job_providers/manager.py`)
- Match engine → Resume and claims: reads claims (evidence: `backend/app/services/matching/engine.py`)
- Match engine → Job records: reads requirements (evidence: `backend/app/services/matching/engine.py`)
- Resume endpoints → Resume processing: processes uploads
- Resume endpoints → Resume quality: analyzes
- Resume endpoints → Tailoring and ATS: requests tailoring
- Tailoring and ATS → Match engine: uses match evidence
- Tailoring and ATS → Local AI: may use AI
- Tailoring and ATS → Resume and claims: reads candidate facts (evidence: `backend/app/services/resume/tailor_engine.py`)
- Tailoring and ATS → Job records: reads job requirements (evidence: `backend/app/services/resume/tailor_engine.py`)
- Resume endpoints → Resume export: exports resumes
- Application endpoints → Application records: records activity (evidence: `backend/app/api/applications.py`)
- Search endpoints → Search scheduler: configures searches (evidence: `backend/app/api/saved_searches.py`)
- Search scheduler → Provider manager: retrieves listings (evidence: `backend/app/services/scheduler/task_runner.py`)
- Search scheduler → Match engine: scores relevance (evidence: `backend/app/services/scheduler/task_runner.py`)
- Search scheduler → Telegram notifier: sends alerts (evidence: `backend/app/services/scheduler/task_runner.py`)
- Telegram notifier → Telegram: notifies
- Local database → Job records: backs (evidence: `backend/app/models/job.py`)
- Local database → Resume and claims: backs (evidence: `backend/app/models/resume.py`)
- Local database → Application records: backs (evidence: `backend/app/models/application.py`)
