Build Invoice Ninja

The build, in order

1. 1

   Clients

   hideshow

   Clients with currency and rate, and a delete that refuses to orphan invoices.

   1. 1.1Create the project and the tables

      clients (id, name, email, address, currency, default_rate_cents, notes), invoices (id, number unique, client_id, issue_date, due_date, currency, status, notes, terms, sent_at, paid_at, stripe_link, snapshot JSON), line_items (id, invoice_id, position, description, quantity, unit_price_cents, tax_rate).

      terminalcopy

      mkdir invoices && cd invoices && git init && npm init -y && npm pkg set type=module
      npm install express@4 better-sqlite3@13
      mkdir -p data/pdf config && cp .env.example .env

   2. 1.2Build client CRUD

   done when · tick each as it passes

   • A client saves and reloads with the currency intact
   • Deleting a client with invoices is refused

   next phase
2. 2

   Invoices and line items

   hideshow

   Totals to the cent and numbers that never collide or reuse.

   1. 2.1Build invoice creation with line items

      Subtotal, tax and total in integer cents, rounding once at the end.

   2. 2.2Allocate numbers inside a transaction

      INV-2026-001 style, never reused after a delete; gaps are fine, duplicates are not.

   done when · tick each as it passes

   • A three-line invoice with mixed tax rates totals correctly to the cent
   • Two invoices created concurrently get distinct numbers
   • Deleting the latest invoice does not cause the next to reuse its number

   next phase
3. 3

   Status and the snapshot

   hideshow

   Sending freezes the document; editing after requires a revision.

   1. 3.1Implement draft, sent, paid and void with the snapshot frozen on send

      Copy the client's name, address and every line into snapshot; render sent invoices from it only.

   2. 3.2Add a revise action that voids and reissues under a new number

      The only way to change a sent invoice.

   done when · tick each as it passes

   • Changing a client's address after sending leaves the sent invoice's PDF and HTML unchanged
   • A sent invoice cannot be silently edited

   next phase
4. 4

   PDF

   hideshow

   A clean one-page PDF from your template, byte-identical when regenerated.

   1. 4.1Install Puppeteer and write the HTML template

      Logo, business details, line table, totals, terms and payment details from config/business.json.

      Files templates/invoice.html

      terminalcopy

      npm install puppeteer@23

   2. 4.2Render from the snapshot to PDF_DIR

      Reuse one browser instance; close pages in finally.

   done when · tick each as it passes

   • A short invoice is one page
   • Totals match the screen exactly
   • It opens correctly in a phone mail client
   • Regenerating a sent invoice's PDF later is byte-identical

   next phase
5. 5

   Email

   hideshow

   Sent means sent; failure leaves it a draft with the error visible.

   1. 5.1Send the PDF over SMTP_URL and record sent_at only on success
      terminalcopy

      npm install nodemailer@6

   2. 5.2Log every send attempt and allow resending without renumbering

   done when · tick each as it passes

   • A real send arrives with the PDF attached and readable
   • A failed send leaves the invoice in draft with the error shown
   • The same invoice resends without a new number

   next phase
6. 6

   Payment links

   hideshow

   A Stripe link per invoice, paid marked by hand.

   1. 6.1Create a Stripe Payment Link for the invoice total and store it
      terminalcopy

      npm install stripe@17

   2. 6.2Include it in the PDF and the email; mark paid by hand records paid_at and locks

   done when · tick each as it passes

   • The link opens a correct amount in the right currency
   • Mark paid records paid_at and locks the invoice

   next phase
7. 7

   Dashboard and books

   hideshow

   What is unpaid, and an export your accountant can use.

   1. 7.1Build the unpaid dashboard with days outstanding and totals by month and client
   2. 7.2Stream a CSV export of everything

      The export is what makes this handover-able to an accountant.

   done when · tick each as it passes

   • Days outstanding is correct across a month boundary
   • The CSV reconciles with the invoice table to the cent

   next phase
8. 8

   Backup and deploy

   hideshow

   Database and PDFs backed up together, one restore performed.

   1. 8.1Nightly copy of the database plus PDF_DIR, thirty kept; restore once
      terminalcopy

      tar czf backups/invoices-$(date +%F).tgz data/

   2. 8.2Write the README

      The numbering rule, where PDFs live, and the tax disclaimer in plain language.

      Files README.md

   done when · tick each as it passes

   • A restore brings back both data and the PDFs of sent invoices
   • The README carries the tax disclaimer

   next phase