求职工作流自动化助手

Deploy — Fly.io (hosted)

If you're not comfortable with the command line, start at docs/getting-started/start-here-fly.md — a step-by-step walkthrough with screenshots at every UI decision point and inline troubleshooting branches, paced for first-timers.

If you've deployed to a PaaS before and just want the dense version: full runbook at docs/getting-started/install-fly.md. What it'll cost per month, all-in: docs/getting-started/cost.md.

In short:

```bash

1. (macOS only) Install Homebrew if you don't have it — see https://brew.sh

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install flyctl

brew install flyctl # macOS curl -L https://fly.io/install.sh | sh # Linux

6. Deploy (creates the app + 8GB volume, prompts for API keys, runs `fly deploy`)

bash ops/fly-deploy.sh ```

The script provisions the Fly app + 8 GB volume, stages your API keys as Fly secrets, runs fly deploy, and verifies the basic-auth gate post-deploy. On success it prints your URL: https://findajob-<your-handle>.fly.dev/.

Deploy — Docker Compose (self-host)

For operators running their own Linux server. Pick any directory:

• /opt/stacks/findajob-<you>/ is the conventional system-path layout
• Anywhere under your home directory works fine for personal use

```bash

./.env — top-level: image tag, port, timezone (read by Docker Compose)

Both must exist before `docker compose up -d` or Compose will refuse to start.

curl -fsSL -o compose.yaml https://raw.githubusercontent.com/brockamer/findajob/main/ops/compose.yaml.example curl -fsSL -o .env https://raw.githubusercontent.com/brockamer/findajob/main/ops/stack.env.example curl -fsSL -o state/data/.env https://raw.githubusercontent.com/brockamer/findajob/main/data/.env.example chmod 600 state/data/.env

(For internet-exposed deployments: also set FINDAJOB_AUTH_USER + FINDAJOB_AUTH_PASS

Quick start

There are two ways to run findajob — pick based on whether you want to operate a Linux server:

• Hosted on Fly.io (recommended for most people) — runs on Fly's infrastructure under your account. ~$5/month for the always-on machine + 8 GB volume; you don't operate a server. Setup is fly auth login + a deploy script that prompts for your API keys, then ~60 minutes inside the app to complete the onboarding interview.
• Self-hosted with Docker Compose (for operators) — runs as ghcr.io/brockamer/findajob (linux/amd64 + linux/arm64) on a server you operate. Zero hosting cost beyond what you already pay for the box. You handle backups, reverse proxy, TLS, and updates.

Both paths run the same image, complete the same onboarding interview, and reach the same dashboard. Full cost breakdown across paths and LLM cadences: docs/getting-started/cost.md.

Two .env files exist:

./state/data/.env — runtime: API keys, ntfy topic, optional basic-auth credentials

Edit ./.env: set FINDAJOB_TZ to your timezone and FINDAJOB_MATERIALS_PORT to a free host port.

Leave ./state/data/.env at the placeholder values — first-run onboarding overwrites them.

in ./state/data/.env to gate the UI behind HTTP Basic Auth.)

docker compose up -d ```

If you placed the stack in /opt/stacks/, prefix mkdir with sudo and follow with sudo chown -R $(id -u):$(id -g) <stack-dir>/. Skip both for paths under your home directory.

Full walkthrough → docs/getting-started/install-docker.md

How the prep pipeline works

The "one click → folder full of tailored materials" in step 3 is seven sequential LLM stages, each consuming the previous stages' output as explicit context:

   company_researcher  ─►  briefing_writer  ─►  fit_analyst
   (web research)          (writing)             (web research)
                                                      │
                                          fit spliced INTO briefing
                                          BEFORE Overall Recommendation
                                                      ▼
                                          merged briefing.md
                                                      │
                                                      ▼
                                          resume_tailor
                                          (writing)
                                                      │
                              ┌───────────────────────┴────────────────┐
                              ▼                                        ▼
                  resume_change_reviewer                    cover_letter_writer
                  (cheap diff vs master,                    (writing — consumes
                   no premium tokens                         briefing + tailored
                   spent on cheap work)                      resume)
                                                                       │
                                                                       ▼
                                                             recruiter_critic
                                                             (writing — sees ONLY
                                                              JD + resume + cover;
                                                              simulates a reader who
                                                              hasn't researched the
                                                              candidate)

   sidecar:  find_contacts  ─►  outreach_drafter (writing)
             reads LinkedIn connections.csv, drafts personalized notes

Three architectural choices make the outputs feel like they were written by someone who actually researched the company:

• Explicit context chaining, not RAG. Each stage's output is structured markdown that becomes literal input to the next stage. No vector embeddings, no similarity-retrieval guesses, no "the model couldn't find the relevant chunk." When prep produces a bad cover letter, you can read the briefing it was given and see why.
• An asymmetric DAG, not a uniform pipeline. recruiter_critic deliberately doesn't see the briefing or fit analysis — its job is to simulate a recruiter who hasn't researched the candidate, so giving it that context would defeat the purpose. The other writing stages share a cached_prefix (profile + master resume + JD) so the provider can cache and discount the repeated input across the run.
• Per-role model judgment, not one model for everything. A high-quality model where voice matters (briefing, resume, cover, critique, outreach). A web-grounded model where web grounding matters (company_researcher, fit_analyst). A cheap fast model for the diff review (resume_change_reviewer). A volume-tuned model for the high-frequency scorer that runs 100–500× a day. Specific model picks: docs/architecture.md.

Inline retry gates on Stages 2 and 3 catch malformed model output (missing ## Overall Recommendation, empty fit analysis from the web-grounded model's intermittent content=null) before it propagates downstream.

Full DAG + per-stage I/O contracts + failure handling: docs/architecture.md.

---