# kozker-lab/kozker_recruiter_ai architecture

> Architecture diagram of the GitHub repository kozker-lab/kozker_recruiter_ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kozker-lab/kozker_recruiter_ai
- Repository: https://github.com/kozker-lab/kozker_recruiter_ai

## Overview

Kozker Recruiter AI is a recruitment-management platform: recruiters register client mandates, generate and publish jobs, source and match candidates, review applications, and track interview stages; candidates can apply and ask questions. The Next.js feature views use a shared API client, while the FastAPI backend provides the documented AI, parsing, and persistence capabilities. The README documents Supabase and Anthropic integrations. Backend implementation details are concentrated in one large file; unsampled features are represented only where the README supports them.

Main entry points: [`frontend/lib/api.ts`](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/lib/api.ts) (API client), [`backend/main.py`](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/backend/main.py) (FastAPI service), [`frontend/components/ClientsView.tsx`](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/components/ClientsView.tsx) (Clients and mandates), [`frontend/components/ReviewWorkspace.tsx`](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/components/ReviewWorkspace.tsx) (Application review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Recruiter workspace"]
  node_dashboard["Recruiter dashboard<br/>[DashboardView.tsx]"]
  node_copilot["AI copilot<br/>[ChatbotPanel.tsx]"]
end

subgraph group_hiring["Hiring lifecycle"]
  node_mandates["Clients and mandates<br/>[ClientsView.tsx]"]
  node_jobcatalog["Job catalog<br/>[JobsView.tsx]"]
  node_candidatepool["Sourcing pool<br/>[PoolView.tsx]"]
  node_matching["Candidate matching<br/>[main.py]"]
  node_review["Application review"]
  node_screening["Screening questions<br/>[QnaView.tsx]"]
  node_rounds["Interview rounds<br/>[page.tsx]"]
end

subgraph group_platform["API and services"]
  node_api["API client<br/>[api.ts]"]
  node_backend["FastAPI service<br/>[main.py]"]
  node_resume["Resume parsing<br/>[main.py]"]
  node_database[("Supabase database")]
  node_auth["Supabase authentication<br/>[client.ts]"]
  node_claude["Anthropic Claude"]
end

subgraph group_candidate["Candidate experience"]
  node_publicapply["Public job application<br/>[page.tsx]"]
  node_candidateqna["Candidate questions<br/>[page.tsx]"]
end

node_recruiter(("Recruiter"))
node_applicant(("Applicant"))

node_recruiter -->|"creates mandates"| node_mandates
node_mandates -->|"sends requests"| node_api
node_jobcatalog -->|"sends requests"| node_api
node_mandates -->|"requests job drafts"| node_backend
node_backend -->|"generates drafts"| node_claude
node_candidatepool -->|"uploads candidates"| node_api
node_candidatepool -->|"submits resumes"| node_resume
node_resume -->|"extracts entities"| node_claude
node_api -->|"sends HTTP requests"| node_backend
node_api -->|"gets session token"| node_auth
node_backend -->|"reads and writes"| node_database
node_backend -->|"scores and generates"| node_claude
node_backend -->|"runs matching"| node_matching
node_recruiter -->|"reviews and publishes"| node_jobcatalog
node_review -->|"updates applications"| node_api
node_recruiter -->|"reviews candidates"| node_review
node_review -->|"manages questions"| node_screening
node_recruiter -->|"tracks stages"| node_rounds
node_dashboard -->|"updates applications"| node_api
node_recruiter -->|"views pipeline"| node_dashboard
node_recruiter -->|"asks for guidance"| node_copilot
node_copilot -->|"sends messages"| node_api
node_applicant -->|"submits application"| node_publicapply
node_applicant -->|"asks questions"| node_candidateqna
node_candidateqna -->|"sends candidate queries"| node_screening
node_backend -->|"stores match results"| node_database

click node_mandates "https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/components/ClientsView.tsx"
click node_jobcatalog "https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/components/JobsView.tsx"
click node_candidatepool "https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/components/PoolView.tsx"
click node_matching "https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/backend/main.py"
click node_review "https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/components/ReviewWorkspace.tsx"
click node_screening "https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/components/QnaView.tsx"
click node_rounds "https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/app/(protected)/rounds/page.tsx"
click node_dashboard "https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/components/DashboardView.tsx"
click node_copilot "https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/components/ChatbotPanel.tsx"
click node_api "https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/lib/api.ts"
click node_backend "https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/backend/main.py"
click node_resume "https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/backend/main.py"
click node_auth "https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/lib/supabase/client.ts"
click node_publicapply "https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/app/apply/%5BjobId%5D/page.tsx"
click node_candidateqna "https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/app/apply/status/page.tsx"

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_dashboard,node_copilot toneBlue
class node_mandates,node_jobcatalog,node_candidatepool,node_matching,node_review,node_screening,node_rounds toneAmber
class node_api,node_backend,node_resume,node_database,node_auth,node_claude toneMint
class node_publicapply,node_candidateqna toneRose
class node_recruiter,node_applicant toneIndigo
```

## Components

### Recruiter workspace

- [Recruiter dashboard](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/components/DashboardView.tsx): `frontend/components/DashboardView.tsx`
- [AI copilot](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/components/ChatbotPanel.tsx): `frontend/components/ChatbotPanel.tsx`

### Hiring lifecycle

- [Clients and mandates](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/components/ClientsView.tsx): `frontend/components/ClientsView.tsx`
- [Job catalog](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/components/JobsView.tsx): `frontend/components/JobsView.tsx`
- [Sourcing pool](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/components/PoolView.tsx): `frontend/components/PoolView.tsx`
- [Candidate matching](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/backend/main.py): `backend/main.py`
- [Application review](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/components/ReviewWorkspace.tsx): `frontend/components/ReviewWorkspace.tsx`
- [Screening questions](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/components/QnaView.tsx): `frontend/components/QnaView.tsx`
- [Interview rounds](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/app/(protected)/rounds/page.tsx): `frontend/app/(protected)/rounds/page.tsx`

### API and services

- [API client](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [FastAPI service](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/backend/main.py): `backend/main.py`
- [Resume parsing](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/backend/main.py): `backend/main.py`
- **Supabase database**
- [Supabase authentication](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/lib/supabase/client.ts): `frontend/lib/supabase/client.ts`
- **Anthropic Claude**

### Candidate experience

- [Public job application](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/app/apply/%5BjobId%5D/page.tsx): `frontend/app/apply/[jobId]/page.tsx`
- [Candidate questions](https://github.com/kozker-lab/kozker_recruiter_ai/blob/main/frontend/app/apply/status/page.tsx): `frontend/app/apply/status/page.tsx`

### Other components

- **Recruiter**
- **Applicant**

## Connections

- Recruiter → Clients and mandates: creates mandates
- Clients and mandates → API client: sends requests (evidence: `frontend/components/ClientsView.tsx`)
- Job catalog → API client: sends requests (evidence: `frontend/components/JobsView.tsx`)
- Clients and mandates → FastAPI service: requests job drafts
- FastAPI service → Anthropic Claude: generates drafts
- Sourcing pool → API client: uploads candidates (evidence: `frontend/components/PoolView.tsx`)
- Sourcing pool → Resume parsing: submits resumes
- Resume parsing → Anthropic Claude: extracts entities
- API client → FastAPI service: sends HTTP requests
- API client → Supabase authentication: gets session token (evidence: `frontend/lib/api.ts`)
- FastAPI service → Supabase database: reads and writes
- FastAPI service → Anthropic Claude: scores and generates
- FastAPI service → Candidate matching: runs matching (evidence: `backend/main.py`)
- Recruiter → Job catalog: reviews and publishes
- Application review → API client: updates applications (evidence: `frontend/components/ReviewWorkspace.tsx`)
- Recruiter → Application review: reviews candidates
- Application review → Screening questions: manages questions
- Recruiter → Interview rounds: tracks stages
- Recruiter dashboard → API client: updates applications (evidence: `frontend/components/DashboardView.tsx`)
- Recruiter → Recruiter dashboard: views pipeline
- Recruiter → AI copilot: asks for guidance
- AI copilot → API client: sends messages
- Applicant → Public job application: submits application
- Applicant → Candidate questions: asks questions
- Candidate questions → Screening questions: sends candidate queries
- FastAPI service → Supabase database: stores match results
