# kakuibeyond/talent-eval-agents architecture

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

- Interactive diagram: https://gitdiagram.com/kakuibeyond/talent-eval-agents
- Repository: https://github.com/kakuibeyond/talent-eval-agents

## Overview

This is a multi-agent talent evaluation and recommendation system, with a document evidence library and evidence-search workbench as its current user-facing workflow. Users manage employee profiles and knowledge-base documents; uploaded files are stored, parsed, chunked and indexed, then retrieved under tenant and permission filters. Natural-language talent searches compile into controlled candidate filters and evidence retrieval. The README also describes evidence packs, citation display and talent-decision workflows. Some graph links are limited to README statements or source-index references because not all implementation excerpts were provided.

Main entry points: [`backend/app/api.py`](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/api.py) (FastAPI Routes), [`backend/app/services.py`](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/services.py) (Upload and Parse), [`backend/app/worker.py`](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/worker.py) (Background Worker), [`backend/app/talent_decision_engine.py`](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/talent_decision_engine.py) (Decision Orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_frontend["Application UI<br/>[main.tsx]"]
  node_evidence_panel["Evidence Panel"]
  node_api["FastAPI Routes<br/>[api.py]"]
end

subgraph group_documents["Document Evidence"]
  node_domain_models[("Talent and Document Records<br/>[models.py]")]
  node_document_services["Upload and Parse<br/>[services.py]"]
  node_parsers["Document Parsers"]
  node_mineru["MinerU Parser<br/>[mineru_client.py]"]
  node_pipeline["Document Pipeline"]
  node_worker["Background Worker<br/>[worker.py]"]
  node_chunking["Chunk Creation<br/>[chunk_service.py]"]
  node_postgres[("PostgreSQL<br/>[database.py]")]
  node_object_store[("File Object Store<br/>[object_store.py]")]
end

subgraph group_retrieval["Search and Evidence"]
  node_index_service["Evidence Indexing"]
  node_model_provider["Model Provider<br/>[model_provider.py]"]
  node_milvus[("Milvus Evidence Index<br/>[milvus_store.py]")]
  node_search["Hybrid Evidence Search"]
  node_query_plan["Query Planning<br/>[query_plan.py]"]
  node_evidence_pack["Evidence Pack<br/>[evidence_pack.py]"]
  node_citations["Citation Resolution"]
end

subgraph group_decision["Talent Decisions"]
  node_decision_engine["Decision Orchestrator"]
  node_request_graph["Talent Request Graph"]
  node_evaluation_runtime["Evaluation Runtime"]
  node_evaluation_dispatch["Evaluation Dispatch"]
  node_evaluation_report["Evaluation Report"]
end

node_user(("Talent User"))

node_user -->|"uses"| node_frontend
node_frontend -.->|"requests"| node_api
node_frontend -->|"renders"| node_evidence_panel
node_api -->|"reads and writes"| node_domain_models
node_api -->|"uploads and parses"| node_document_services
node_document_services -->|"stores files"| node_object_store
node_document_services -->|"parses documents"| node_parsers
node_document_services -->|"fallback parses"| node_mineru
node_worker -->|"consumes jobs"| node_pipeline
node_pipeline -->|"creates chunks"| node_chunking
node_worker -->|"runs parsing"| node_document_services
node_worker -->|"runs indexing"| node_index_service
node_chunking -->|"reads parse output"| node_object_store
node_document_services -.->|"persists records"| node_postgres
node_index_service -->|"embeds chunks"| node_model_provider
node_index_service -->|"writes vectors"| node_milvus
node_api -->|"plans searches"| node_query_plan
node_api -->|"runs retrieval"| node_search
node_search -->|"hybrid searches"| node_milvus
node_api -->|"builds evidence"| node_evidence_pack
node_api -->|"resolves citations"| node_citations
node_decision_engine -->|"dispatches request"| node_request_graph
node_decision_engine -->|"dispatches evaluation"| node_evaluation_runtime
node_decision_engine -->|"dispatches report"| node_evaluation_report
node_evaluation_runtime -.->|"uses dispatch"| node_evaluation_dispatch

click node_frontend "https://github.com/kakuibeyond/talent-eval-agents/blob/main/frontend/src/main.tsx"
click node_evidence_panel "https://github.com/kakuibeyond/talent-eval-agents/blob/main/frontend/src/EvidencePackPanel.tsx"
click node_api "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/api.py"
click node_domain_models "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/models.py"
click node_document_services "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/services.py"
click node_parsers "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/document_parsers.py"
click node_mineru "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/mineru_client.py"
click node_pipeline "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/document_pipeline.py"
click node_worker "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/worker.py"
click node_chunking "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/chunk_service.py"
click node_postgres "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/database.py"
click node_object_store "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/object_store.py"
click node_index_service "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/evidence_index_service.py"
click node_model_provider "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/model_provider.py"
click node_milvus "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/milvus_store.py"
click node_search "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/hybrid_search_service.py"
click node_query_plan "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/query_plan.py"
click node_evidence_pack "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/evidence_pack.py"
click node_citations "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/evidence_citations.py"
click node_decision_engine "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/talent_decision_engine.py"
click node_request_graph "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/talent_request_graph.py"
click node_evaluation_runtime "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/talent_evaluation_runtime.py"
click node_evaluation_dispatch "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/talent_evaluation_dispatch.py"
click node_evaluation_report "https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/talent_evaluation_report.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_frontend,node_evidence_panel,node_api,node_user toneBlue
class node_domain_models,node_document_services,node_parsers,node_mineru,node_pipeline,node_worker,node_chunking,node_postgres,node_object_store toneAmber
class node_index_service,node_model_provider,node_milvus,node_search,node_query_plan,node_evidence_pack,node_citations toneMint
class node_decision_engine,node_request_graph,node_evaluation_runtime,node_evaluation_dispatch,node_evaluation_report toneRose
```

## Components

### User Experience

- [Application UI](https://github.com/kakuibeyond/talent-eval-agents/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Evidence Panel](https://github.com/kakuibeyond/talent-eval-agents/blob/main/frontend/src/EvidencePackPanel.tsx): `frontend/src/EvidencePackPanel.tsx`
- [FastAPI Routes](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/api.py): `backend/app/api.py`

### Document Evidence

- [Talent and Document Records](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/models.py): `backend/app/models.py`
- [Upload and Parse](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/services.py): `backend/app/services.py`
- [Document Parsers](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/document_parsers.py): `backend/app/document_parsers.py`
- [MinerU Parser](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/mineru_client.py): `backend/app/mineru_client.py`
- [Document Pipeline](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/document_pipeline.py): `backend/app/document_pipeline.py`
- [Background Worker](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/worker.py): `backend/app/worker.py`
- [Chunk Creation](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/chunk_service.py): `backend/app/chunk_service.py`
- [PostgreSQL](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/database.py): `backend/app/database.py`
- [File Object Store](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/object_store.py): `backend/app/object_store.py`

### Search and Evidence

- [Evidence Indexing](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/evidence_index_service.py): `backend/app/evidence_index_service.py`
- [Model Provider](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/model_provider.py): `backend/app/model_provider.py`
- [Milvus Evidence Index](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/milvus_store.py): `backend/app/milvus_store.py`
- [Hybrid Evidence Search](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/hybrid_search_service.py): `backend/app/hybrid_search_service.py`
- [Query Planning](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/query_plan.py): `backend/app/query_plan.py`
- [Evidence Pack](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/evidence_pack.py): `backend/app/evidence_pack.py`
- [Citation Resolution](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/evidence_citations.py): `backend/app/evidence_citations.py`

### Talent Decisions

- [Decision Orchestrator](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/talent_decision_engine.py): `backend/app/talent_decision_engine.py`
- [Talent Request Graph](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/talent_request_graph.py): `backend/app/talent_request_graph.py`
- [Evaluation Runtime](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/talent_evaluation_runtime.py): `backend/app/talent_evaluation_runtime.py`
- [Evaluation Dispatch](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/talent_evaluation_dispatch.py): `backend/app/talent_evaluation_dispatch.py`
- [Evaluation Report](https://github.com/kakuibeyond/talent-eval-agents/blob/main/backend/app/talent_evaluation_report.py): `backend/app/talent_evaluation_report.py`

### Other components

- **Talent User**

## Connections

- Talent User → Application UI: uses (evidence: `README.md`)
- Application UI → FastAPI Routes: requests
- Application UI → Evidence Panel: renders (evidence: `frontend/src/main.tsx`)
- FastAPI Routes → Talent and Document Records: reads and writes (evidence: `backend/app/api.py`)
- FastAPI Routes → Upload and Parse: uploads and parses (evidence: `backend/app/api.py`)
- Upload and Parse → File Object Store: stores files (evidence: `backend/app/services.py`)
- Upload and Parse → Document Parsers: parses documents (evidence: `backend/app/services.py`)
- Upload and Parse → MinerU Parser: fallback parses (evidence: `backend/app/services.py`)
- Background Worker → Document Pipeline: consumes jobs (evidence: `backend/app/worker.py`)
- Document Pipeline → Chunk Creation: creates chunks (evidence: `backend/app/document_pipeline.py`)
- Background Worker → Upload and Parse: runs parsing (evidence: `backend/app/worker.py`)
- Background Worker → Evidence Indexing: runs indexing (evidence: `backend/app/worker.py`)
- Chunk Creation → File Object Store: reads parse output (evidence: `backend/app/chunk_service.py`)
- Upload and Parse → PostgreSQL: persists records
- Evidence Indexing → Model Provider: embeds chunks (evidence: `backend/app/evidence_index_service.py`)
- Evidence Indexing → Milvus Evidence Index: writes vectors (evidence: `backend/app/evidence_index_service.py`)
- FastAPI Routes → Query Planning: plans searches (evidence: `backend/app/api.py`)
- FastAPI Routes → Hybrid Evidence Search: runs retrieval (evidence: `backend/app/api.py`)
- Hybrid Evidence Search → Milvus Evidence Index: hybrid searches (evidence: `backend/app/hybrid_search_service.py`)
- FastAPI Routes → Evidence Pack: builds evidence (evidence: `backend/app/api.py`)
- FastAPI Routes → Citation Resolution: resolves citations (evidence: `backend/app/api.py`)
- Decision Orchestrator → Talent Request Graph: dispatches request (evidence: `backend/app/talent_decision_engine.py`)
- Decision Orchestrator → Evaluation Runtime: dispatches evaluation (evidence: `backend/app/talent_decision_engine.py`)
- Decision Orchestrator → Evaluation Report: dispatches report (evidence: `backend/app/talent_decision_engine.py`)
- Evaluation Runtime → Evaluation Dispatch: uses dispatch (evidence: `backend/app/talent_evaluation_runtime.py`)