fe12b032af
docker-compose.yml: pgvector/pgvector:pg16 on host 54341 (side-by-side
with novelpad's 54321/54331), healthcheck-gated worker + review services
from one multi-stage Dockerfile (same image, different command — the
website/auth pattern). No Electric/Redis: nothing client-synced here.
Dockerfile adapted from novelpad-desktop @ 62c56b87, trimmed: no native
modules so no build-tools layer, no pm2. Default CMD = DBOS worker.
Verified end to end: migration applied against the container (vector
0.8.2, 6 tables, 2 HNSW indexes), containerized worker boots, DBOS
system schema lands in helmdocs_outreach ('dbos' schema — the
*_dbos_sys URL in DBOS's boot log is cosmetic; the shared pool wins).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
54 lines
3.2 KiB
Markdown
54 lines
3.2 KiB
Markdown
# 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](https://gitea.stephenmann.io/NovelPad/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/genai` on Vertex; embeddings `gemini-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).
|