# kotraharidutt/jd-agent architecture

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

- Interactive diagram: https://gitdiagram.com/kotraharidutt/jd-agent
- Repository: https://github.com/kotraharidutt/jd-agent

## Overview

Job Agent is a resume-to-job-description gap analyzer. A user submits resume text, target companies, role, and timeline; the agent structures the resume, searches and evaluates company job descriptions, then synthesizes priorities and actions for the report. The sampled source establishes the frontend-to-analysis API flow, validation, authentication, rate limiting, and OpenAI request handling. Some agent implementation is excerpted, so the graph limits internal stage links to the documented and visible workflow; no persistent product data store is evident.

Main entry points: [`api/analyze.ts`](https://github.com/kotraharidutt/jd-agent/blob/main/api/analyze.ts) (Analyze endpoint), [`src/components/ReportPanel/ReportPanel.tsx`](https://github.com/kotraharidutt/jd-agent/blob/main/src/components/ReportPanel/ReportPanel.tsx) (Report panel), [`src/agents/jobAgent.ts`](https://github.com/kotraharidutt/jd-agent/blob/main/src/agents/jobAgent.ts) (Job agent), [`src/App.tsx`](https://github.com/kotraharidutt/jd-agent/blob/main/src/App.tsx) (App controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_app["App controller<br/>[App.tsx]"]
  node_input["Analysis inputs<br/>[InputPanel.tsx]"]
  node_progress["Progress display"]
  node_report["Report panel<br/>[ReportPanel.tsx]"]
  node_companycards["Company gap cards<br/>[CompanyCards.tsx]"]
  node_ranking["Company ranking<br/>[CompanyRanking.tsx]"]
  node_priority["Priority gaps"]
  node_today["Today action<br/>[TodayAction.tsx]"]
end

subgraph group_agent["Analysis workflow"]
  node_agent["Job agent<br/>[jobAgent.ts]"]
  node_profile["Resume profiling<br/>[jobAgent.ts]"]
  node_jd["Company JD analysis<br/>[jobAgent.ts]"]
  node_synthesis["Cross-company synthesis<br/>[jobAgent.ts]"]
  node_llmclient["Validated LLM client<br/>[llmClient.ts]"]
end

subgraph group_contracts["Data contracts"]
  node_schemas["Analysis schemas<br/>[index.ts]"]
  node_requestschema["Request validation<br/>[analyzeRequest.ts]"]
end

subgraph group_server["Analysis API"]
  node_endpoint["Analyze endpoint<br/>[analyze.ts]"]
  node_auth["API key check<br/>[auth.ts]"]
  node_ratelimit["Rate limiting<br/>[rateLimit.ts]"]
  node_errors["Safe error handling<br/>[errorHandler.ts]"]
  node_config["Server configuration<br/>[env.ts]"]
end

node_user(("Job seeker"))
node_openai{{"OpenAI Responses API"}}
node_websearch{{"Web search tool"}}

node_user -->|"enters details"| node_input
node_input -->|"submits analysis"| node_app
node_app -->|"runs workflow"| node_agent
node_agent -->|"returns report"| node_app
node_app -->|"updates status"| node_progress
node_app -->|"provides report"| node_report
node_report -->|"renders company gaps"| node_companycards
node_report -->|"renders ranking"| node_ranking
node_report -->|"renders priorities"| node_priority
node_report -->|"renders next action"| node_today
node_agent -->|"parses resume"| node_profile
node_agent -->|"analyzes companies"| node_jd
node_agent -->|"synthesizes reports"| node_synthesis
node_profile -->|"requests extraction"| node_llmclient
node_jd -->|"requests JD analysis"| node_llmclient
node_synthesis -->|"requests synthesis"| node_llmclient
node_llmclient -->|"validates response"| node_schemas
node_llmclient -->|"posts analysis request"| node_endpoint
node_endpoint -->|"checks API key"| node_auth
node_endpoint -->|"checks client limit"| node_ratelimit
node_endpoint -->|"validates body"| node_requestschema
node_endpoint -->|"loads server settings"| node_config
node_endpoint -->|"sends model request"| node_openai
node_openai -->|"returns response"| node_endpoint
node_openai -.->|"uses optional search"| node_websearch
node_endpoint -->|"sanitizes failures"| node_errors

click node_app "https://github.com/kotraharidutt/jd-agent/blob/main/src/App.tsx"
click node_input "https://github.com/kotraharidutt/jd-agent/blob/main/src/components/InputPanel.tsx"
click node_progress "https://github.com/kotraharidutt/jd-agent/blob/main/src/components/ProgressTracker.tsx"
click node_report "https://github.com/kotraharidutt/jd-agent/blob/main/src/components/ReportPanel/ReportPanel.tsx"
click node_companycards "https://github.com/kotraharidutt/jd-agent/blob/main/src/components/ReportPanel/CompanyCards.tsx"
click node_ranking "https://github.com/kotraharidutt/jd-agent/blob/main/src/components/ReportPanel/CompanyRanking.tsx"
click node_priority "https://github.com/kotraharidutt/jd-agent/blob/main/src/components/ReportPanel/PriorityGapsList.tsx"
click node_today "https://github.com/kotraharidutt/jd-agent/blob/main/src/components/ReportPanel/TodayAction.tsx"
click node_agent "https://github.com/kotraharidutt/jd-agent/blob/main/src/agents/jobAgent.ts"
click node_profile "https://github.com/kotraharidutt/jd-agent/blob/main/src/agents/jobAgent.ts"
click node_jd "https://github.com/kotraharidutt/jd-agent/blob/main/src/agents/jobAgent.ts"
click node_synthesis "https://github.com/kotraharidutt/jd-agent/blob/main/src/agents/jobAgent.ts"
click node_llmclient "https://github.com/kotraharidutt/jd-agent/blob/main/src/api/llmClient.ts"
click node_schemas "https://github.com/kotraharidutt/jd-agent/blob/main/src/schemas/index.ts"
click node_requestschema "https://github.com/kotraharidutt/jd-agent/blob/main/src/schemas/analyzeRequest.ts"
click node_endpoint "https://github.com/kotraharidutt/jd-agent/blob/main/api/analyze.ts"
click node_auth "https://github.com/kotraharidutt/jd-agent/blob/main/api/middleware/auth.ts"
click node_ratelimit "https://github.com/kotraharidutt/jd-agent/blob/main/api/middleware/rateLimit.ts"
click node_errors "https://github.com/kotraharidutt/jd-agent/blob/main/api/lib/errorHandler.ts"
click node_config "https://github.com/kotraharidutt/jd-agent/blob/main/src/lib/config/env.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_app,node_input,node_progress,node_report,node_companycards,node_ranking,node_priority,node_today toneBlue
class node_agent,node_profile,node_jd,node_synthesis,node_llmclient toneAmber
class node_schemas,node_requestschema,node_openai toneMint
class node_endpoint,node_auth,node_ratelimit,node_errors,node_config toneRose
class node_user,node_websearch toneIndigo
```

## Components

### User interface

- [App controller](https://github.com/kotraharidutt/jd-agent/blob/main/src/App.tsx): `src/App.tsx`
- [Analysis inputs](https://github.com/kotraharidutt/jd-agent/blob/main/src/components/InputPanel.tsx): `src/components/InputPanel.tsx`
- [Progress display](https://github.com/kotraharidutt/jd-agent/blob/main/src/components/ProgressTracker.tsx): `src/components/ProgressTracker.tsx`
- [Report panel](https://github.com/kotraharidutt/jd-agent/blob/main/src/components/ReportPanel/ReportPanel.tsx): `src/components/ReportPanel/ReportPanel.tsx`
- [Company gap cards](https://github.com/kotraharidutt/jd-agent/blob/main/src/components/ReportPanel/CompanyCards.tsx): `src/components/ReportPanel/CompanyCards.tsx`
- [Company ranking](https://github.com/kotraharidutt/jd-agent/blob/main/src/components/ReportPanel/CompanyRanking.tsx): `src/components/ReportPanel/CompanyRanking.tsx`
- [Priority gaps](https://github.com/kotraharidutt/jd-agent/blob/main/src/components/ReportPanel/PriorityGapsList.tsx): `src/components/ReportPanel/PriorityGapsList.tsx`
- [Today action](https://github.com/kotraharidutt/jd-agent/blob/main/src/components/ReportPanel/TodayAction.tsx): `src/components/ReportPanel/TodayAction.tsx`

### Analysis workflow

- [Job agent](https://github.com/kotraharidutt/jd-agent/blob/main/src/agents/jobAgent.ts): `src/agents/jobAgent.ts`
- [Resume profiling](https://github.com/kotraharidutt/jd-agent/blob/main/src/agents/jobAgent.ts): `src/agents/jobAgent.ts`
- [Company JD analysis](https://github.com/kotraharidutt/jd-agent/blob/main/src/agents/jobAgent.ts): `src/agents/jobAgent.ts`
- [Cross-company synthesis](https://github.com/kotraharidutt/jd-agent/blob/main/src/agents/jobAgent.ts): `src/agents/jobAgent.ts`
- [Validated LLM client](https://github.com/kotraharidutt/jd-agent/blob/main/src/api/llmClient.ts): `src/api/llmClient.ts`

### Data contracts

- [Analysis schemas](https://github.com/kotraharidutt/jd-agent/blob/main/src/schemas/index.ts): `src/schemas/index.ts`
- [Request validation](https://github.com/kotraharidutt/jd-agent/blob/main/src/schemas/analyzeRequest.ts): `src/schemas/analyzeRequest.ts`

### Analysis API

- [Analyze endpoint](https://github.com/kotraharidutt/jd-agent/blob/main/api/analyze.ts): `api/analyze.ts`
- [API key check](https://github.com/kotraharidutt/jd-agent/blob/main/api/middleware/auth.ts): `api/middleware/auth.ts`
- [Rate limiting](https://github.com/kotraharidutt/jd-agent/blob/main/api/middleware/rateLimit.ts): `api/middleware/rateLimit.ts`
- [Safe error handling](https://github.com/kotraharidutt/jd-agent/blob/main/api/lib/errorHandler.ts): `api/lib/errorHandler.ts`
- [Server configuration](https://github.com/kotraharidutt/jd-agent/blob/main/src/lib/config/env.ts): `src/lib/config/env.ts`

### Other components

- **Job seeker**
- **OpenAI Responses API**
- **Web search tool**

## Connections

- Job seeker → Analysis inputs: enters details
- Analysis inputs → App controller: submits analysis
- App controller → Job agent: runs workflow
- Job agent → App controller: returns report
- App controller → Progress display: updates status
- App controller → Report panel: provides report
- Report panel → Company gap cards: renders company gaps
- Report panel → Company ranking: renders ranking
- Report panel → Priority gaps: renders priorities
- Report panel → Today action: renders next action
- Job agent → Resume profiling: parses resume
- Job agent → Company JD analysis: analyzes companies
- Job agent → Cross-company synthesis: synthesizes reports
- Resume profiling → Validated LLM client: requests extraction
- Company JD analysis → Validated LLM client: requests JD analysis
- Cross-company synthesis → Validated LLM client: requests synthesis
- Validated LLM client → Analysis schemas: validates response
- Validated LLM client → Analyze endpoint: posts analysis request
- Analyze endpoint → API key check: checks API key
- Analyze endpoint → Rate limiting: checks client limit
- Analyze endpoint → Request validation: validates body
- Analyze endpoint → Server configuration: loads server settings
- Analyze endpoint → OpenAI Responses API: sends model request
- OpenAI Responses API → Analyze endpoint: returns response
- OpenAI Responses API → Web search tool: uses optional search
- Analyze endpoint → Safe error handling: sanitizes failures