# eklakh-ai-engineer/ai-job-agent architecture

> Architecture diagram of the GitHub repository eklakh-ai-engineer/ai-job-agent, 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/eklakh-ai-engineer/ai-job-agent
- Repository: https://github.com/eklakh-ai-engineer/ai-job-agent

## Overview

AI Job Agent is currently a FastAPI backend foundation, not the fully autonomous career agent described as future scope. The main user flow is a client calling versioned API routes for account access, job browsing/search, candidate documents, evaluation, and application tracking; application submission is guarded and human-controlled. The graph includes major implemented service areas and the embedding/search path. Several subsystems are represented from the source index or README rather than inspected excerpts, so their internal links are omitted where call ownership is not established.

Main entry points: [`backend/app/api/v1/router.py`](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/router.py) (V1 routes), [`backend/app/services/browser_automation_service.py`](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/browser_automation_service.py) (Guarded submission), [`backend/app/services/embedding_service.py`](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/embedding_service.py) (Embedding service), [`backend/app/api/deps.py`](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/deps.py) (Auth dependencies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_api_app["API application<br/>[main.py]"]
  node_v1_router["V1 routes<br/>[router.py]"]
  node_auth["Authentication routes<br/>[auth.py]"]
  node_user_routes["User routes<br/>[users.py]"]
  node_api_deps["Auth dependencies<br/>[deps.py]"]
end

subgraph group_career["Career workflows"]
  node_job_routes["Job routes<br/>[jobs.py]"]
  node_jobs[("Job records<br/>[job.py]")]
  node_candidate_routes["Candidate knowledge API<br/>[candidate_kb.py]"]
  node_candidate_service["Candidate knowledge"]
  node_document_routes["Document API<br/>[documents.py]"]
  node_document_service["Document service"]
  node_document_storage["Document storage"]
  node_applications_api["Application API<br/>[applications.py]"]
  node_application_service["Application workflow"]
  node_browser_automation["Guarded submission"]
  node_agents["ATS adapters and agents"]
end

subgraph group_intelligence["Search and evaluation"]
  node_semantic_api["Semantic search API<br/>[semantic_search.py]"]
  node_semantic_service["Semantic search"]
  node_embedding_service["Embedding service"]
  node_embedding_core["Embedding providers<br/>[embeddings.py]"]
  node_embedding_tasks["Embedding tasks<br/>[embeddings.py]"]
  node_evaluation_api["Evaluation API<br/>[evaluation.py]"]
  node_evaluation_service["Evaluation service"]
  node_evaluation_engine["Evaluation engine<br/>[evaluator.py]"]
  node_evaluation_models["Evaluation schemas<br/>[models.py]"]
  node_candidate_models["Candidate models"]
  node_candidate_loader["Candidate loader"]
end

subgraph group_runtime["Services and persistence"]
  node_database[("Database sessions<br/>[database.py]")]
  node_config["Runtime configuration<br/>[config.py]"]
  node_celery["Task queue setup<br/>[celery_app.py]"]
  node_application_tasks["Application tasks<br/>[applications.py]"]
  node_notification_service["Notifications"]
end

node_client(("Client"))
node_embedding_provider(("Embedding API provider"))

node_client -->|"sends requests"| node_api_app
node_api_app -->|"mounts routes"| node_v1_router
node_v1_router -->|"registers"| node_auth
node_v1_router -->|"registers"| node_user_routes
node_v1_router -->|"registers"| node_job_routes
node_v1_router -->|"registers"| node_candidate_routes
node_v1_router -->|"registers"| node_document_routes
node_v1_router -->|"registers"| node_applications_api
node_v1_router -->|"registers"| node_semantic_api
node_v1_router -->|"registers"| node_evaluation_api
node_auth -->|"uses auth dependencies"| node_api_deps
node_api_deps -->|"gets sessions"| node_database
node_api_deps -->|"reads settings"| node_config
node_job_routes -.->|"serves job data"| node_jobs
node_candidate_routes -->|"delegates to"| node_candidate_service
node_document_routes -->|"uses candidate data"| node_candidate_service
node_document_routes -->|"delegates to"| node_document_service
node_document_service -.->|"uses storage"| node_document_storage
node_applications_api -->|"manages applications"| node_application_service
node_applications_api -.->|"requests submission"| node_browser_automation
node_browser_automation -->|"loads candidate data"| node_candidate_service
node_browser_automation -->|"uses ATS automation"| node_agents
node_application_service -->|"notifies changes"| node_notification_service
node_semantic_api -->|"delegates search"| node_semantic_service
node_semantic_service -->|"creates query vectors"| node_embedding_service
node_embedding_service -->|"requests embeddings"| node_embedding_core
node_embedding_core -->|"calls provider API"| node_embedding_provider
node_semantic_service -->|"queries ranked jobs"| node_jobs
node_embedding_service -->|"writes vectors"| node_jobs
node_embedding_tasks -->|"runs embedding work"| node_embedding_service
node_evaluation_api -->|"delegates evaluation"| node_evaluation_service
node_evaluation_service -.->|"uses evaluator"| node_evaluation_engine
node_evaluation_engine -->|"uses schemas"| node_evaluation_models
node_evaluation_engine -->|"uses candidate types"| node_candidate_models
node_candidate_loader -->|"builds candidate data"| node_candidate_models
node_celery -->|"reads settings"| node_config
node_application_tasks -->|"registers tasks"| node_celery
node_application_tasks -->|"runs submissions"| node_browser_automation
node_database -->|"gets database settings"| node_config

click node_api_app "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/main.py"
click node_v1_router "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/router.py"
click node_auth "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/auth.py"
click node_user_routes "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/users.py"
click node_api_deps "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/deps.py"
click node_job_routes "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/jobs.py"
click node_jobs "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/models/job.py"
click node_candidate_routes "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/candidate_kb.py"
click node_candidate_service "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/candidate_kb_service.py"
click node_document_routes "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/documents.py"
click node_document_service "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/document_service.py"
click node_document_storage "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/document_storage.py"
click node_applications_api "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/applications.py"
click node_application_service "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/application_service.py"
click node_browser_automation "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/browser_automation_service.py"
click node_agents "https://github.com/eklakh-ai-engineer/ai-job-agent/tree/main/backend/app/agents"
click node_semantic_api "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/semantic_search.py"
click node_semantic_service "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/semantic_search_service.py"
click node_embedding_service "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/embedding_service.py"
click node_embedding_core "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/core/embeddings.py"
click node_embedding_tasks "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/tasks/embeddings.py"
click node_evaluation_api "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/evaluation.py"
click node_evaluation_service "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/evaluation_service.py"
click node_evaluation_engine "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/evaluation/evaluator.py"
click node_evaluation_models "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/evaluation/models.py"
click node_candidate_models "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/evaluation/candidate_models.py"
click node_candidate_loader "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/evaluation/candidate_loader.py"
click node_database "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/core/database.py"
click node_config "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/core/config.py"
click node_celery "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/core/celery_app.py"
click node_application_tasks "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/tasks/applications.py"
click node_notification_service "https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/notification_service.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_api_app,node_v1_router,node_auth,node_user_routes,node_api_deps,node_client toneBlue
class node_job_routes,node_jobs,node_candidate_routes,node_candidate_service,node_document_routes,node_document_service,node_document_storage,node_applications_api,node_application_service,node_browser_automation,node_agents toneAmber
class node_semantic_api,node_semantic_service,node_embedding_service,node_embedding_core,node_embedding_tasks,node_evaluation_api,node_evaluation_service,node_evaluation_engine,node_evaluation_models,node_candidate_models,node_candidate_loader,node_embedding_provider toneMint
class node_database,node_config,node_celery,node_application_tasks,node_notification_service toneRose
```

## Components

### API and identity

- [API application](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/main.py): `backend/app/main.py`
- [V1 routes](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Authentication routes](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`
- [User routes](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/users.py): `backend/app/api/v1/users.py`
- [Auth dependencies](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`

### Career workflows

- [Job routes](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/jobs.py): `backend/app/api/v1/jobs.py`
- [Job records](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/models/job.py): `backend/app/models/job.py`
- [Candidate knowledge API](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/candidate_kb.py): `backend/app/api/v1/candidate_kb.py`
- [Candidate knowledge](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/candidate_kb_service.py): `backend/app/services/candidate_kb_service.py`
- [Document API](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/documents.py): `backend/app/api/v1/documents.py`
- [Document service](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/document_service.py): `backend/app/services/document_service.py`
- [Document storage](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/document_storage.py): `backend/app/services/document_storage.py`
- [Application API](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/applications.py): `backend/app/api/v1/applications.py`
- [Application workflow](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/application_service.py): `backend/app/services/application_service.py`
- [Guarded submission](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/browser_automation_service.py): `backend/app/services/browser_automation_service.py`
- [ATS adapters and agents](https://github.com/eklakh-ai-engineer/ai-job-agent/tree/main/backend/app/agents): `backend/app/agents`

### Search and evaluation

- [Semantic search API](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/semantic_search.py): `backend/app/api/v1/semantic_search.py`
- [Semantic search](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/semantic_search_service.py): `backend/app/services/semantic_search_service.py`
- [Embedding service](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/embedding_service.py): `backend/app/services/embedding_service.py`
- [Embedding providers](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/core/embeddings.py): `backend/app/core/embeddings.py`
- [Embedding tasks](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/tasks/embeddings.py): `backend/app/tasks/embeddings.py`
- [Evaluation API](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/api/v1/evaluation.py): `backend/app/api/v1/evaluation.py`
- [Evaluation service](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/evaluation_service.py): `backend/app/services/evaluation_service.py`
- [Evaluation engine](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/evaluation/evaluator.py): `backend/evaluation/evaluator.py`
- [Evaluation schemas](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/evaluation/models.py): `backend/evaluation/models.py`
- [Candidate models](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/evaluation/candidate_models.py): `backend/evaluation/candidate_models.py`
- [Candidate loader](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/evaluation/candidate_loader.py): `backend/evaluation/candidate_loader.py`

### Services and persistence

- [Database sessions](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Runtime configuration](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/core/config.py): `backend/app/core/config.py`
- [Task queue setup](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/core/celery_app.py): `backend/app/core/celery_app.py`
- [Application tasks](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/tasks/applications.py): `backend/app/tasks/applications.py`
- [Notifications](https://github.com/eklakh-ai-engineer/ai-job-agent/blob/main/backend/app/services/notification_service.py): `backend/app/services/notification_service.py`

### Other components

- **Client**
- **Embedding API provider**

## Connections

- Client → API application: sends requests (evidence: `README.md`)
- API application → V1 routes: mounts routes (evidence: `backend/app/main.py`)
- V1 routes → Authentication routes: registers (evidence: `backend/app/api/v1/router.py`)
- V1 routes → User routes: registers (evidence: `backend/app/api/v1/router.py`)
- V1 routes → Job routes: registers (evidence: `backend/app/api/v1/router.py`)
- V1 routes → Candidate knowledge API: registers (evidence: `backend/app/api/v1/router.py`)
- V1 routes → Document API: registers (evidence: `backend/app/api/v1/router.py`)
- V1 routes → Application API: registers (evidence: `backend/app/api/v1/router.py`)
- V1 routes → Semantic search API: registers (evidence: `backend/app/api/v1/router.py`)
- V1 routes → Evaluation API: registers (evidence: `backend/app/api/v1/router.py`)
- Authentication routes → Auth dependencies: uses auth dependencies (evidence: `backend/app/api/v1/auth.py`)
- Auth dependencies → Database sessions: gets sessions (evidence: `backend/app/api/deps.py`)
- Auth dependencies → Runtime configuration: reads settings (evidence: `backend/app/api/deps.py`)
- Job routes → Job records: serves job data
- Candidate knowledge API → Candidate knowledge: delegates to (evidence: `backend/app/api/v1/candidate_kb.py`)
- Document API → Candidate knowledge: uses candidate data (evidence: `backend/app/api/v1/documents.py`)
- Document API → Document service: delegates to (evidence: `backend/app/api/v1/documents.py`)
- Document service → Document storage: uses storage
- Application API → Application workflow: manages applications (evidence: `backend/app/api/v1/applications.py`)
- Application API → Guarded submission: requests submission (evidence: `backend/app/api/v1/applications.py`)
- Guarded submission → Candidate knowledge: loads candidate data (evidence: `backend/app/services/browser_automation_service.py`)
- Guarded submission → ATS adapters and agents: uses ATS automation (evidence: `backend/app/services/browser_automation_service.py`)
- Application workflow → Notifications: notifies changes (evidence: `backend/app/services/application_service.py`)
- Semantic search API → Semantic search: delegates search (evidence: `backend/app/api/v1/semantic_search.py`)
- Semantic search → Embedding service: creates query vectors (evidence: `backend/app/services/semantic_search_service.py`)
- Embedding service → Embedding providers: requests embeddings (evidence: `backend/app/services/embedding_service.py`)
- Embedding providers → Embedding API provider: calls provider API (evidence: `backend/app/core/embeddings.py`)
- Semantic search → Job records: queries ranked jobs (evidence: `backend/app/services/semantic_search_service.py`)
- Embedding service → Job records: writes vectors (evidence: `backend/app/services/embedding_service.py`)
- Embedding tasks → Embedding service: runs embedding work (evidence: `backend/app/tasks/embeddings.py`)
- Evaluation API → Evaluation service: delegates evaluation (evidence: `backend/app/api/v1/evaluation.py`)
- Evaluation service → Evaluation engine: uses evaluator
- Evaluation engine → Evaluation schemas: uses schemas (evidence: `backend/evaluation/evaluator.py`)
- Evaluation engine → Candidate models: uses candidate types (evidence: `backend/evaluation/evaluator.py`)
- Candidate loader → Candidate models: builds candidate data (evidence: `backend/evaluation/candidate_loader.py`)
- Task queue setup → Runtime configuration: reads settings (evidence: `backend/app/core/celery_app.py`)
- Application tasks → Task queue setup: registers tasks (evidence: `backend/app/tasks/applications.py`)
- Application tasks → Guarded submission: runs submissions (evidence: `backend/app/tasks/applications.py`)
- Database sessions → Runtime configuration: gets database settings (evidence: `backend/app/core/database.py`)
