ApplyGo

ApplyGo is a governed job application automation platform built from the locked OpenClaw architecture baseline.

The product brand and GitHub repository slug are now ApplyGo, while the current Python package namespace, health payload, and some runtime identifiers still use ApplyPilot / applypilot until a later technical rename pass. That deferred cleanup is tracked in issue #197.

Current status

ApplyGo has an M1 MVP-ready capstone baseline, early M2 packet preparation and review groundwork, and the M3 company identity database baseline implemented.

The reviewer-facing demo remains the M1 governed workflow: manual intake, deterministic scoring, policy review, dry-run execution evidence, and audit visibility. M2 and M3 work is present as controlled platform groundwork; it does not add production automation, live Gmail/browser execution, or real external submissions.

What This Repo Proves

This repository is best read as an engineering capstone baseline, not as a finished end-user product. The implemented system demonstrates:

• governed workflow state, not hidden automation;
• policy-before-executor discipline;
• dry-run-first execution with explicit side-effect reporting;
• database-backed auditability and migration discipline;
• a reviewer dashboard that makes the workflow legible without opening the database.

Review In 2 Minutes

If you only have a couple of minutes, focus on this:

1. Read docs/capstone/reviewer-quickstart.md.
2. Look at the dashboard evidence screenshot below.
3. Skim docs/capstone/mvp-status.md.

What you should see:

• a Sample job guided path through creation, scoring, policy, and preview;
• dry-run executor evidence with no external side effects;
• append-only audit visibility for creation, state changes, scoring, policy, and executor activity;
• explicit reviewer control rather than autonomous job submission claims.

Locked architecture principles

• Workflow owns state.
• Database owns truth.
• Policy engine owns permission.
• LLMs are limited to extraction, classification, scoring support, and drafting.
• Workers execute approved actions only through a shared executor contract.
• Dry-run is a first-class platform capability from day one.
• Semi-auto and full-auto are policy modes on the same workflow.

Implemented baseline

The implemented baseline includes the M1 platform spine:

• Canonical data model and tracker
• Application state machine
• Append-only event log
• Policy engine and automation modes
• Executor contract with execute and dry_run
• Stub executor that logs planned actions, safeguards, and side-effect status
• Minimal dashboard for tracker, workflow state, scoring, policy, dry-run, review readiness, and audit visibility

It also includes focused post-M1 groundwork:

• M2 packet preview and packet review evidence for human-controlled application preparation
• M3 first-class company identity, including canonical companies records and retained raw job source text for traceability

No Gmail, browser automation, LLM integration, or real external submission behavior is implemented yet.

M1 demo path

The current dashboard demo flow is:

manual intake -> parse/classify -> state progression -> scoring -> policy check -> dry-run executor -> review readiness -> audit timeline

Useful reviewer entry points:

• docs/capstone/reviewer-quickstart.md: fastest public reviewer entry point with screenshot-led reading path
• docs/capstone/release-pack.md: fastest recruiter/reviewer reading order
• docs/capstone/reviewer-brief.md: concise capstone/recruiter overview
• docs/capstone/codespaces-demo.md: quick Codespaces demo path for reviewers
• docs/capstone/README.md: capstone documentation index and suggested reading order
• docs/capstone/mvp-status.md: concise current implementation status and MVP boundaries
• docs/capstone/final-manual-validation-checklist.md: final human validation pass before presenting
• docs/capstone/m1-demo-script.md: short presentation script for the live M1 demo
• docs/capstone/m1-release-notes.md: M1 release marker, validation evidence, and handoff summary
• docs/capstone/dashboard-demo-flow.md: step-by-step dashboard demo runbook
• docs/capstone/m1-demo-review-checklist.md: manual pass/fix checklist for reviewing the M1 demo
• docs/architecture/current-data-model.md: implemented data model snapshot through the M3 company identity cutover
• docs/architecture/database-implementation-roadmap.md: done/next/future PostgreSQL plan and contract readiness
• docs/roadmap/m2-kickoff-plan.md: M2 direction after the M1 MVP-ready baseline
• docs/roadmap/m2-scope-and-acceptance.md: scoped M2 acceptance criteria
• docs/contracts/database-schema-contract.md: PostgreSQL table and constraint contract for the current baseline
• docs/diagrams/README.md: diagram index and diagram authority reminder
• docs/diagrams/database-schema.md: separate implemented and planned ER views
• docs/devops/codespaces.md: Codespaces and DB-backed validation workflow
• docs/architecture/locked-plan.md: architecture authority and M1 scope

The dashboard includes a Sample job prefill button so reviewers can run the demo path without manually typing the sample role.

Public Reviewer Path

For the cleanest first pass through the public repo:

