Architecture

Mon, 01 Jan 0001 00:00:00 +0000

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

Mon, 01 Jan 0001 00:00:00 +0000

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

Concepts on Raven