Concepts #

Understand how Raven is structured and how the Discover → Draft → Send pipeline fits together before diving into individual commands.

Pages in this section #

Architecture

Architecture #

Raven is a bash CLI (bin/raven) that dispatches to shell scripts (scripts/*.sh), which invoke a Node.js discovery engine (jobs/).

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  bin/raven  │────▶│ scripts/*.sh │────▶│  jobs/*.mjs     │
│  (CLI)      │     │  (_lib.sh)   │     │  (ESM engine)   │
└─────────────┘     └──────────────┘     └─────────────────┘
                           │                      │
                           ▼                      ▼
                    config/*.yml            data/jobs.json
                    .env                    data/jobs.db
                    files/resume.md         drafts/

Layers #

CLI layer (`bin/raven`, `scripts/`) #

Resolves repo root (works with npm link)
Loads .env
Ensures dependencies installed
Forwards to Node scripts or bash helpers

Discovery engine (`jobs/`) #

Module	Role
`discover.mjs`	Orchestrates parallel tier scans
`scan-ats-full.mjs`	Reverse ATS walk (12 platforms)
`scan.mjs`	Board feeds + portal scanner
`sync-openjobdata.mjs`	HuggingFace → SQLite index
`query-index.mjs`	Search local index
`draft-outreach.mjs`	Application draft CLI
`lib/draft-engine.mjs`	Profile + resume + form guides
`plugins/gemini-draft.mjs`	Optional Gemini email polish

Providers (`jobs/providers/`) #

One module per ATS or board feed. Each exports { id, fetch, detect? } and uses shared HTTP helpers.

Pipeline

Discover → Draft → Send #

Raven’s workflow is three stages. Each stage produces artifacts the next stage consumes.

Stage 1: Discover #

raven discover

Input: config/portals.yml filters (+ optional CLI flags)

Output: data/jobs.json (auto-saved)

Sources (parallel):

Tier	Flag	Description
ATS	`--sources ats`	Live APIs: Greenhouse, Lever, Ashby, Workday, …
Boards	`--sources boards`	RemoteOK, Remotive, Arbeitnow, Landing.jobs
Index	`--sources index`	Local SQLite from openjobdata
hiring.cafe	`--sources hiringcafe`	Opt-in; may need `HIRING_CAFE_ENABLED=1`

Stage 2: Draft #

raven draft --max 25

Input: data/jobs.json + config/profile.yml + parsed resume

The pipeline at a glance #

config/profile.yml + files/resume.md
         │
         ▼
   raven discover  ──►  data/jobs.json
         │
         ▼
   raven draft     ──►  drafts/outreach-*.csv + .md
         │
         ▼
   raven send      ──►  Gmail / Outlook (email rows only)

Stage	Input	Output
Discover	Search filters, ATS APIs, board feeds	Matching jobs saved to JSON
Draft	Jobs + your profile + resume	Tailored CSV, Markdown review, form guides
Send	CSV with `contact_email`	Delivered emails (optional)

Design principles #

Local-first — jobs, drafts, logs, and config stay on your machine
Profile as source of truth — one YAML file drives all drafting
Resume-aware — bullets are matched per job, not generic templates
Form vs email — ATS applications get step-by-step guides, not blind sends

Start with Architecture →