# xmrtdao/jobby-mcjobberson architecture

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

- Interactive diagram: https://gitdiagram.com/xmrtdao/jobby-mcjobberson
- Repository: https://github.com/xmrtdao/jobby-mcjobberson

## Overview

Jobby’s documented active workflow is recipient preparation: normalize and validate explicit contact details, deduplicate, apply suppression rules, and audit malformed records; it does not send messages. A separate local resume-portal workflow parses uploaded files into source-derived data and can render a resume. The repository also contains broader orchestration, routing, research, delivery, ATS, and persistence modules, but the README describes those tracks as planned or out of scope; their presence here does not establish an active end-to-end service. Edges reflect excerpted calls or README statements, not inferred wiring.

Main entry points: [`orchestrator.py`](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/orchestrator.py) (Pipeline orchestrator), [`resume_server.py`](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/resume_server.py) (Local portal server), [`docs/app.js`](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/docs/app.js) (Resume portal UI), [`routing.py`](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/routing.py) (Opportunity routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_recipient["Recipient preparation"]
  node_newsletter["Newsletter extraction"]
  node_recipient_rules["Recipient rules<br/>[lead_utils.py]"]
end

subgraph group_resume["Resume portal"]
  node_resume_ui["Resume portal UI<br/>[app.js]"]
  node_resume_server["Local portal server<br/>[resume_server.py]"]
  node_resume_parser["Resume parser<br/>[resume_ingest.py]"]
  node_resume_renderer["Resume renderer<br/>[resume_render.py]"]
end

subgraph group_pipeline["Opportunity modules"]
  node_orchestrator["Pipeline orchestrator<br/>[orchestrator.py]"]
  node_researcher["Lead research<br/>[researcher.py]"]
  node_routing["Opportunity routing<br/>[routing.py]"]
  node_personalizer["Outreach preparation<br/>[personalizer.py]"]
  node_profile["Client profile<br/>[profile.py]"]
end

subgraph group_integrations["Adapters and state"]
  node_state_manager["Lead state<br/>[state_manager.py]"]
  node_lead_store[("PostgREST lead store")]
  node_delivery["Delivery adapter"]
  node_ats["ATS adapter<br/>[ats_adapter.py]"]
end

node_user(("Job seeker"))
node_fleet_services["Fleet services"]

node_user -->|"uploads resume"| node_resume_ui
node_resume_ui -->|"submits parse"| node_resume_server
node_resume_server -->|"parses file"| node_resume_parser
node_resume_server -->|"renders document"| node_resume_renderer
node_newsletter -->|"uses recipient helpers"| node_recipient_rules
node_orchestrator -->|"researches leads"| node_researcher
node_orchestrator -->|"routes leads"| node_routing
node_orchestrator -->|"prepares outreach"| node_personalizer
node_orchestrator -->|"persists leads"| node_state_manager
node_state_manager -->|"reads and writes"| node_lead_store
node_orchestrator -->|"dispatches batch"| node_delivery
node_orchestrator -->|"prepares applications"| node_ats
node_routing -->|"loads targets"| node_profile
node_personalizer -->|"uses profile"| node_profile
node_delivery -.->|"delivery boundary"| node_fleet_services
node_ats -.->|"canonical page-agent boundary"| node_fleet_services

click node_newsletter "https://github.com/xmrtdao/jobby-mcjobberson/blob/master/newsletter_ingest.py"
click node_recipient_rules "https://github.com/xmrtdao/jobby-mcjobberson/blob/master/lead_utils.py"
click node_resume_ui "https://github.com/xmrtdao/jobby-mcjobberson/blob/master/docs/app.js"
click node_resume_server "https://github.com/xmrtdao/jobby-mcjobberson/blob/master/resume_server.py"
click node_resume_parser "https://github.com/xmrtdao/jobby-mcjobberson/blob/master/resume_ingest.py"
click node_resume_renderer "https://github.com/xmrtdao/jobby-mcjobberson/blob/master/resume_render.py"
click node_orchestrator "https://github.com/xmrtdao/jobby-mcjobberson/blob/master/orchestrator.py"
click node_researcher "https://github.com/xmrtdao/jobby-mcjobberson/blob/master/researcher.py"
click node_routing "https://github.com/xmrtdao/jobby-mcjobberson/blob/master/routing.py"
click node_personalizer "https://github.com/xmrtdao/jobby-mcjobberson/blob/master/personalizer.py"
click node_profile "https://github.com/xmrtdao/jobby-mcjobberson/blob/master/profile.py"
click node_state_manager "https://github.com/xmrtdao/jobby-mcjobberson/blob/master/state_manager.py"
click node_delivery "https://github.com/xmrtdao/jobby-mcjobberson/blob/master/delivery_adapter.py"
click node_ats "https://github.com/xmrtdao/jobby-mcjobberson/blob/master/ats_adapter.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_newsletter,node_recipient_rules toneBlue
class node_resume_ui,node_resume_server,node_resume_parser,node_resume_renderer toneAmber
class node_orchestrator,node_researcher,node_routing,node_personalizer,node_profile toneMint
class node_state_manager,node_lead_store,node_delivery,node_ats toneRose
class node_user,node_fleet_services toneIndigo
```

## Components

### Recipient preparation

- [Newsletter extraction](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/newsletter_ingest.py): `newsletter_ingest.py`
- [Recipient rules](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/lead_utils.py): `lead_utils.py`

### Resume portal

- [Resume portal UI](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/docs/app.js): `docs/app.js`
- [Local portal server](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/resume_server.py): `resume_server.py`
- [Resume parser](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/resume_ingest.py): `resume_ingest.py`
- [Resume renderer](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/resume_render.py): `resume_render.py`

### Opportunity modules

- [Pipeline orchestrator](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/orchestrator.py): `orchestrator.py`
- [Lead research](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/researcher.py): `researcher.py`
- [Opportunity routing](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/routing.py): `routing.py`
- [Outreach preparation](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/personalizer.py): `personalizer.py`
- [Client profile](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/profile.py): `profile.py`

### Adapters and state

- [Lead state](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/state_manager.py): `state_manager.py`
- **PostgREST lead store**
- [Delivery adapter](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/delivery_adapter.py): `delivery_adapter.py`
- [ATS adapter](https://github.com/xmrtdao/jobby-mcjobberson/blob/master/ats_adapter.py): `ats_adapter.py`

### Other components

- **Job seeker**
- **Fleet services**

## Connections

- Job seeker → Resume portal UI: uploads resume (evidence: `README.md`)
- Resume portal UI → Local portal server: submits parse (evidence: `README.md`)
- Local portal server → Resume parser: parses file (evidence: `resume_server.py`)
- Local portal server → Resume renderer: renders document (evidence: `resume_server.py`)
- Newsletter extraction → Recipient rules: uses recipient helpers (evidence: `newsletter_ingest.py`)
- Pipeline orchestrator → Lead research: researches leads (evidence: `orchestrator.py`)
- Pipeline orchestrator → Opportunity routing: routes leads (evidence: `orchestrator.py`)
- Pipeline orchestrator → Outreach preparation: prepares outreach (evidence: `orchestrator.py`)
- Pipeline orchestrator → Lead state: persists leads (evidence: `orchestrator.py`)
- Lead state → PostgREST lead store: reads and writes (evidence: `state_manager.py`)
- Pipeline orchestrator → Delivery adapter: dispatches batch (evidence: `orchestrator.py`)
- Pipeline orchestrator → ATS adapter: prepares applications (evidence: `orchestrator.py`)
- Opportunity routing → Client profile: loads targets (evidence: `routing.py`)
- Outreach preparation → Client profile: uses profile (evidence: `personalizer.py`)
- Delivery adapter → Fleet services: delivery boundary (evidence: `README.md`)
- ATS adapter → Fleet services: canonical page-agent boundary (evidence: `README.md`)
