Freelancer Payment Protection

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# or: uvx freelancer-payment-protection-cli --help# or: npx freelancer-payment-protection-cli --help

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
• Features
• Run the full stack locally
• Command-Line Interface
• API Reference
• Comparison
• Architecture
• MCP Server
• Security
• What's Not Implemented Yet
• FAQ
• Contributing
• License

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

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.gitcd freelancer-payment-protectionpnpm install
# Backend envcp apps/api/.env.example apps/api/.env# apps/api/.env.example ships two values that don't parse as written. See the# Troubleshooting question in the FAQ before you skip this:#   ALLOWED_ORIGINS=["http://localhost:3000"]   (needs the JSON-array brackets)#   delete the DATABASE_URL= line entirely (Settings doesn't accept it; the#   app already defaults to sqlite:///./dev.db without it)
cp apps/web/.env.example apps/web/.env.local
pip install -r apps/api/requirements.txtpython -m alembic -c packages/db/migrations/alembic.ini upgrade headpython 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.

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 credentialsfpp 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 stagefpp escalation status <invoice-id> [--json] Current stage + full historyfpp 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 loginfpp 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 probeGET    /health/ready                          Readiness (DB)
GET    /api/v1/clients                        ListPOST   /api/v1/clients                        CreateGET    /api/v1/clients/{client_id}            DetailPUT    /api/v1/clients/{client_id}            UpdateDELETE /api/v1/clients/{client_id}            Delete
GET    /api/v1/invoices                       ListPOST   /api/v1/invoices                       Create (manual)GET    /api/v1/invoices/{invoice_id}          DetailPATCH  /api/v1/invoices/{invoice_id}/status   Update status
GET    /api/v1/escalations                    Active escalationsPOST   /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 letterPOST   /api/v1/legal/demand-letter/stream     Generate + stream (SSE)
GET    /api/v1/evidence/{invoice_id}          Evidence itemsPOST   /api/v1/evidence/{invoice_id}/upload   Manual uploadDELETE /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.

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

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