# shreyaa310805/ai-career-assistant architecture

> Architecture diagram of the GitHub repository shreyaa310805/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/shreyaa310805/ai-career-assistant
- Repository: https://github.com/shreyaa310805/ai-career-assistant

## Overview

AI Career Assistant turns a resume and job description into a free ATS assessment, then supports Premium users with application tracking and per-role career intelligence. The central path is upload/paste, parse, score, and report; the Premium branch adds saved resume versions and career views. Authentication and simulated upgrade gate those surfaces. The README documents several workspace capabilities whose individual implementations were not sampled, so those are represented at their existing frontend page paths without asserting unverified backend call chains. Interview preparation is explicitly a placeholder.

Main entry points: [`frontend/app/layout.tsx`](https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/layout.tsx) (Web application), [`backend/app/services/resumes/pipeline.py`](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/services/resumes/pipeline.py) (Ingest and analyze), [`backend/app/api/deps.py`](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/api/deps.py) (Access checks), [`frontend/app/applications/[id]/page.tsx`](https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/applications/%5Bid%5D/page.tsx) (Role workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Frontend experience"]
  node_web["Web application<br/>[layout.tsx]"]
  node_authui["Sign-in forms<br/>[auth-form.tsx]"]
  node_scanui["Resume scan<br/>[scan-panel.tsx]"]
  node_reportui["Analysis report"]
  node_upgradeui["Upgrade page<br/>[page.tsx]"]
  node_applicationsui["Application tracker<br/>[page.tsx]"]
  node_workspaceui["Role workspace<br/>[page.tsx]"]
  node_careerui["Career insights<br/>[page.tsx]"]
  node_versionsui["Resume versions<br/>[page.tsx]"]
end

subgraph group_identity["Identity and access"]
  node_authapi["Authentication routes<br/>[auth.py]"]
  node_access["Access checks<br/>[deps.py]"]
  node_billing["Mock billing<br/>[billing.py]"]
  node_userdb[("User records<br/>[user.py]")]
end

subgraph group_ats["Resume intelligence"]
  node_quickscan["Free scan route<br/>[quick_scan.py]"]
  node_resumeroutes["Resume routes<br/>[resumes.py]"]
  node_pipeline["Ingest and analyze<br/>[pipeline.py]"]
  node_extraction["Document extraction<br/>[extraction.py]"]
  node_parsing["Structured parsing<br/>[gemini_service.py]"]
  node_atsengine["ATS scoring<br/>[ats_engine.py]"]
  node_storage["Private file storage<br/>[storage.py]"]
  node_resumedb[("Resume records<br/>[resume.py]")]
end

subgraph group_workspace["Application workspace"]
  node_applicationsapi["Application tracker API<br/>[applications.py]"]
  node_applicationmodel[("Application records<br/>[application.py]")]
  node_careerapi["Career intelligence API<br/>[career.py]"]
  node_workspacefeatures["Role intelligence views<br/>[page.tsx]"]
end

subgraph group_interview["Interview placeholder"]
  node_interviewui["Interview placeholder<br/>[page.tsx]"]
  node_interviewapi["Interview routes<br/>[interviews.py]"]
end

node_seeker(("Career seeker"))

node_seeker -->|"uses"| node_web
node_web -.->|"presents"| node_authui
node_authui -.->|"authenticates"| node_authapi
node_authapi -->|"issues credentials"| node_access
node_access -->|"checks identity"| node_userdb
node_web -.->|"offers scan"| node_scanui
node_scanui -.->|"submits documents"| node_quickscan
node_quickscan -->|"authorizes"| node_access
node_quickscan -->|"runs pipeline"| node_pipeline
node_resumeroutes -->|"runs pipeline"| node_pipeline
node_pipeline -->|"extracts text"| node_extraction
node_pipeline -->|"parses content"| node_parsing
node_pipeline -->|"calculates scores"| node_atsengine
node_pipeline -->|"stores upload"| node_storage
node_pipeline -->|"persists reports"| node_resumedb
node_quickscan -.->|"returns assessment"| node_reportui
node_web -.->|"offers upgrade"| node_upgradeui
node_upgradeui -.->|"requests upgrade"| node_billing
node_billing -->|"updates plan"| node_userdb
node_web -.->|"opens tracker"| node_applicationsui
node_applicationsui -.->|"manages roles"| node_applicationsapi
node_applicationsapi -->|"requires premium"| node_access
node_applicationsapi -->|"reads and writes"| node_applicationmodel
node_web -.->|"opens role workspace"| node_workspaceui
node_workspaceui -.->|"shows capabilities"| node_workspacefeatures
node_workspaceui -.->|"opens versions"| node_versionsui
node_versionsui -.->|"manages versions"| node_resumeroutes
node_web -.->|"opens insights"| node_careerui
node_careerui -.->|"requests intelligence"| node_careerapi
node_careerapi -->|"requires premium"| node_access
node_careerapi -->|"reads applications"| node_applicationmodel
node_careerapi -->|"reads ATS reports"| node_resumedb
node_workspaceui -.->|"offers placeholder"| node_interviewui
node_interviewapi -->|"checks user"| node_access
node_interviewapi -->|"checks application"| node_applicationmodel

click node_web "https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/layout.tsx"
click node_authui "https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/components/auth-form.tsx"
click node_scanui "https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/components/scan-panel.tsx"
click node_reportui "https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/components/analysis-report.tsx"
click node_upgradeui "https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/upgrade/page.tsx"
click node_applicationsui "https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/applications/page.tsx"
click node_workspaceui "https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/applications/%5Bid%5D/page.tsx"
click node_careerui "https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/career/page.tsx"
click node_versionsui "https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/applications/%5Bid%5D/versions/page.tsx"
click node_authapi "https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/api/routes/auth.py"
click node_access "https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/api/deps.py"
click node_billing "https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/api/routes/billing.py"
click node_quickscan "https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/api/routes/quick_scan.py"
click node_resumeroutes "https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/api/routes/resumes.py"
click node_pipeline "https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/services/resumes/pipeline.py"
click node_extraction "https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/services/resumes/extraction.py"
click node_parsing "https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/services/resumes/gemini_service.py"
click node_atsengine "https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/services/resumes/ats_engine.py"
click node_storage "https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/services/resumes/storage.py"
click node_resumedb "https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/models/resume.py"
click node_applicationsapi "https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/api/routes/applications.py"
click node_applicationmodel "https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/models/application.py"
click node_careerapi "https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/api/routes/career.py"
click node_workspacefeatures "https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/applications/%5Bid%5D/skill-gap/page.tsx"
click node_interviewui "https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/applications/%5Bid%5D/interview/page.tsx"
click node_interviewapi "https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/api/routes/interviews.py"
click node_userdb "https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/models/user.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_web,node_authui,node_scanui,node_reportui,node_upgradeui,node_applicationsui,node_workspaceui,node_careerui,node_versionsui toneBlue
class node_authapi,node_access,node_billing,node_userdb toneAmber
class node_quickscan,node_resumeroutes,node_pipeline,node_extraction,node_parsing,node_atsengine,node_storage,node_resumedb toneMint
class node_applicationsapi,node_applicationmodel,node_careerapi,node_workspacefeatures toneRose
class node_interviewui,node_interviewapi,node_seeker toneIndigo
```

## Components

### Frontend experience

- [Web application](https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/layout.tsx): `frontend/app/layout.tsx`
- [Sign-in forms](https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/components/auth-form.tsx): `frontend/components/auth-form.tsx`
- [Resume scan](https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/components/scan-panel.tsx): `frontend/components/scan-panel.tsx`
- [Analysis report](https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/components/analysis-report.tsx): `frontend/components/analysis-report.tsx`
- [Upgrade page](https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/upgrade/page.tsx): `frontend/app/upgrade/page.tsx`
- [Application tracker](https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/applications/page.tsx): `frontend/app/applications/page.tsx`
- [Role workspace](https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/applications/%5Bid%5D/page.tsx): `frontend/app/applications/[id]/page.tsx`
- [Career insights](https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/career/page.tsx): `frontend/app/career/page.tsx`
- [Resume versions](https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/applications/%5Bid%5D/versions/page.tsx): `frontend/app/applications/[id]/versions/page.tsx`

### Identity and access

- [Authentication routes](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/api/routes/auth.py): `backend/app/api/routes/auth.py`
- [Access checks](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`
- [Mock billing](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/api/routes/billing.py): `backend/app/api/routes/billing.py`
- [User records](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/models/user.py): `backend/app/models/user.py`

### Resume intelligence

- [Free scan route](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/api/routes/quick_scan.py): `backend/app/api/routes/quick_scan.py`
- [Resume routes](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/api/routes/resumes.py): `backend/app/api/routes/resumes.py`
- [Ingest and analyze](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/services/resumes/pipeline.py): `backend/app/services/resumes/pipeline.py`
- [Document extraction](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/services/resumes/extraction.py): `backend/app/services/resumes/extraction.py`
- [Structured parsing](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/services/resumes/gemini_service.py): `backend/app/services/resumes/gemini_service.py`
- [ATS scoring](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/services/resumes/ats_engine.py): `backend/app/services/resumes/ats_engine.py`
- [Private file storage](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/services/resumes/storage.py): `backend/app/services/resumes/storage.py`
- [Resume records](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/models/resume.py): `backend/app/models/resume.py`

### Application workspace

- [Application tracker API](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/api/routes/applications.py): `backend/app/api/routes/applications.py`
- [Application records](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/models/application.py): `backend/app/models/application.py`
- [Career intelligence API](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/api/routes/career.py): `backend/app/api/routes/career.py`
- [Role intelligence views](https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/applications/%5Bid%5D/skill-gap/page.tsx): `frontend/app/applications/[id]/skill-gap/page.tsx`

### Interview placeholder

- [Interview placeholder](https://github.com/shreyaa310805/ai-career-assistant/blob/main/frontend/app/applications/%5Bid%5D/interview/page.tsx): `frontend/app/applications/[id]/interview/page.tsx`
- [Interview routes](https://github.com/shreyaa310805/ai-career-assistant/blob/main/backend/app/api/routes/interviews.py): `backend/app/api/routes/interviews.py`

### Other components

- **Career seeker**

## Connections

- Career seeker → Web application: uses (evidence: `README.md`)
- Web application → Sign-in forms: presents
- Sign-in forms → Authentication routes: authenticates
- Authentication routes → Access checks: issues credentials (evidence: `backend/app/api/routes/auth.py`)
- Access checks → User records: checks identity (evidence: `backend/app/api/deps.py`)
- Web application → Resume scan: offers scan
- Resume scan → Free scan route: submits documents
- Free scan route → Access checks: authorizes (evidence: `backend/app/api/routes/quick_scan.py`)
- Free scan route → Ingest and analyze: runs pipeline (evidence: `backend/app/api/routes/quick_scan.py`)
- Resume routes → Ingest and analyze: runs pipeline (evidence: `backend/app/api/routes/resumes.py`)
- Ingest and analyze → Document extraction: extracts text (evidence: `backend/app/services/resumes/pipeline.py`)
- Ingest and analyze → Structured parsing: parses content (evidence: `backend/app/services/resumes/pipeline.py`)
- Ingest and analyze → ATS scoring: calculates scores (evidence: `backend/app/services/resumes/pipeline.py`)
- Ingest and analyze → Private file storage: stores upload (evidence: `backend/app/services/resumes/pipeline.py`)
- Ingest and analyze → Resume records: persists reports (evidence: `backend/app/services/resumes/pipeline.py`)
- Free scan route → Analysis report: returns assessment
- Web application → Upgrade page: offers upgrade
- Upgrade page → Mock billing: requests upgrade
- Mock billing → User records: updates plan (evidence: `backend/app/api/routes/billing.py`)
- Web application → Application tracker: opens tracker
- Application tracker → Application tracker API: manages roles
- Application tracker API → Access checks: requires premium (evidence: `backend/app/api/routes/applications.py`)
- Application tracker API → Application records: reads and writes (evidence: `backend/app/api/routes/applications.py`)
- Web application → Role workspace: opens role workspace
- Role workspace → Role intelligence views: shows capabilities
- Role workspace → Resume versions: opens versions
- Resume versions → Resume routes: manages versions
- Web application → Career insights: opens insights
- Career insights → Career intelligence API: requests intelligence
- Career intelligence API → Access checks: requires premium (evidence: `backend/app/api/routes/career.py`)
- Career intelligence API → Application records: reads applications (evidence: `backend/app/api/routes/career.py`)
- Career intelligence API → Resume records: reads ATS reports (evidence: `backend/app/api/routes/career.py`)
- Role workspace → Interview placeholder: offers placeholder (evidence: `README.md`)
- Interview routes → Access checks: checks user (evidence: `backend/app/api/routes/interviews.py`)
- Interview routes → Application records: checks application (evidence: `backend/app/api/routes/interviews.py`)
