Note on the license: this project is MIT licensed. Copyright is held by Rudrendu Paul and Sourav Nandy. See License below for full terms.
Install the CLI
pip install freelancer-payment-protection-cli
That installs fpp, a typed command-line client for the FastAPI backend below (invoices, escalations, client risk scoring, --json on every data command). It talks to a freelancer-payment-protection API instance you run yourself. See Run the full stack locally to stand one up, or point FPP_API_URL at one that's already running.
Table of Contents
What This Is
FreshBooks and HoneyBook stop at "invoice sent." Neither drafts what to say when a client goes quiet, and neither scores a client's risk of non-payment before you start the work. This project is a FastAPI + Next.js app, backed by Claude, that does two specific things well: it drafts a stage-appropriate escalation email or a jurisdiction-referenced demand letter for an overdue invoice, and it scores a client's payment risk from 0–100 with a full factor breakdown, both with an AI-generated confidence/reasoning trail a human reviews before anything goes out.
It is not a set-and-forget automation system. There's no background scheduler enforcing wait times between stages and no live sync with FreshBooks/QuickBooks/Wave today. See What's Not Implemented Yet for the honest gap between the architecture diagram and what's wired up. What's real: the AI drafting, the risk scoring, the evidence locker, and a CLI that scripts all three.
Features
| Capability | What's actually implemented |
|---|
| AI escalation drafting | Five ordered stages (polite_reminder → firm_notice → final_warning → legal_demand → legal_action). POST /api/v1/escalations/{id}/draft asks Claude for the next stage's subject/body/tone/confidence score. It's a preview: the endpoint doesn't send the email or persist the stage change (apps/api/app/services/escalation_service.py). |
| Jurisdiction-referenced demand letters | Claude drafts a letter for a jurisdiction string you supply. Four jurisdictions (California, New York, England & Wales, Ontario) have a dedicated template file under legal-templates/; any other jurisdiction still gets a draft, formatted from the model's general knowledge rather than a hard-coded template. Every letter carries a fixed AI-disclaimer paragraph. Streams to the UI over SSE via a threading.Thread → queue.Queue → asyncio.run_in_executor bridge (apps/api/app/services/ai_service.py), verified real and not just a UI-only typewriter effect. |
| Client risk scoring | POST /api/v1/risk/score returns a 0–100 score, a level (low/medium/high/critical), and a factors array. The prompt asks Claude to weigh 7 named factors (industry payment culture, payment-terms length, historical delay, contract quality, invoice size, geography, outstanding-balance ratio) and return its reasoning. If the Claude call fails, risk_service.py falls back to a deterministic heuristic score rather than erroring. Rate-limited to 30 requests/minute. |
| Evidence locker | Manual upload of PDF/PNG/JPEG/.eml/plain-text files (25MB cap), listed and deletable per invoice, backed by Supabase Storage in production. There's no drag-and-drop auto-capture and no ZIP export endpoint today. Uploads happen one file at a time via POST /api/v1/evidence/{invoice_id}/upload. |
CLI (fpp) | Every data-returning command supports --json. Persistent login against Supabase's own password-grant endpoint, cached to ~/.config/freelancer-payment-protection-cli/credentials.json (mode 600), transparent refresh. Published on PyPI and npm as freelancer-payment-protection-cli. |
| Security controls | Row Level Security on every Postgres table (packages/db/migrations/versions/002_rls_policies.sql), Supabase JWT auth with no local bypass, slowapi rate limiting (10/min on the AI-drafting routes, 30/min on risk scoring, 100/min global), CodeQL on every PR, pip-audit + pnpm audit dependency scanning, and TruffleHog secret scanning in CI. |
Run the full stack locally
Verified against a fresh clone. Prerequisites: Node.js 20+, pnpm 9.x, Python 3.12.x (3.13/3.14 aren't supported by this checkout: 3.14 fails at pip install for one of the pinned backend dependencies).
WARNING
Requires Python 3.12.x specifically. 3.13 and 3.14 are not yet supported.
git clone https://github.com/RudrenduPaul/freelancer-payment-protection.git
cd freelancer-payment-protection
pnpm install
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env.local
pip install -r apps/api/requirements.txt
python -m alembic -c packages/db/migrations/alembic.ini upgrade head
python scripts/seed_dev.py
pnpm dev
The seed script needs no external services and produces 8 clients, 16 invoices, and pre-generated escalation events, all queryable through the API or the CLI once seeded. Verified end to end in a fresh venv: alembic upgrade head runs clean, seed_dev.py populates SQLite, and uvicorn app.main:app boots and serves /health and /health/ready once the two .env fixes above are applied.
| Service | URL |
|---|
| Dashboard | http://localhost:3000 |
| API + OpenAPI docs | http://localhost:8000/docs |
Logging into the web dashboard needs a real (free tier is fine) Supabase project. apps/api/app/middleware/auth.py validates a Supabase-issued JWT with no local bypass. The seeded data is fully reachable through the API/CLI without one. AI features (demand letters, risk scoring, escalation drafts) need a real ANTHROPIC_API_KEY in apps/api/.env; without one, risk scoring falls back to the heuristic score and the other two AI routes return a 503.
Command-Line Interface
Verified against the installed package's actual --help output.
fpp login Log in (prompts for email/password)
fpp logout Delete cached credentials
fpp whoami [--json] Show cached workspace/session info
fpp invoice list [--status] [--client-id] [--page] [--page-size] [--json]
fpp invoice create --client-id --invoice-number --amount --due-date [--currency] [--source-system] [--external-id] [--json]
fpp invoice show <invoice-id> [--json]
fpp invoice set-status <invoice-id> <status> [--json]
fpp escalation list [--json] Active escalations, grouped by stage
fpp escalation status <invoice-id> [--json] Current stage + full history
fpp escalation advance <invoice-id> [--json] Preview the next stage's AI-drafted email (does not send or persist)
fpp client list [--risk-level] [--search] [--page] [--page-size] [--json]
fpp client show <client-id> [--json]
fpp client risk <client-id> [--json] Compute/refresh the AI risk score
fpp login
fpp invoice list --status overdue --json | jq '.[] | {id, invoiceNumber, daysPastDue}'
fpp client risk <client-id> --json | jq '.level'
--status on invoice list accepts disputed, overdue, paid, pending, written_off. Full flag reference for any command: fpp <command> --help. Full install, config, and auth walkthrough: packages/cli/README.md.
API Reference
Interactive OpenAPI at http://localhost:8000/docs. Verified against the router source directly:
GET /health Liveness probe
GET /health/ready Readiness (DB)
GET /api/v1/clients List
POST /api/v1/clients Create
GET /api/v1/clients/{client_id} Detail
PUT /api/v1/clients/{client_id} Update
DELETE /api/v1/clients/{client_id} Delete
GET /api/v1/invoices List
POST /api/v1/invoices Create (manual)
GET /api/v1/invoices/{invoice_id} Detail
PATCH /api/v1/invoices/{invoice_id}/status Update status
GET /api/v1/escalations Active escalations
POST /api/v1/escalations/{invoice_id}/draft AI-draft next escalation email (preview only)
GET /api/v1/escalations/{invoice_id}/history Full history
POST /api/v1/legal/demand-letter Generate demand letter
POST /api/v1/legal/demand-letter/stream Generate + stream (SSE)
GET /api/v1/evidence/{invoice_id} Evidence items
POST /api/v1/evidence/{invoice_id}/upload Manual upload
DELETE /api/v1/evidence/{item_id} Remove
POST /api/v1/risk/score AI risk score, structured JSON
GET /api/v1/analytics/overview Dashboard totals
Comparison
Every non-freelancer-payment-protection row below is sourced from each vendor's own docs/help center, checked in August 2026.
| Capability | Spreadsheets | FreshBooks | HoneyBook | HubSpot | freelancer-payment-protection |
|---|
| Overdue-payment reminders | ✗ | Automatic, up to 3 per invoice, configurable timing, template-based | Automatic, 4 fixed timings (7 days before, due day, 2 days after, recurring), template-based | Automated "Payment Reminder" workflow (rule-based) | AI-drafted per stage, tone-calibrated, confidence-scored (preview only, not auto-sent) |
| Jurisdiction-referenced legal demand letters | ✗ | ✗ (not documented) | ✗ (not documented) | ✗ (not documented) | AI-drafted; 4 jurisdictions have a dedicated template (CA, NY, UK, Ontario) |
| Client/invoice risk scoring | ✗ | ✗ (not documented) | ✗ (not documented) | Breeze Invoice Prioritization, an AI ranking of overdue invoices by risk/age/customer value, Revenue Hub public beta as of June 2026; no published 0–100 score or per-factor reasoning | 0–100 score, 7 named factors, full AI reasoning returned per client, heuristic fallback if AI is down |
| Evidence/document storage per invoice | ✗ | ✗ (not documented) | ✗ (not documented) | ✗ (not documented) | Manual upload, Supabase Storage-backed, no ZIP export yet |
| Streaming AI generation in the UI | ✗ | ✗ | ✗ | ✗ | Real SSE streaming (verified in source, not just a UI animation) |
| Native invoicing | ✗ | Yes (core product) | Yes (core product) | Yes (Commerce/Payments) | No. Invoices are created via API/CLI, not synced from an accounting tool today |
| Background job automation (sync, scheduled escalation) | N/A | Native | Native | Native | Not implemented. See What's Not Implemented Yet |
The honest read: FreshBooks and HoneyBook are stronger at the mechanical, rule-based reminder they already do well. HubSpot's June 2026 Breeze beta is the closest thing to a competing risk-scoring feature on this list and is worth watching. Nobody here drafts a jurisdiction-referenced demand letter or streams AI generation into the UI; that's the actual gap this project fills, not "full collection automation," which none of these, including this project, deliver end to end yet.
Architecture
System diagram (what's actually implemented)
graph TB
subgraph "Frontend: Next.js 14"
A[App Router Pages]
B[TanStack Query Cache]
C[Framer Motion UI]
D[Supabase Auth Client]
end
subgraph "Backend: FastAPI, Python 3.12"
E[FastAPI App Factory]
F[JWT Middleware]
G[slowapi Rate Limiter]
H["Routers: 8 domains"]
I[Services: business logic only]
end
subgraph "AI: Claude Sonnet 4.6"
J[packages/legal_ai/client.py]
K[Demand Letter: streaming SSE]
L[Escalation Email: structured draft]
M[Risk Scorer: JSON output]
end
subgraph "Data Layer"
T[(Supabase PostgreSQL + RLS)]
U[Supabase Storage]
W[(SQLite Dev DB)]
end
A --> E
D --> T
B --> E
E --> F --> G --> H --> I
I --> J
J --> K
J --> L
J --> M
I --> T & U
Celery and Redis are declared dependencies (requirements.txt) with no worker code in the repository today: no apps/workers/ directory exists, and there is no scheduled job that advances an invoice's stage automatically. See What's Not Implemented Yet.
Why Python for the backend, not Node
Legal document drafting uses python-docx/WeasyPrint in the code paths that are wired up for it, and the Anthropic Python SDK is the reference implementation. The Python ecosystem is also where contract-analysis tooling (NLTK, spaCy) would live for a future dispute-analysis feature.
Why centralize all Claude calls in one file
packages/legal_ai/client.py (called from apps/api/app/services/ai_service.py) is the only place the Anthropic SDK is imported. Model version, retries, and the sync-SDK/async-FastAPI bridge live there, so upgrading the model is a one-file change.
Why Pydantic Settings with fail-fast validation
settings = Settings() runs at import time. If ANTHROPIC_API_KEY is absent, the app raises before serving a request rather than degrading silently. The tradeoff: the settings model is strict about unrecognized fields too, which is the root cause of one of the two .env.example issues in the FAQ below.
Every data-returning command also takes --json for structured output an agent or script can parse directly:
MCP Server
freelancer-payment-protection-cli ships a Model Context Protocol (MCP) server, so an
agent (Claude Desktop, Claude Code, or any other MCP client) can call the same commands
above (invoice list, client risk, escalation status, ...) as tool calls instead of
shelling out to the CLI directly.
Install:
pip install "freelancer-payment-protection-cli[mcp]"
Claude Desktop config (claude_desktop_config.json):
{
"mcpServers": {
"freelancer-payment-protection": {
"command": "fpp-mcp"
}
}
}
The server exposes one tool, run, that shells out to the installed fpp binary with
the given argument list and returns its output as structured JSON when possible — every
fpp subcommand is reachable through it, not just a hand-picked subset. Example call:
run(args=["client", "risk", "<client-id>", "--json"]) returns the same 0-100 risk
score, factor breakdown, and AI reasoning that fpp client risk <client-id> --json
prints to a terminal.
Security
| Control | Implementation |
|---|
| Authentication | Supabase JWT validated on every protected route, no local bypass |
| Authorization | Row Level Security on every table, with workspace isolation enforced at the database, not the app layer |
| Secrets | Pydantic SecretStr; app fails to start if a required var is missing |
| Input validation | Pydantic v2 on every endpoint |
| Rate limiting | 100 req/min global default; 10/min on the AI-drafting routes; 30/min on risk scoring |
| SQL injection | SQLAlchemy ORM only, no raw SQL in the routers/services reviewed |
| Evidence access | Uploaded files validated by MIME type and size (25MB cap) before storage |
| Dependency audit | pip-audit (backend) + pnpm audit (frontend), both run in CI |
| Secret scanning | TruffleHog on every push/PR |
| SAST | CodeQL (Python + TypeScript) on every PR |
What's Not Implemented Yet
Being direct about this because the architecture diagrams and dependency list overstate it otherwise:
- No background worker or scheduler.
celery and redis are pinned in requirements.txt, but no apps/workers/ code exists in the repository. Nothing advances an invoice's escalation stage automatically or on a timer.
- No minimum-wait-time enforcement.
escalation_service.py's get_next_stage() is a plain ordered lookup with no date/timedelta check anywhere in the call path. Any authenticated caller can request a draft for the next stage regardless of how long the invoice has been overdue; the endpoint also never writes the new stage back to the invoice.
- No FreshBooks/QuickBooks/Wave sync.
packages/integrations/__init__.py is an empty file. Invoices are created through the API/CLI, not synced from an accounting tool.
- No production PDF/DOCX export yet.
doc_gen_service.py's docstring says it plainly: dev builds save the drafted letter as a .txt file; the python-docx/WeasyPrint production path is not wired up.
- No evidence ZIP export. The evidence router supports list/upload/delete only.
None of this is secret. It's what running the code shows. The parts that are real (AI drafting, risk scoring with reasoning, streaming, the CLI) are described above with specifics, not adjectives.
FAQ
What is this, and what's the actual differentiator versus FreshBooks or HoneyBook?
Both of those handle sending an invoice and reminding a client on a fixed schedule. Neither drafts a jurisdiction-referenced legal demand letter or scores a client's payment risk with an AI-generated reasoning trail. This project does both, backed by a real Claude API call you can see in packages/legal_ai/ and apps/api/app/services/, not a canned template swap.
Is this open source? Can I fork it or use the code in my own project?
Yes. The repository is MIT licensed: fork it, modify it, or embed the code in your own project, subject only to the standard MIT terms in LICENSE (keep the copyright/permission notice). The freelancer-payment-protection-cli package on PyPI/npm is installable and runnable as-is under the same license.
What platforms does the CLI support?
Python 3.10–3.13 on Linux, macOS, or Windows, installed via pip, uvx, or pipx. The npm package (freelancer-payment-protection-cli on npm) is a thin wrapper that shells out to uvx or pipx at runtime rather than bundling a platform binary; it needs one of those two on PATH. Running the full backend/frontend stack needs Python 3.12.x specifically; 3.13/3.14 aren't supported by the current dependency pins.
How is this different from HubSpot's new Breeze Invoice Prioritization feature?
Breeze (Revenue Hub, public beta as of June 2026) ranks a HubSpot user's overdue invoices by risk, age, and customer value, closer to a sort order than a score. fpp client risk returns a 0–100 score with a named-factor breakdown and a written reasoning paragraph per client, works standalone without adopting the rest of HubSpot's CRM, and pairs with jurisdiction-referenced demand-letter drafting that HubSpot doesn't offer. Worth revisiting as Breeze comes out of beta.
I followed the Quick Start exactly and uvicorn app.main:app --reload crashed on startup. Is that a bug?
Yes, a real one in the shipped apps/api/.env.example. Two of its default values don't survive Settings()'s validation: ALLOWED_ORIGINS=http://localhost:3000 needs to be a JSON array (["http://localhost:3000"]) because the field is typed list[str], and DATABASE_URL=sqlite:///./dev.db isn't a field the Settings model declares at all, so it fails with Extra inputs are not permitted. Fix both lines in your .env (or just delete the DATABASE_URL line; apps/api/app/database.py already defaults to that same SQLite path independently) and the server boots. Confirmed by running the documented steps in a clean clone.
Does fpp escalation advance actually send the email or move the invoice forward?
No. It calls /api/v1/escalations/{id}/draft, which returns an AI-drafted preview only. The backend has no endpoint today that persists a stage change or sends the email. See What's Not Implemented Yet.
What happens if I don't have an ANTHROPIC_API_KEY set?
The app still starts once the two .env fixes above are applied, but the AI routes behave differently: client risk falls back to a deterministic heuristic score (documented in risk_service.py), while escalation advance and the demand-letter endpoints return a 503 with no fallback.
Can I use this for a real client engagement today?
For the CLI against your own self-hosted backend and Supabase project, yes. The MIT license also permits using or embedding this in a real client engagement or your own product; see License for the exact terms.
Contributing
GitHub Issues are open for bug reports and feature requests. Pull requests are welcome; open an issue first for anything non-trivial so the approach can be agreed on before you put in the work. Reach out via github.com/RudrenduPaul with questions.
License
MIT. See LICENSE for full terms.
Contact: github.com/RudrenduPaul
Built by Rudrendu Paul and Sourav Nandy · Developed with Claude Code
