# 849879772/recruitops-agent architecture

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

- Interactive diagram: https://gitdiagram.com/849879772/recruitops-agent
- Repository: https://github.com/849879772/recruitops-agent

## Overview

RecruitOps is a local-first campus-recruiting workbench, presented mainly as a Windows desktop app with a FastAPI/Web UI. The central workflow configures a candidate profile, discovers company openings, crawls and filters jobs, completes missing descriptions, scores matches, and supports user-controlled applications and progress tracking. Separate branches handle recruiting email, schedules, assistant tools, and automation. The README documents the workflow and capabilities; sampled source confirms selected API, browser-bridge, mail-storage, MCP, and filler behavior, so uncertain internal wiring is omitted.

Main entry points: [`apps/api/main.py`](https://github.com/849879772/recruitops-agent/blob/main/apps/api/main.py) (FastAPI application), [`packages/pipeline/daily.py`](https://github.com/849879772/recruitops-agent/blob/main/packages/pipeline/daily.py) (Daily job pipeline), [`packages/recruitment_mail/run_service.py`](https://github.com/849879772/recruitops-agent/blob/main/packages/recruitment_mail/run_service.py) (Recruiting mail), [`packages/mcp/server.py`](https://github.com/849879772/recruitops-agent/blob/main/packages/mcp/server.py) (Assistant tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Desktop and API"]
  node_desktop["Desktop workbench<br/>[main.ts]"]
  node_web["Web workbench<br/>[app.js]"]
  node_api["FastAPI application<br/>[main.py]"]
end

subgraph group_jobs["Job discovery and matching"]
  node_profile["Profile parsing<br/>[loader.py]"]
  node_company_sources["Company sources"]
  node_discovery["Source discovery"]
  node_crawler["Job crawling<br/>[runner.py]"]
  node_pipeline["Daily job pipeline<br/>[daily.py]"]
  node_matching["Job matching<br/>[service.py]"]
  node_job_store[("Recruitment database<br/>[postgres.py]")]
end

subgraph group_applications["Applications and browser"]
  node_browser["Embedded browser<br/>[browser-service.ts]"]
  node_filler["Resume autofill<br/>[index.cjs]"]
  node_application_review["Progress review"]
  node_browser_bridge["Browser bridge<br/>[server.py]"]
end

subgraph group_communications["Mail and schedule"]
  node_mail["Recruiting mail<br/>[run_service.py]"]
  node_mail_store[("Mail records<br/>[storage.py]")]
  node_schedule["Schedule and tasks<br/>[job_browse.py]"]
end

subgraph group_assistant["Assistant and automation"]
  node_assistant["Assistant tools<br/>[server.py]"]
  node_codex["Assistant runtime<br/>[client.py]"]
  node_automation["Automation worker<br/>[worker.py]"]
end

node_candidate(("Candidate"))
node_model{{"Model API"}}
node_recruitment_sites{{"Recruitment sites"}}
node_imap{{"IMAP mailbox"}}

node_candidate -->|"uses"| node_desktop
node_candidate -->|"uses"| node_web
node_desktop -->|"requests"| node_api
node_web -->|"requests"| node_api
node_api -->|"loads profile"| node_profile
node_profile -.->|"analyzes resume"| node_model
node_api -->|"starts tasks"| node_pipeline
node_pipeline -->|"refreshes sources"| node_discovery
node_discovery -->|"updates registry"| node_company_sources
node_pipeline -->|"runs crawl"| node_crawler
node_crawler -->|"fetches listings"| node_recruitment_sites
node_pipeline -->|"scores jobs"| node_matching
node_matching -.->|"analyzes match"| node_model
node_pipeline -->|"saves results"| node_job_store
node_api -->|"reads and writes"| node_job_store
node_desktop -->|"opens sites"| node_browser
node_browser -->|"navigates"| node_recruitment_sites
node_desktop -->|"fills fields"| node_filler
node_api -->|"requests review"| node_application_review
node_application_review -->|"observes pages"| node_browser_bridge
node_browser_bridge -->|"records evidence"| node_job_store
node_api -->|"syncs and processes"| node_mail
node_mail -->|"reads messages"| node_imap
node_mail -.->|"interprets messages"| node_model
node_mail -->|"persists records"| node_mail_store
node_api -->|"manages schedule"| node_schedule
node_api -->|"serves assistant"| node_codex
node_codex -->|"invokes tools"| node_assistant
node_assistant -->|"runs recruitment"| node_pipeline
node_assistant -->|"handles mail"| node_mail
node_assistant -->|"reviews progress"| node_application_review
node_assistant -->|"manages tasks"| node_schedule
node_automation -->|"runs scheduled"| node_pipeline
node_automation -->|"processes scheduled"| node_mail
node_automation -->|"reviews scheduled"| node_application_review

click node_desktop "https://github.com/849879772/recruitops-agent/blob/main/apps/desktop/src/main.ts"
click node_web "https://github.com/849879772/recruitops-agent/blob/main/apps/web/app.js"
click node_api "https://github.com/849879772/recruitops-agent/blob/main/apps/api/main.py"
click node_profile "https://github.com/849879772/recruitops-agent/blob/main/packages/candidate_profile/loader.py"
click node_company_sources "https://github.com/849879772/recruitops-agent/blob/main/packages/discovery/company_registry.py"
click node_discovery "https://github.com/849879772/recruitops-agent/blob/main/packages/discovery/offerbiu_refresh.py"
click node_crawler "https://github.com/849879772/recruitops-agent/blob/main/packages/recruitment_core/runner.py"
click node_pipeline "https://github.com/849879772/recruitops-agent/blob/main/packages/pipeline/daily.py"
click node_matching "https://github.com/849879772/recruitops-agent/blob/main/packages/matching/service.py"
click node_job_store "https://github.com/849879772/recruitops-agent/blob/main/packages/repositories/postgres.py"
click node_browser "https://github.com/849879772/recruitops-agent/blob/main/apps/desktop/src/browser-service.ts"
click node_filler "https://github.com/849879772/recruitops-agent/blob/main/packages/desktop_filler/index.cjs"
click node_application_review "https://github.com/849879772/recruitops-agent/blob/main/packages/tools/application_review_run.py"
click node_browser_bridge "https://github.com/849879772/recruitops-agent/blob/main/packages/browser_bridge/server.py"
click node_mail "https://github.com/849879772/recruitops-agent/blob/main/packages/recruitment_mail/run_service.py"
click node_mail_store "https://github.com/849879772/recruitops-agent/blob/main/packages/recruitment_mail/storage.py"
click node_schedule "https://github.com/849879772/recruitops-agent/blob/main/packages/repositories/job_browse.py"
click node_assistant "https://github.com/849879772/recruitops-agent/blob/main/packages/mcp/server.py"
click node_codex "https://github.com/849879772/recruitops-agent/blob/main/packages/codex_runtime/client.py"
click node_automation "https://github.com/849879772/recruitops-agent/blob/main/packages/automation/worker.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_desktop,node_web,node_api toneBlue
class node_profile,node_company_sources,node_discovery,node_crawler,node_pipeline,node_matching,node_job_store toneAmber
class node_browser,node_filler,node_application_review,node_browser_bridge,node_model toneMint
class node_mail,node_mail_store,node_schedule toneRose
class node_assistant,node_codex,node_automation,node_candidate,node_recruitment_sites,node_imap toneIndigo
```

## Components

### Desktop and API

- [Desktop workbench](https://github.com/849879772/recruitops-agent/blob/main/apps/desktop/src/main.ts): `apps/desktop/src/main.ts`
- [Web workbench](https://github.com/849879772/recruitops-agent/blob/main/apps/web/app.js): `apps/web/app.js`
- [FastAPI application](https://github.com/849879772/recruitops-agent/blob/main/apps/api/main.py): `apps/api/main.py`

### Job discovery and matching

- [Profile parsing](https://github.com/849879772/recruitops-agent/blob/main/packages/candidate_profile/loader.py): `packages/candidate_profile/loader.py`
- [Company sources](https://github.com/849879772/recruitops-agent/blob/main/packages/discovery/company_registry.py): `packages/discovery/company_registry.py`
- [Source discovery](https://github.com/849879772/recruitops-agent/blob/main/packages/discovery/offerbiu_refresh.py): `packages/discovery/offerbiu_refresh.py`
- [Job crawling](https://github.com/849879772/recruitops-agent/blob/main/packages/recruitment_core/runner.py): `packages/recruitment_core/runner.py`
- [Daily job pipeline](https://github.com/849879772/recruitops-agent/blob/main/packages/pipeline/daily.py): `packages/pipeline/daily.py`
- [Job matching](https://github.com/849879772/recruitops-agent/blob/main/packages/matching/service.py): `packages/matching/service.py`
- [Recruitment database](https://github.com/849879772/recruitops-agent/blob/main/packages/repositories/postgres.py): `packages/repositories/postgres.py`

### Applications and browser

- [Embedded browser](https://github.com/849879772/recruitops-agent/blob/main/apps/desktop/src/browser-service.ts): `apps/desktop/src/browser-service.ts`
- [Resume autofill](https://github.com/849879772/recruitops-agent/blob/main/packages/desktop_filler/index.cjs): `packages/desktop_filler/index.cjs`
- [Progress review](https://github.com/849879772/recruitops-agent/blob/main/packages/tools/application_review_run.py): `packages/tools/application_review_run.py`
- [Browser bridge](https://github.com/849879772/recruitops-agent/blob/main/packages/browser_bridge/server.py): `packages/browser_bridge/server.py`

### Mail and schedule

- [Recruiting mail](https://github.com/849879772/recruitops-agent/blob/main/packages/recruitment_mail/run_service.py): `packages/recruitment_mail/run_service.py`
- [Mail records](https://github.com/849879772/recruitops-agent/blob/main/packages/recruitment_mail/storage.py): `packages/recruitment_mail/storage.py`
- [Schedule and tasks](https://github.com/849879772/recruitops-agent/blob/main/packages/repositories/job_browse.py): `packages/repositories/job_browse.py`

### Assistant and automation

- [Assistant tools](https://github.com/849879772/recruitops-agent/blob/main/packages/mcp/server.py): `packages/mcp/server.py`
- [Assistant runtime](https://github.com/849879772/recruitops-agent/blob/main/packages/codex_runtime/client.py): `packages/codex_runtime/client.py`
- [Automation worker](https://github.com/849879772/recruitops-agent/blob/main/packages/automation/worker.py): `packages/automation/worker.py`

### Other components

- **Candidate**
- **Model API**
- **Recruitment sites**
- **IMAP mailbox**

## Connections

- Candidate → Desktop workbench: uses
- Candidate → Web workbench: uses
- Desktop workbench → FastAPI application: requests
- Web workbench → FastAPI application: requests
- FastAPI application → Profile parsing: loads profile
- Profile parsing → Model API: analyzes resume
- FastAPI application → Daily job pipeline: starts tasks
- Daily job pipeline → Source discovery: refreshes sources
- Source discovery → Company sources: updates registry
- Daily job pipeline → Job crawling: runs crawl
- Job crawling → Recruitment sites: fetches listings
- Daily job pipeline → Job matching: scores jobs
- Job matching → Model API: analyzes match
- Daily job pipeline → Recruitment database: saves results
- FastAPI application → Recruitment database: reads and writes
- Desktop workbench → Embedded browser: opens sites
- Embedded browser → Recruitment sites: navigates
- Desktop workbench → Resume autofill: fills fields
- FastAPI application → Progress review: requests review
- Progress review → Browser bridge: observes pages
- Browser bridge → Recruitment database: records evidence
- FastAPI application → Recruiting mail: syncs and processes
- Recruiting mail → IMAP mailbox: reads messages
- Recruiting mail → Model API: interprets messages
- Recruiting mail → Mail records: persists records
- FastAPI application → Schedule and tasks: manages schedule
- FastAPI application → Assistant runtime: serves assistant
- Assistant runtime → Assistant tools: invokes tools
- Assistant tools → Daily job pipeline: runs recruitment
- Assistant tools → Recruiting mail: handles mail
- Assistant tools → Progress review: reviews progress
- Assistant tools → Schedule and tasks: manages tasks
- Automation worker → Daily job pipeline: runs scheduled
- Automation worker → Recruiting mail: processes scheduled
- Automation worker → Progress review: reviews scheduled