# bkocii/ai-candidate-matcher architecture

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

- Interactive diagram: https://gitdiagram.com/bkocii/ai-candidate-matcher
- Repository: https://github.com/bkocii/ai-candidate-matcher

## Overview

AI Candidate Matcher is a tenant-scoped recruiting application for rediscovering candidates against confirmed vacancies. Recruiters create and confirm vacancy requirements, evaluate the organization’s candidate pool, review a deterministic shortlist and optional evidence-based AI assessments, record human decisions, and separately draft outreach after approval. The graph also preserves candidate intake/profile extraction, organization and access controls, asynchronous AI work, and audit/retention capabilities. Relationships use README workflow statements and indexed source references; unsampled areas are shown only where documented, so some internal calls are omitted.

Main entry points: [`candidates/models.py`](https://github.com/bkocii/ai-candidate-matcher/blob/main/candidates/models.py) (Candidate profiles and documents), [`matching/services.py`](https://github.com/bkocii/ai-candidate-matcher/blob/main/matching/services.py) (Rules and scoring), [`matching/ai_assessment.py`](https://github.com/bkocii/ai-candidate-matcher/blob/main/matching/ai_assessment.py) (AI assessment), [`matching/models.py`](https://github.com/bkocii/ai-candidate-matcher/blob/main/matching/models.py) (Shortlists and assessments)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tenant["Workspace and access"]
  node_workspace[("Organizations and memberships<br/>[models.py]")]
  node_authorization["Tenant authorization<br/>[permissions.py]"]
  node_accounts[("User accounts<br/>[models.py]")]
end

subgraph group_vacancy["Vacancy setup"]
  node_vacancy_records[("Vacancies and requirements<br/>[models.py]")]
  node_vacancy_workflow["Vacancy workflow<br/>[services.py]"]
end

subgraph group_candidate["Candidate records"]
  node_candidate_records[("Candidate profiles and documents<br/>[models.py]")]
  node_candidate_intake["Candidate intake<br/>[services.py]"]
  node_document_processing["CV document processing<br/>[documents.py]"]
  node_profile_extraction["Profile extraction<br/>[ai_extraction.py]"]
  node_profile_review["Profile confirmation<br/>[profile_review.py]"]
end

subgraph group_matching["Matching and review"]
  node_matching_logic["Rules and scoring<br/>[services.py]"]
  node_shortlists[("Shortlists and assessments<br/>[models.py]")]
  node_assessment["AI assessment<br/>[ai_assessment.py]"]
  node_freshness["Input freshness<br/>[staleness.py]"]
  node_review_decisions["Recruiter review and decisions<br/>[review.py]"]
  node_outreach["Outreach drafts<br/>[workflow.py]"]
end

subgraph group_platform["AI and operations"]
  node_ai_gateway["AI gateway<br/>[toolkit.py]"]
  node_usage_audit[("Usage and audit ledger<br/>[models.py]")]
  node_audit_services["Audit services<br/>[services.py]"]
  node_background_jobs["Background AI jobs<br/>[services.py]"]
  node_operations_records[("Job records<br/>[models.py]")]
  node_lifecycle["Retention and lifecycle<br/>[lifecycle.py]"]
  node_evaluation["Evaluation workflows<br/>[services.py]"]
end

node_recruiter(("Recruiter"))

node_recruiter -->|"selects workspace"| node_workspace
node_recruiter -->|"creates vacancy"| node_vacancy_workflow
node_vacancy_workflow -->|"creates versions"| node_vacancy_records
node_vacancy_workflow -->|"syncs requirements"| node_matching_logic
node_recruiter -->|"imports candidates"| node_candidate_intake
node_candidate_intake -->|"creates records"| node_candidate_records
node_recruiter -->|"uploads CVs"| node_document_processing
node_document_processing -->|"stores documents"| node_candidate_records
node_profile_extraction -->|"creates profile draft"| node_candidate_records
node_profile_extraction -->|"requests extraction"| node_ai_gateway
node_profile_extraction -->|"records usage"| node_audit_services
node_audit_services -->|"writes usage"| node_usage_audit
node_recruiter -->|"confirms profile"| node_profile_review
node_profile_review -->|"publishes facts"| node_candidate_records
node_recruiter -->|"evaluates pool"| node_matching_logic
node_matching_logic -->|"reads requirements"| node_vacancy_records
node_matching_logic -->|"reads candidate facts"| node_candidate_records
node_matching_logic -->|"saves ranking"| node_shortlists
node_freshness -->|"checks inputs"| node_shortlists
node_recruiter -->|"requests assessment"| node_assessment
node_assessment -->|"requests assessment"| node_ai_gateway
node_assessment -->|"saves version"| node_shortlists
node_assessment -->|"records usage"| node_audit_services
node_recruiter -->|"reviews evidence"| node_review_decisions
node_review_decisions -->|"records decision"| node_shortlists
node_recruiter -->|"requests approved draft"| node_outreach
node_outreach -->|"requires approval"| node_shortlists
node_background_jobs -->|"processes tasks"| node_assessment
node_background_jobs -->|"processes tasks"| node_profile_extraction
node_background_jobs -->|"claims tasks"| node_operations_records
node_recruiter -->|"manages retention"| node_lifecycle
node_lifecycle -->|"records lifecycle"| node_usage_audit
node_evaluation -->|"uses candidate data"| node_candidate_records
node_evaluation -->|"uses vacancy data"| node_vacancy_records
node_workspace -->|"defines membership scope"| node_authorization
node_recruiter -.->|"uses account"| node_accounts

click node_workspace "https://github.com/bkocii/ai-candidate-matcher/blob/main/organizations/models.py"
click node_authorization "https://github.com/bkocii/ai-candidate-matcher/blob/main/organizations/permissions.py"
click node_accounts "https://github.com/bkocii/ai-candidate-matcher/blob/main/accounts/models.py"
click node_vacancy_records "https://github.com/bkocii/ai-candidate-matcher/blob/main/vacancies/models.py"
click node_vacancy_workflow "https://github.com/bkocii/ai-candidate-matcher/blob/main/vacancies/services.py"
click node_candidate_records "https://github.com/bkocii/ai-candidate-matcher/blob/main/candidates/models.py"
click node_candidate_intake "https://github.com/bkocii/ai-candidate-matcher/blob/main/candidates/services.py"
click node_document_processing "https://github.com/bkocii/ai-candidate-matcher/blob/main/candidates/documents.py"
click node_profile_extraction "https://github.com/bkocii/ai-candidate-matcher/blob/main/candidates/ai_extraction.py"
click node_profile_review "https://github.com/bkocii/ai-candidate-matcher/blob/main/candidates/profile_review.py"
click node_matching_logic "https://github.com/bkocii/ai-candidate-matcher/blob/main/matching/services.py"
click node_shortlists "https://github.com/bkocii/ai-candidate-matcher/blob/main/matching/models.py"
click node_assessment "https://github.com/bkocii/ai-candidate-matcher/blob/main/matching/ai_assessment.py"
click node_freshness "https://github.com/bkocii/ai-candidate-matcher/blob/main/matching/staleness.py"
click node_review_decisions "https://github.com/bkocii/ai-candidate-matcher/blob/main/matching/review.py"
click node_outreach "https://github.com/bkocii/ai-candidate-matcher/blob/main/outreach/workflow.py"
click node_ai_gateway "https://github.com/bkocii/ai-candidate-matcher/blob/main/ai_gateway/toolkit.py"
click node_usage_audit "https://github.com/bkocii/ai-candidate-matcher/blob/main/audit/models.py"
click node_audit_services "https://github.com/bkocii/ai-candidate-matcher/blob/main/audit/services.py"
click node_background_jobs "https://github.com/bkocii/ai-candidate-matcher/blob/main/operations/services.py"
click node_operations_records "https://github.com/bkocii/ai-candidate-matcher/blob/main/operations/models.py"
click node_lifecycle "https://github.com/bkocii/ai-candidate-matcher/blob/main/audit/lifecycle.py"
click node_evaluation "https://github.com/bkocii/ai-candidate-matcher/blob/main/evaluation/services.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_workspace,node_authorization,node_accounts toneBlue
class node_vacancy_records,node_vacancy_workflow toneAmber
class node_candidate_records,node_candidate_intake,node_document_processing,node_profile_extraction,node_profile_review toneMint
class node_matching_logic,node_shortlists,node_assessment,node_freshness,node_review_decisions,node_outreach toneRose
class node_ai_gateway,node_usage_audit,node_audit_services,node_background_jobs,node_operations_records,node_lifecycle,node_evaluation,node_recruiter toneIndigo
```

## Components

### Workspace and access

- [Organizations and memberships](https://github.com/bkocii/ai-candidate-matcher/blob/main/organizations/models.py): `organizations/models.py`
- [Tenant authorization](https://github.com/bkocii/ai-candidate-matcher/blob/main/organizations/permissions.py): `organizations/permissions.py`
- [User accounts](https://github.com/bkocii/ai-candidate-matcher/blob/main/accounts/models.py): `accounts/models.py`

### Vacancy setup

- [Vacancies and requirements](https://github.com/bkocii/ai-candidate-matcher/blob/main/vacancies/models.py): `vacancies/models.py`
- [Vacancy workflow](https://github.com/bkocii/ai-candidate-matcher/blob/main/vacancies/services.py): `vacancies/services.py`

### Candidate records

- [Candidate profiles and documents](https://github.com/bkocii/ai-candidate-matcher/blob/main/candidates/models.py): `candidates/models.py`
- [Candidate intake](https://github.com/bkocii/ai-candidate-matcher/blob/main/candidates/services.py): `candidates/services.py`
- [CV document processing](https://github.com/bkocii/ai-candidate-matcher/blob/main/candidates/documents.py): `candidates/documents.py`
- [Profile extraction](https://github.com/bkocii/ai-candidate-matcher/blob/main/candidates/ai_extraction.py): `candidates/ai_extraction.py`
- [Profile confirmation](https://github.com/bkocii/ai-candidate-matcher/blob/main/candidates/profile_review.py): `candidates/profile_review.py`

### Matching and review

- [Rules and scoring](https://github.com/bkocii/ai-candidate-matcher/blob/main/matching/services.py): `matching/services.py`
- [Shortlists and assessments](https://github.com/bkocii/ai-candidate-matcher/blob/main/matching/models.py): `matching/models.py`
- [AI assessment](https://github.com/bkocii/ai-candidate-matcher/blob/main/matching/ai_assessment.py): `matching/ai_assessment.py`
- [Input freshness](https://github.com/bkocii/ai-candidate-matcher/blob/main/matching/staleness.py): `matching/staleness.py`
- [Recruiter review and decisions](https://github.com/bkocii/ai-candidate-matcher/blob/main/matching/review.py): `matching/review.py`
- [Outreach drafts](https://github.com/bkocii/ai-candidate-matcher/blob/main/outreach/workflow.py): `outreach/workflow.py`

### AI and operations

- [AI gateway](https://github.com/bkocii/ai-candidate-matcher/blob/main/ai_gateway/toolkit.py): `ai_gateway/toolkit.py`
- [Usage and audit ledger](https://github.com/bkocii/ai-candidate-matcher/blob/main/audit/models.py): `audit/models.py`
- [Audit services](https://github.com/bkocii/ai-candidate-matcher/blob/main/audit/services.py): `audit/services.py`
- [Background AI jobs](https://github.com/bkocii/ai-candidate-matcher/blob/main/operations/services.py): `operations/services.py`
- [Job records](https://github.com/bkocii/ai-candidate-matcher/blob/main/operations/models.py): `operations/models.py`
- [Retention and lifecycle](https://github.com/bkocii/ai-candidate-matcher/blob/main/audit/lifecycle.py): `audit/lifecycle.py`
- [Evaluation workflows](https://github.com/bkocii/ai-candidate-matcher/blob/main/evaluation/services.py): `evaluation/services.py`

### Other components

- **Recruiter**

## Connections

- Recruiter → Organizations and memberships: selects workspace
- Recruiter → Vacancy workflow: creates vacancy
- Vacancy workflow → Vacancies and requirements: creates versions (evidence: `vacancies/services.py`)
- Vacancy workflow → Rules and scoring: syncs requirements (evidence: `vacancies/services.py`)
- Recruiter → Candidate intake: imports candidates
- Candidate intake → Candidate profiles and documents: creates records (evidence: `candidates/services.py`)
- Recruiter → CV document processing: uploads CVs
- CV document processing → Candidate profiles and documents: stores documents (evidence: `candidates/documents.py`)
- Profile extraction → Candidate profiles and documents: creates profile draft (evidence: `candidates/ai_extraction.py`)
- Profile extraction → AI gateway: requests extraction (evidence: `candidates/ai_extraction.py`)
- Profile extraction → Audit services: records usage (evidence: `candidates/ai_extraction.py`)
- Audit services → Usage and audit ledger: writes usage (evidence: `audit/services.py`)
- Recruiter → Profile confirmation: confirms profile
- Profile confirmation → Candidate profiles and documents: publishes facts (evidence: `candidates/profile_review.py`)
- Recruiter → Rules and scoring: evaluates pool
- Rules and scoring → Vacancies and requirements: reads requirements (evidence: `matching/services.py`)
- Rules and scoring → Candidate profiles and documents: reads candidate facts (evidence: `matching/services.py`)
- Rules and scoring → Shortlists and assessments: saves ranking (evidence: `matching/services.py`)
- Input freshness → Shortlists and assessments: checks inputs (evidence: `matching/staleness.py`)
- Recruiter → AI assessment: requests assessment
- AI assessment → AI gateway: requests assessment (evidence: `matching/ai_assessment.py`)
- AI assessment → Shortlists and assessments: saves version (evidence: `matching/ai_assessment.py`)
- AI assessment → Audit services: records usage (evidence: `matching/ai_assessment.py`)
- Recruiter → Recruiter review and decisions: reviews evidence
- Recruiter review and decisions → Shortlists and assessments: records decision (evidence: `matching/review.py`)
- Recruiter → Outreach drafts: requests approved draft
- Outreach drafts → Shortlists and assessments: requires approval
- Background AI jobs → AI assessment: processes tasks (evidence: `operations/services.py`)
- Background AI jobs → Profile extraction: processes tasks (evidence: `operations/services.py`)
- Background AI jobs → Job records: claims tasks (evidence: `operations/services.py`)
- Recruiter → Retention and lifecycle: manages retention
- Retention and lifecycle → Usage and audit ledger: records lifecycle (evidence: `audit/models.py`)
- Evaluation workflows → Candidate profiles and documents: uses candidate data (evidence: `evaluation/services.py`)
- Evaluation workflows → Vacancies and requirements: uses vacancy data (evidence: `evaluation/services.py`)
- Organizations and memberships → Tenant authorization: defines membership scope (evidence: `organizations/permissions.py`)
- Recruiter → User accounts: uses account