# vamshinethula/ai-career-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/vamshinethula/ai-career-assistant
- Repository: https://github.com/vamshinethula/ai-career-assistant

## Overview

AI Career Assistant is a React/FastAPI application for account-based resume analysis, public remote-job discovery, and job-description comparison. The main user flow is register/log in, upload a PDF, then inspect detected skills and role overlaps or search jobs and compare a description; users can save comparison results. Job discovery includes provider aggregation and optional evidence-aware matching. The graph preserves documented capabilities, but unsampled routes and storage details are represented only where README or source-index evidence supports them.

Main entry points: [`backend/app/routers/resumes.py`](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/routers/resumes.py) (Resume routes), [`frontend/src/services/api.js`](https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/services/api.js) (API client), [`backend/app/main.py`](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/services/job_search.py`](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/services/job_search.py) (Search and snapshots)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_app["Career workspace<br/>[App.jsx]"]
  node_dashboard["Personal dashboard<br/>[Dashboard.jsx]"]
  node_resume_ui["Resume panels<br/>[ResumeList.jsx]"]
  node_job_ui["Jobs for you<br/>[JobsForYou.jsx]"]
  node_compare_ui["Comparison review<br/>[JobComparison.jsx]"]
  node_saved_ui["Saved comparisons"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_identity["Accounts and API"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_user_routes["User routes<br/>[users.py]"]
  node_auth_tokens["Token authentication<br/>[oauth2.py]"]
  node_data_store[("SQLite data store<br/>[database.py]")]
  node_models["User and resume records<br/>[models.py]"]
end

subgraph group_resume["Resume analysis"]
  node_resume_routes["Resume routes<br/>[resumes.py]"]
  node_pdf_parser["PDF text extraction<br/>[resume_parser.py]"]
  node_skill_extract["Skill extraction<br/>[skill_extractor.py]"]
  node_role_match["Example role overlaps<br/>[role_matcher.py]"]
end

subgraph group_jobs["Job discovery"]
  node_job_routes["Job search routes<br/>[jobs.py]"]
  node_job_search["Search and snapshots<br/>[job_search.py]"]
  node_provider["Job providers<br/>[job_provider.py]"]
  node_job_schemas["Job result contracts<br/>[job_schemas.py]"]
  node_job_matcher["Job matching<br/>[job_matcher.py]"]
  node_evidence_matcher["Evidence-aware matching<br/>[matcher.py]"]
end

subgraph group_compare["Job comparison"]
  node_review_score["Reviewed score<br/>[reviewedScore.js]"]
  node_comparison_service["Description comparison<br/>[job_comparison.py]"]
  node_comparison_export["Comparison download"]
end

node_person(("Career seeker"))
node_external_jobs["Public job sources"]

node_person -->|"uses"| node_app
node_app -->|"renders"| node_dashboard
node_app -.->|"session requests"| node_api_client
node_dashboard -.->|"presents resumes"| node_resume_ui
node_dashboard -.->|"presents jobs"| node_job_ui
node_resume_ui -.->|"loads resume data"| node_api_client
node_job_ui -->|"requests jobs"| node_api_client
node_compare_ui -->|"compares and saves"| node_api_client
node_compare_ui -->|"opens saved results"| node_saved_ui
node_compare_ui -->|"calculates review"| node_review_score
node_saved_ui -->|"loads saved results"| node_api_client
node_saved_ui -->|"downloads summary"| node_comparison_export
node_api_client -.->|"HTTP requests"| node_backend
node_backend -->|"routes"| node_auth_routes
node_backend -->|"routes"| node_user_routes
node_backend -->|"routes"| node_resume_routes
node_backend -->|"routes"| node_job_routes
node_auth_routes -->|"issues tokens"| node_auth_tokens
node_auth_routes -->|"reads and writes"| node_data_store
node_auth_tokens -->|"loads user"| node_models
node_resume_routes -.->|"checks ownership"| node_auth_tokens
node_resume_routes -->|"reads and writes"| node_models
node_resume_routes -->|"extracts text"| node_pdf_parser
node_resume_routes -->|"detects skills"| node_skill_extract
node_resume_routes -->|"scores overlaps"| node_role_match
node_resume_routes -->|"compares description"| node_comparison_service
node_job_routes -->|"searches listings"| node_job_search
node_job_search -->|"fetches listings"| node_provider
node_provider -.->|"queries sources"| node_external_jobs
node_job_search -->|"scores postings"| node_job_matcher
node_job_matcher -->|"extracts skills"| node_skill_extract
node_job_search -->|"optional evidence match"| node_evidence_matcher
node_job_search -->|"stores snapshots"| node_models
node_job_routes -->|"uses contracts"| node_job_schemas

click node_app "https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/App.jsx"
click node_dashboard "https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/components/Dashboard.jsx"
click node_resume_ui "https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/components/ResumeList.jsx"
click node_job_ui "https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/components/JobsForYou.jsx"
click node_compare_ui "https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/components/JobComparison.jsx"
click node_saved_ui "https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/components/SavedComparisons.jsx"
click node_review_score "https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/services/reviewedScore.js"
click node_api_client "https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/services/api.js"
click node_backend "https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/routers/auth.py"
click node_resume_routes "https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/routers/resumes.py"
click node_user_routes "https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/routers/users.py"
click node_auth_tokens "https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/oauth2.py"
click node_data_store "https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/database.py"
click node_models "https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/models.py"
click node_pdf_parser "https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/services/resume_parser.py"
click node_skill_extract "https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/services/skill_extractor.py"
click node_role_match "https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/services/role_matcher.py"
click node_job_routes "https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/routers/jobs.py"
click node_job_search "https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/services/job_search.py"
click node_provider "https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/services/job_provider.py"
click node_job_schemas "https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/job_schemas.py"
click node_job_matcher "https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/services/job_matcher.py"
click node_evidence_matcher "https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/services/occupational_evidence/matcher.py"
click node_comparison_service "https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/services/job_comparison.py"
click node_comparison_export "https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/services/comparisonExport.js"

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_app,node_dashboard,node_resume_ui,node_job_ui,node_compare_ui,node_saved_ui,node_api_client toneBlue
class node_backend,node_auth_routes,node_user_routes,node_auth_tokens,node_data_store,node_models toneAmber
class node_resume_routes,node_pdf_parser,node_skill_extract,node_role_match toneMint
class node_job_routes,node_job_search,node_provider,node_job_schemas,node_job_matcher,node_evidence_matcher toneRose
class node_review_score,node_comparison_service,node_comparison_export,node_person,node_external_jobs toneIndigo
```

## Components

### Web interface

- [Career workspace](https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Personal dashboard](https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/components/Dashboard.jsx): `frontend/src/components/Dashboard.jsx`
- [Resume panels](https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/components/ResumeList.jsx): `frontend/src/components/ResumeList.jsx`
- [Jobs for you](https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/components/JobsForYou.jsx): `frontend/src/components/JobsForYou.jsx`
- [Comparison review](https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/components/JobComparison.jsx): `frontend/src/components/JobComparison.jsx`
- [Saved comparisons](https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/components/SavedComparisons.jsx): `frontend/src/components/SavedComparisons.jsx`
- [API client](https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### Accounts and API

- [FastAPI application](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication routes](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [User routes](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/routers/users.py): `backend/app/routers/users.py`
- [Token authentication](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/oauth2.py): `backend/app/oauth2.py`
- [SQLite data store](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/database.py): `backend/app/database.py`
- [User and resume records](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/models.py): `backend/app/models.py`

### Resume analysis

- [Resume routes](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/routers/resumes.py): `backend/app/routers/resumes.py`
- [PDF text extraction](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/services/resume_parser.py): `backend/app/services/resume_parser.py`
- [Skill extraction](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/services/skill_extractor.py): `backend/app/services/skill_extractor.py`
- [Example role overlaps](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/services/role_matcher.py): `backend/app/services/role_matcher.py`

### Job discovery

- [Job search routes](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/routers/jobs.py): `backend/app/routers/jobs.py`
- [Search and snapshots](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/services/job_search.py): `backend/app/services/job_search.py`
- [Job providers](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/services/job_provider.py): `backend/app/services/job_provider.py`
- [Job result contracts](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/job_schemas.py): `backend/app/job_schemas.py`
- [Job matching](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/services/job_matcher.py): `backend/app/services/job_matcher.py`
- [Evidence-aware matching](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/services/occupational_evidence/matcher.py): `backend/app/services/occupational_evidence/matcher.py`

### Job comparison

- [Reviewed score](https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/services/reviewedScore.js): `frontend/src/services/reviewedScore.js`
- [Description comparison](https://github.com/vamshinethula/ai-career-assistant/blob/main/backend/app/services/job_comparison.py): `backend/app/services/job_comparison.py`
- [Comparison download](https://github.com/vamshinethula/ai-career-assistant/blob/main/frontend/src/services/comparisonExport.js): `frontend/src/services/comparisonExport.js`

### Other components

- **Career seeker**
- **Public job sources**

## Connections

- Career seeker → Career workspace: uses (evidence: `frontend/src/App.jsx`)
- Career workspace → Personal dashboard: renders (evidence: `frontend/src/App.jsx`)
- Career workspace → API client: session requests
- Personal dashboard → Resume panels: presents resumes
- Personal dashboard → Jobs for you: presents jobs
- Resume panels → API client: loads resume data
- Jobs for you → API client: requests jobs
- Comparison review → API client: compares and saves (evidence: `frontend/src/components/JobComparison.jsx`)
- Comparison review → Saved comparisons: opens saved results (evidence: `frontend/src/components/JobComparison.jsx`)
- Comparison review → Reviewed score: calculates review (evidence: `frontend/src/components/JobComparison.jsx`)
- Saved comparisons → API client: loads saved results (evidence: `frontend/src/components/SavedComparisons.jsx`)
- Saved comparisons → Comparison download: downloads summary (evidence: `frontend/src/components/SavedComparisons.jsx`)
- API client → FastAPI application: HTTP requests
- FastAPI application → Authentication routes: routes (evidence: `backend/app/main.py`)
- FastAPI application → User routes: routes (evidence: `backend/app/main.py`)
- FastAPI application → Resume routes: routes (evidence: `backend/app/main.py`)
- FastAPI application → Job search routes: routes (evidence: `backend/app/main.py`)
- Authentication routes → Token authentication: issues tokens (evidence: `backend/app/routers/auth.py`)
- Authentication routes → SQLite data store: reads and writes (evidence: `backend/app/routers/auth.py`)
- Token authentication → User and resume records: loads user (evidence: `backend/app/oauth2.py`)
- Resume routes → Token authentication: checks ownership (evidence: `backend/app/routers/resumes.py`)
- Resume routes → User and resume records: reads and writes (evidence: `backend/app/routers/resumes.py`)
- Resume routes → PDF text extraction: extracts text (evidence: `backend/app/routers/resumes.py`)
- Resume routes → Skill extraction: detects skills (evidence: `backend/app/routers/resumes.py`)
- Resume routes → Example role overlaps: scores overlaps (evidence: `backend/app/routers/resumes.py`)
- Resume routes → Description comparison: compares description (evidence: `backend/app/routers/resumes.py`)
- Job search routes → Search and snapshots: searches listings (evidence: `backend/app/routers/jobs.py`)
- Search and snapshots → Job providers: fetches listings (evidence: `backend/app/services/job_search.py`)
- Job providers → Public job sources: queries sources
- Search and snapshots → Job matching: scores postings (evidence: `backend/app/services/job_search.py`)
- Job matching → Skill extraction: extracts skills (evidence: `backend/app/services/job_matcher.py`)
- Search and snapshots → Evidence-aware matching: optional evidence match (evidence: `backend/app/services/job_search.py`)
- Search and snapshots → User and resume records: stores snapshots (evidence: `backend/app/services/job_search.py`)
- Job search routes → Job result contracts: uses contracts (evidence: `backend/app/routers/jobs.py`)
