Production-grade REST API for freelance invoicing with bulletproof financial integrity.
Most freelance invoicing tools are built as CRUD apps with business logic scattered across views and serializers. This leads to real money bugs: incorrect totals, double-billed hours, invoices edited after payment, and cross-tenant data leaks.
ClientFlow enforces financial correctness at the model layer - if it can't be guaranteed by the database and business rules, it won't happen. Built with Django 5, DRF, and tested with 33 tests.
| Feature | Why It Matters |
|---|---|
| Financial Invariants | Payments clamp to outstanding balance. Discounts can't create negative taxes. Totals recalculate atomically. |
| Row-Level Invoice Numbering | Invoice numbers allocated under select_for_update() per account - impossible to get duplicates even under concurrency. |
| Immutable Settled Invoices | Paid or void invoices cannot be modified. Prevents re-billing or tampering with paid work. |
| Two-Layer Multi-Tenancy | Queryset scoping + object-level permission re-checks. Another user's data is unreadable, unwritable, and undeletable. |
| Time Tracking with Snapshots | Hourly rates snapshotted at log time - rate changes never rewrite historical billing. |
| Automatic Invoice Generation | Generate invoices from unbilled time entries with one click. |
| PDF Generation | Professional PDF invoices via ReportLab. |
| Receivables Dashboard | Real-time view of who owes what, with overdue tracking. |
[Deploy to Render/Railway and add live URL here]
- API Docs (Swagger):
/api/docs/ - OpenAPI Schema:
/api/schema/ - Health Check:
/healthz
Demo credentials: demo / demo-pass-1234 (after running seed data)
Django 5 Django REST Framework PostgreSQL JWT Auth ReportLab Docker drf-spectacular Gunicorn WhiteNoise
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python manage.py migrate
python manage.py seed_demo --reset
python manage.py runserverAPI docs at http://127.0.0.1:8000/api/docs/
docker compose up --buildGET /api/clients/ List/manage clients
GET /api/projects/ List/manage projects
GET /api/time-entries/ Log trackable time
POST /api/invoices/generate/ Generate from unbilled time
POST /api/invoices/{id}/send/ Mark as sent
POST /api/invoices/{id}/payments/ Record payment
GET /api/invoices/{id}/pdf/ Download PDF
GET /api/invoices/receivables/ Outstanding balances
GET /api/dashboard/ Business overviewpython manage.py test33 tests covering money maths, tax/discount edge cases, invoice numbering collisions, payment clamping, settled-invoice immutability, multi-tenant isolation, PDF generation, and dashboard aggregation. Runs in ~50 seconds with SQLite, no external services needed.
- Refuses boot with
DEBUG=Falseand default secret key - Auto-enables security headers, HSTS, secure cookies in production
- Consistent error envelope across all endpoints
- Rate-limited auth endpoints
IntegrityErrorcaught and sanitized (no schema leakage)
Ready to deploy on Render or Railway with included Dockerfile, render.yaml, and Procfile.
MIT License - see LICENSE for details.
- Hosted/Pro: need a managed 24/7 endpoint, API keys, quotas, or integration help? Open an issue: https://github.com/sumitrao9/clientflow/issues
- Sponsor: GitHub Sponsors (FUNDING.yml) supports maintenance.
- Hire/Consulting: custom features, deployment, or automation workflows (authorized use only).
Built by Sumit Yadav. Authorized/ethical use only.