63b58e514d
New funders/funder_grants schema + ingest990pf monthly workflow: IRS BMF state file discovers NH private foundations (747), e-file index CSVs select their latest 990-PF filings, batch ZIPs stream through fflate (4/run cap, most-hits-first, deferred logged), grants-paid rows land in funder_grants, and funders with >=2 NH grants synthesize rolling grant rows (source irs_990pf, funder_ein linked) that flow through the existing embed+match pipeline. Scoring v2: funderPrecedentSubscore tiers repeated in-state giving (1/3/5/10 -> 8/15/20/25); easy win = >=65 total AND >=12 precedent (plan's precedent floor); scale is the full 0-100. Rolling deadlines pass the runway gate. Retrieval computes per-funder in-state counts and exposes funder_ein. Lead-quality gates from the first precedent run's failures: candidate orgs exclude NTEE T* grantmakers; self-matches gated by EIN + normalized name (NHDOJ registers foundations as charities, several without resolved EINs — the first run's top 'leads' were foundations matched to themselves). Live: ~6.5GB of IRS batches processed, 2,766 grants-paid rows, 123 synthesized foundation grants, 89 easy wins across 27 orgs, credible top-10 (AIDS Response-Seacoast -> Foundation for Seacoast Health, 25/25 precedent). 153 tests green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
HelmDocs Grant-Match Outreach Engine
Automated pipeline that matches open grants to NH nonprofits, then runs a personalized email drip whose success metric is a booked demo call. The grant match is the lead magnet — match accuracy is the prime engineering directive.
Architecture doc: docs/plan.md. Build plan and phase status: ~/.claude/plans/helmdocs-outreach.md.
Relationship to novelpad-desktop
This repo deliberately mirrors the novelpad-desktop stack so a future merge is a directory move, not a rewrite:
- Yarn 4.5.0 + Turbo monorepo, Node 22.16 (volta), TypeScript ^5.9.3
- Postgres + pgvector + Drizzle (0.44.6, pinned via
resolutions), actions/queries pattern - DBOS for durable jobs/cron (worker-app pattern)
@google/genaion Vertex; embeddingsgemini-embedding-001@ 1536 dims (identical to HelmDocs RAG — never mix embedding models)- React Router v7 for the review UI
Merge rules: all packages stay in the @novelpad/ scope with names that never collide with novelpad-desktop workspaces (outreach-*). Files copied from novelpad-desktop carry a provenance header (source path @ commit) — diff against origin at merge time. No live code sharing; drift is fixed at merge, by design.
Boundary: separate repo and separate Postgres on purpose — outreach tooling and sourced contact data stay outside the compliance-scoped product repo/DB.
Workspaces
| Workspace | Purpose |
|---|---|
packages/config |
Shared tsconfig/tailwind base (copied from novelpad-desktop) |
packages/outreach-core |
Drizzle schema (grants, orgs, profiles, contacts, matches, pipeline_events), actions/queries, hard gates |
packages/outreach-ai |
Gemini client, embeddings, org-profiler + mission-fit-judge agents |
apps/outreach-worker |
DBOS executor: ingestion crons, expiry sweep, scoring runs, Apollo sync |
apps/outreach-review |
Human review queue (RR7). No auth by design — run behind IAP/localhost |
Development
yarn install
yarn build
yarn typecheck
yarn test
Migrations: yarn create:migration <name> inside packages/outreach-core (server-only — no client DB in this repo).
Local infrastructure
docker-compose.yml mirrors novelpad-desktop's compose conventions (pgvector image, healthcheck-gated startup), trimmed to this repo: Postgres 16 + pgvector on host port 54341 (novelpad's stacks use 54321/54331 — all three run side by side), plus worker and review services built from the root multi-stage Dockerfile (same image, different command — the novelpad website/auth pattern).
docker compose up -d postgres # just the database
DATABASE_URL=postgresql://postgres:password@localhost:54341/helmdocs_outreach \
yarn workspace @novelpad/outreach-core migrate
docker compose up -d # full stack (worker + review UI on :3100)
Migrations always run from the host — drizzle-kit is a devDependency and deliberately absent from the production image. The DBOS system schema initializes itself into the same database on worker boot (the dbos schema; ignore the misleading *_dbos_sys URL in DBOS's boot log — the shared pool override wins).