1. Read docs/capstone/reviewer-quickstart.md.
2. Read docs/capstone/release-pack.md.
3. Read docs/capstone/reviewer-brief.md.
4. Read docs/capstone/mvp-status.md.
5. Use docs/capstone/codespaces-demo.md if you want the fastest runnable demo.
6. Use docs/capstone/dashboard-demo-flow.md for the detailed step-by-step workflow.

This path stays grounded in implemented behavior and avoids pulling future-looking architecture notes ahead of the current capstone baseline.

Implemented M1 architecture

flowchart LR
    Dashboard["Dashboard /ui"] --> API["FastAPI API"]
    API --> Tracker["Tracker repository"]
    Tracker --> DB[("PostgreSQL")]
    Tracker --> Events["Event log"]
    API --> State["State machine"]
    API --> Policy["Policy engine"]
    API --> Executor["Dry-run executor stub"]
    Executor --> Events
    Policy --> Events
    State --> Events

Loading

This diagram shows implemented M1 behavior only. Future Gmail, browser, LLM, authentication, and production deployment work is intentionally excluded from the current MVP.

Repository layout

• backend/: FastAPI backend, domain boundaries, and worker placeholders
• frontend/: React + TypeScript audit dashboard built with Vite and served by the backend at /ui
• docs/architecture/: implementation notes tied to the locked plan

Initial stack

• Backend: FastAPI
• Database: PostgreSQL
• Queue/cache: Redis
• Browser automation: Playwright later
• Email: Gmail API later
• Documents: docxtpl / python-docx later
• Deployment: Docker Compose first

Getting started

The root Makefile is the canonical façade for daily operations. Docker Compose owns PostgreSQL, Redis, migrations, and the packaged API/UI; local Python/Node tooling supports fast iteration and mirrors the CI quality gates. Run make help to see every target grouped by purpose and its safety behavior.

The example environment keeps dev-friendly values such as APP_DEBUG=true, while the backend package default is now debug=False unless you opt into debug mode. Cross-origin frontend access is also limited to explicit localhost or Codespaces origins instead of wildcard credentialed CORS.

First-time setup and packaged run:

make init      # idempotent: create .env (if absent), backend venv, install backend+frontend deps
make up        # build and start the packaged API/UI stack (runs migrations via its dependency)
make health    # probe /health and /ui/

Then open http://localhost:8000/ui/.

Common targets:

make help                # list all targets and safety notes (default target)
make status              # Compose service status
make logs                # tail logs (optional: make logs SERVICE=api)
make upgrade             # rebuild/recreate the running app from the working tree and apply migrations
make down                # stop containers; PostgreSQL/Redis volumes are PRESERVED
make destroy CONFIRM=1   # the ONLY command that deletes database volumes

Two-terminal local development (separate foreground processes):

make api-dev   # FastAPI in reload mode after provisioning DB/Redis and migrating
make web-dev   # Vite frontend dev server

The underlying docker compose and backend commands still work directly; the Makefile only centralizes them so contributors do not have to memorize command chains.

Validation

For DB-backed validation in Codespaces or local Docker, use docs/devops/codespaces.md.

Use the Make validation targets, which mirror the GitHub Actions gates:

make test-frontend   # frontend typecheck-aware test suite (vitest)
make test-backend    # auto-starts PostgreSQL/Redis, applies migrations, runs pytest
make test            # both suites
make check           # merge-ready CI-equivalent gate (fail-fast)

make check runs the same substantive gates as CI in the same order: frontend install/typecheck/ test/build, backend lint, migrations, the full backend test suite, and the FastAPI import smoke test. The database-backed backend targets start PostgreSQL/Redis and apply migrations automatically, leaving the services running afterward.

When PostgreSQL is available, the backend test suite also exercises database constraints, audit retention, packet review persistence, and the M3 company identity cutover regression path. The underlying commands (docker compose run --rm migrate, python -m pytest, python -m scripts.validate_seed_to_dashboard) remain available directly.

The Compose migration runner uses the same Alembic migration chain as local backend commands. For an optional demo seed and audit validation inside Compose, run:

docker compose --profile demo run --rm seed

M1 demo definition of done

• Create an application record
• Parse and classify basic job metadata
• Transition through states
• Log every event
• Evaluate policy
• Simulate an executor action in dry-run with plan details and no side effects
• Inspect it in the dashboard
• Inspect review readiness and audit evidence in the dashboard

Non-goals in v1

• Multi-account orchestration
• Captcha bypassing or anti-bot evasion
• Autonomous custom, salary, legal, or disclosure answers
• Unsupported ATS flows
• Full event sourcing
• LLM access to credentials

AI-assisted development

AI tools were used for pair programming, review, documentation drafting, and validation prompts. Final architecture decisions, scope control, testing expectations, and merge decisions were human-owned. The repository keeps implemented behavior separate from proposed future work through contracts, ADRs, CI checks, and capstone validation docs.