# pashaeimehran/agentic-ai-job-matcher architecture

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

- Interactive diagram: https://gitdiagram.com/pashaeimehran/agentic-ai-job-matcher
- Repository: https://github.com/pashaeimehran/agentic-ai-job-matcher

## Overview

This is an agentic job-matching product: job seekers search German postings, retrieve CV evidence, receive deterministic requirement assessments and scores, and can save jobs or ask an agent to explain results. REST, MCP, the LangGraph agent, and a manual baseline expose shared tools. The graph preserves extraction, hybrid CV retrieval, matching, persistence, and LLM operations. Edges reflect README statements and shown source references/calls; several tool registrations and subsystem internals were not sampled, so those connections rely on the README rather than claims of inspected implementation.

Main entry points: [`src/tools/registry.py`](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/tools/registry.py) (Tool registry), [`src/rag/service.py`](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/rag/service.py) (CV retrieval service), [`src/api/app.py`](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/api/app.py) (FastAPI), [`src/observability/instrumented.py`](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/observability/instrumented.py) (LLM instrumentation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces and agents"]
  node_api["FastAPI<br/>[app.py]"]
  node_mcp["MCP server<br/>[server.py]"]
  node_graph_agent["LangGraph agent<br/>[agent.py]"]
  node_graph_nodes["Graph nodes<br/>[nodes.py]"]
  node_manual_loop["Manual agent loop<br/>[loop.py]"]
end

subgraph group_jobs["Job discovery"]
  node_job_catalog["Job catalog<br/>[jobs.py]"]
  node_job_source["BA job source<br/>[ba_jobsuche.py]"]
  node_job_extraction["Job extraction<br/>[extractor.py]"]
end

subgraph group_matching["CV and matching"]
  node_cv_service["CV retrieval service<br/>[service.py]"]
  node_cv_ingestion["CV ingestion<br/>[ingestion.py]"]
  node_embeddings["Embeddings<br/>[embeddings.py]"]
  node_hybrid_retrieval["Hybrid retrieval<br/>[retrieval.py]"]
  node_match_service["Evidence matching<br/>[service.py]"]
  node_scoring["Deterministic scoring<br/>[scoring.py]"]
end

subgraph group_tools["Shared tools and state"]
  node_registry["Tool registry<br/>[registry.py]"]
  node_tool_context["Tool context<br/>[context.py]"]
  node_saved_jobs["Saved jobs<br/>[saved_jobs.py]"]
  node_pgvector[("PostgreSQL / pgvector<br/>[postgres.py]")]
end

subgraph group_runtime["LLM and operations"]
  node_provider["LLM provider<br/>[provider.py]"]
  node_instrumentation["LLM instrumentation<br/>[instrumented.py]"]
  node_tracing["Tracing<br/>[tracing.py]"]
end

node_seeker(("Job seeker"))
node_rest_client(("REST client"))
node_mcp_client(("MCP client"))

node_seeker -->|"uses REST"| node_api
node_rest_client -->|"calls endpoints"| node_api
node_mcp_client -->|"calls tools"| node_mcp
node_api -->|"routes chat"| node_graph_agent
node_api -->|"calls tools"| node_registry
node_mcp -->|"calls tools"| node_registry
node_graph_agent -->|"builds graph"| node_graph_nodes
node_graph_nodes -->|"executes tools"| node_registry
node_manual_loop -->|"executes tools"| node_registry
node_registry -->|"dispatches search"| node_job_catalog
node_registry -->|"dispatches retrieval"| node_cv_service
node_registry -->|"dispatches matching"| node_match_service
node_registry -->|"dispatches save"| node_saved_jobs
node_job_source -.->|"provides postings"| node_job_extraction
node_cv_service -->|"ingests and chunks"| node_cv_ingestion
node_cv_service -->|"embeds text"| node_embeddings
node_cv_service -.->|"stores and searches"| node_pgvector
node_match_service -->|"retrieves evidence"| node_hybrid_retrieval
node_hybrid_retrieval -->|"searches CV"| node_cv_service
node_match_service -->|"scores requirements"| node_scoring
node_tool_context -->|"provides service"| node_cv_service
node_tool_context -->|"provides catalog"| node_job_catalog
node_saved_jobs -->|"persists jobs"| node_pgvector
node_graph_agent -.->|"uses provider"| node_instrumentation
node_manual_loop -.->|"uses provider"| node_instrumentation
node_instrumentation -->|"wraps provider"| node_provider
node_instrumentation -->|"records calls"| node_tracing

click node_api "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/api/app.py"
click node_mcp "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/mcp_server/server.py"
click node_graph_agent "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/graph/agent.py"
click node_graph_nodes "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/graph/nodes.py"
click node_manual_loop "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/agent/loop.py"
click node_job_catalog "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/tools/jobs.py"
click node_job_source "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/data_sources/ba_jobsuche.py"
click node_job_extraction "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/extraction/extractor.py"
click node_cv_service "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/rag/service.py"
click node_cv_ingestion "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/rag/ingestion.py"
click node_embeddings "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/rag/embeddings.py"
click node_hybrid_retrieval "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/matching/retrieval.py"
click node_match_service "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/matching/service.py"
click node_scoring "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/matching/scoring.py"
click node_registry "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/tools/registry.py"
click node_tool_context "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/tools/context.py"
click node_saved_jobs "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/tools/saved_jobs.py"
click node_pgvector "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/rag/postgres.py"
click node_provider "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/llm/provider.py"
click node_instrumentation "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/observability/instrumented.py"
click node_tracing "https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/observability/tracing.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,node_mcp,node_graph_agent,node_graph_nodes,node_manual_loop,node_rest_client,node_mcp_client toneBlue
class node_job_catalog,node_job_source,node_job_extraction toneAmber
class node_cv_service,node_cv_ingestion,node_embeddings,node_hybrid_retrieval,node_match_service,node_scoring toneMint
class node_registry,node_tool_context,node_saved_jobs,node_pgvector toneRose
class node_provider,node_instrumentation,node_tracing,node_seeker toneIndigo
```

## Components

### Interfaces and agents

- [FastAPI](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/api/app.py): `src/api/app.py`
- [MCP server](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/mcp_server/server.py): `src/mcp_server/server.py`
- [LangGraph agent](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/graph/agent.py): `src/graph/agent.py`
- [Graph nodes](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/graph/nodes.py): `src/graph/nodes.py`
- [Manual agent loop](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/agent/loop.py): `src/agent/loop.py`

### Job discovery

- [Job catalog](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/tools/jobs.py): `src/tools/jobs.py`
- [BA job source](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/data_sources/ba_jobsuche.py): `src/data_sources/ba_jobsuche.py`
- [Job extraction](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/extraction/extractor.py): `src/extraction/extractor.py`

### CV and matching

- [CV retrieval service](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/rag/service.py): `src/rag/service.py`
- [CV ingestion](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/rag/ingestion.py): `src/rag/ingestion.py`
- [Embeddings](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/rag/embeddings.py): `src/rag/embeddings.py`
- [Hybrid retrieval](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/matching/retrieval.py): `src/matching/retrieval.py`
- [Evidence matching](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/matching/service.py): `src/matching/service.py`
- [Deterministic scoring](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/matching/scoring.py): `src/matching/scoring.py`

### Shared tools and state

- [Tool registry](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/tools/registry.py): `src/tools/registry.py`
- [Tool context](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/tools/context.py): `src/tools/context.py`
- [Saved jobs](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/tools/saved_jobs.py): `src/tools/saved_jobs.py`
- [PostgreSQL / pgvector](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/rag/postgres.py): `src/rag/postgres.py`

### LLM and operations

- [LLM provider](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/llm/provider.py): `src/llm/provider.py`
- [LLM instrumentation](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/observability/instrumented.py): `src/observability/instrumented.py`
- [Tracing](https://github.com/pashaeimehran/agentic-ai-job-matcher/blob/main/src/observability/tracing.py): `src/observability/tracing.py`

### Other components

- **Job seeker**
- **REST client**
- **MCP client**

## Connections

- Job seeker → FastAPI: uses REST (evidence: `README.md`)
- REST client → FastAPI: calls endpoints (evidence: `README.md`)
- MCP client → MCP server: calls tools (evidence: `README.md`)
- FastAPI → LangGraph agent: routes chat (evidence: `README.md`)
- FastAPI → Tool registry: calls tools (evidence: `README.md`)
- MCP server → Tool registry: calls tools (evidence: `README.md`)
- LangGraph agent → Graph nodes: builds graph (evidence: `src/graph/agent.py`)
- Graph nodes → Tool registry: executes tools (evidence: `src/graph/nodes.py`)
- Manual agent loop → Tool registry: executes tools (evidence: `src/agent/loop.py`)
- Tool registry → Job catalog: dispatches search (evidence: `README.md`)
- Tool registry → CV retrieval service: dispatches retrieval (evidence: `README.md`)
- Tool registry → Evidence matching: dispatches matching (evidence: `README.md`)
- Tool registry → Saved jobs: dispatches save (evidence: `README.md`)
- BA job source → Job extraction: provides postings
- CV retrieval service → CV ingestion: ingests and chunks (evidence: `src/rag/service.py`)
- CV retrieval service → Embeddings: embeds text (evidence: `src/rag/service.py`)
- CV retrieval service → PostgreSQL / pgvector: stores and searches
- Evidence matching → Hybrid retrieval: retrieves evidence (evidence: `src/matching/service.py`)
- Hybrid retrieval → CV retrieval service: searches CV (evidence: `src/matching/retrieval.py`)
- Evidence matching → Deterministic scoring: scores requirements (evidence: `src/matching/service.py`)
- Tool context → CV retrieval service: provides service (evidence: `src/tools/context.py`)
- Tool context → Job catalog: provides catalog (evidence: `src/tools/context.py`)
- Saved jobs → PostgreSQL / pgvector: persists jobs (evidence: `README.md`)
- LangGraph agent → LLM instrumentation: uses provider (evidence: `README.md`)
- Manual agent loop → LLM instrumentation: uses provider (evidence: `README.md`)
- LLM instrumentation → LLM provider: wraps provider (evidence: `src/observability/instrumented.py`)
- LLM instrumentation → Tracing: records calls (evidence: `src/observability/instrumented.py`)
