The Problem
Freelancers need a lightweight way to issue quotes, convert them to invoices, collect signatures, and track payments without juggling separate tools or manual PDFs. The process is error‑prone and time‑consuming when done with spreadsheets and generic document editors.
What This Does
invoicerr delivers a self‑hosted web app that covers the full quote‑to‑payment lifecycle. The backend lives in backend/ (NestJS, Prisma) and starts at backend/src/main.ts. It provides REST endpoints for clients, invoices, quotes, signatures, webhooks, and a plugin system (backend/src/plugins/). The frontend is a React SPA under frontend/, bootstrapped from frontend/index.html and compiled from the TSX components in frontend/src/components/. Dockerfiles and a docker-compose.yml enable a single‑command deployment that spins up the API, a PostgreSQL database (or SQLite locally), and the UI.
How To Use It
Setup
Clone git clone https://github.com/Impre-visible/invoicerr.git cd invoicerr Copy example env files cp backend/.env.example backend/.env cp frontend/.env.example frontend/.env # if needed Edit backend/.env (or docker‑compose env block) with real values: DATABASEURL, APPURL, SMTP, JWTSECRET
Build / Deploy
Docker (recommended) – the repo ships a ready‑made image and compose file.
docker compose up -d # builds backend, frontend and DB
Local development – Node 20+ is required.
Backend
cd backend npm ci # installs deps from backend/package.json npm run start:dev # runs NestJS (backend/src/main.ts)
Frontend
cd ../frontend npm ci npm run dev # starts React dev server (vite/webpack)
Running the App
API reachable at http://localhost:3000 (default NestJS port). UI served at http://localhost (Docker maps port 80). Swagger/OpenAPI docs are auto‑generated by NestJS (/api if enabled).
All configurable values are documented in the README and the .env.example files.
Real‑World Use
A freelancer signs up, creates a client record (POST /clients), drafts a quote (POST /quotes), and sends the generated PDF link via the built‑in email service (SMTP). The client opens the link, signs using the Documenso provider (backend/src/plugins/signing/providers/documenso/), and the backend records the signature status. Once signed, the quote can be promoted to an invoice (POST /invoices), and a payment webhook (e.g., Slack) notifies the freelancer automatically (backend/src/modules/webhooks/drivers/slack.driver.ts).
Code Health & Issues
Bugs / Risks Med – Default JWT secret – backend/src/lib/auth.ts falls back to a hard‑coded secret if JWTSECRET is unset; could be exploited in production. Med – Prisma binary limitation – README notes lack of linux/arm/v7 support; deployments on 32‑bit ARM will fail. SDLC & Code Violations Low – Secrets in repo – .env.example contains placeholder credentials but no real secrets; acceptable. Low – License clarity – Both LICENSE (MIT‑style) and LICENSE.COMMERCIAL.md are present; users must read both to understand permitted use. Low – Test coverage – 7 test files exist (backend/test/ and e2e), but core plugin logic (src/plugins/) lacks dedicated unit tests. Low – CI – GitHub Actions for CodeQL, Cypress, Docker build, and publish are configured (.github/workflows/), showing a decent CI pipeline.
Overall, the repo includes linting (.eslintrc.js), formatting (.prettierrc), and a Prisma migration history, indicating disciplined development practices.
The Bottom Line
invoicerr is a well‑structured, Docker‑ready invoicing platform that covers quote creation, signing, and payment tracking out of the box. It is suitable for solo freelancers or small agencies that can host their own instance and are comfortable managing environment variables and a PostgreSQL/SQLite database. The main concerns are the fallback JWT secret and limited ARM support; addressing these will make the solution production‑ready for a broader audience.