Project: an invoicing application

An invoice is not a record. It is a document somebody can be held to, and that changes what the software has to guarantee: the number must be unique and gap-free, the document must not change after it is sent, the arithmetic must be exact, and every change must leave a trace.

Chapter forty did the arithmetic. This chapter is the rest, and most of it is about refusing to do things.

What makes this harder than CRUD

• Numbering
• INV-202610-0003 must be unique, sequential and gap-free, under concurrent creates
• Immutability
• A sent invoice is evidence. You correct it with another document, not with an edit
• State
• Draft, sent, part paid, paid, void, and the transitions that are not allowed
• Money
• Totals, tax, partial payments, in a currency that is not always yours
• Trace
• Who changed what, when, kept in something nobody can quietly rewrite

Numbering, which is a concurrency problem in disguise

The naive version is SELECT MAX(number) + 1, and it is wrong the first time two people create an invoice in the same second. Both read the same maximum, both write the same number, and one of them wins depending on your unique index.

grit generate sequence Invoice --prefix INV \
  --reset monthly --width 4

That creates a counter package backed by a table, and a typed wrapper:

number, err := services.NextInvoiceNumber(db, time.Now())
// INV-202610-0001

The table is one row per sequence and period:

type Counter struct {
    Name      string `gorm:"primaryKey;size:50"`
    Bucket    string `gorm:"primaryKey;size:20"`
    NextValue uint64 `gorm:"not null;default:0"`
}

Bucket is the period key: 202610 for a monthly reset, 2026 for yearly, empty for never. The increment runs inside a transaction holding a row-level lock:

tx.Clauses(clause.Locking{Strength: "UPDATE"}).
    Where("name = ? AND bucket = ?", cfg.Name, bucket).
    First(&c)

so concurrent callers serialise on that row rather than racing.

import cycle not allowed

Immutability, and why an edit is the wrong verb

A draft is yours to change. A sent invoice is not, because a copy exists outside your database, in somebody's inbox and somebody else's accounts.

So the model has two regimes:

func (s *InvoiceService) Update(ctx context.Context,
    id uint, in UpdateInvoice) (*models.Invoice, error) {

    inv, err := s.GetByID(ctx, id)
    if err != nil {
        return nil, err
    }
    if inv.Status != "draft" {
        return nil, ErrNotEditable
    }
    ...
}

and a correction is a second document:

func (s *InvoiceService) CreditNote(ctx context.Context,
    id uint, reason string) (*models.CreditNote, error)

The ledger of what actually happened goes in a resource nobody can rewrite:

grit generate resource LedgerEntry --append-only \
  --fields "invoice:belongs_to:Invoice, kind:string, \
amount:money, note:text"

--append-only means no update and no delete routes, a GORM guard, and a database trigger installed by grit migrate. Three layers, because the one that matters is the one that still holds when somebody writes a quick script against the database directly.

The state machine, written as methods

Statuses in a dropdown are a suggestion. Statuses as methods are a rule:

func (s *InvoiceService) Send(ctx context.Context, id uint) (
    *models.Invoice, error) {

    inv, err := s.GetByID(ctx, id)
    if err != nil {
        return nil, err
    }
    switch inv.Status {
    case "sent", "paid":
        return inv, nil          // idempotent
    case "void":
        return nil, ErrVoided
    }
    if len(inv.Items) == 0 {
        return nil, ErrNoLines
    }

    now := time.Now().UTC()
    inv.Status, inv.SentAt = "sent", &now

    if err := s.db(ctx).Save(inv).Error; err != nil {
        return nil, fmt.Errorf("sending %d: %w", id, err)
    }
    events.Emit(ctx, events.InvoiceSent{ID: inv.ID})
    return inv, nil
}

The transitions worth refusing, in any document workflow:

• Send an empty invoice
• A document with no lines is a mistake, not a zero bill
• Void a paid invoice
• Money moved. Refund it, do not pretend
• Pay a draft
• The customer has not been asked yet
• Edit after sending
• Covered above

Payments, and the status you should not store twice

A payment is its own record, because partial payments exist and because a payment has a date and a method that the invoice does not:

grit generate resource Payment \
  --fields "invoice:belongs_to:Invoice, amount:money, \
paid_on:date, method:select:bank=Bank|card=Card|cash=Cash"

The balance is arithmetic over payments, not a column somebody updates:

func (inv *Invoice) Balance() (money.Money, error) {
    total, err := inv.Total()
    if err != nil {
        return money.Money{}, err
    }
    for _, p := range inv.Payments {
        total, err = total.Sub(p.Amount)
        if err != nil {
            return money.Money{}, err
        }
    }
    return total, nil
}

The document itself

The admin gives you two ways out of the screen:

Print and PDF. The detail page has a print action, and PDF rendering uses@react-pdf/renderer in the browser, lazy loaded so it is not in the first load of every list page.

Excel. The list exports with the current filters applied, through xlsx, also lazy loaded.

Reminders, in one line for now

Overdue invoices should chase themselves:

grit generate job SendInvoiceReminders --cron "0 9 * * *"

That writes a job that runs at nine every morning. Chapter forty three is about what makes a job safe to run unattended: retries, idempotency, and what happens when it fails at three in the morning. For now, note the shape: the job calls the same service method a human would, so the rules cannot be bypassed by automation.

grit new billing && cd billing
  grit generate resource Client \
    --fields "name:string, email:email, address:text"
  grit generate resource Invoice \
    --fields "number:string, client:belongs_to:Client, \
issued:date, due:date, \
status:select:draft=Draft|sent=Sent|paid=Paid|void=Void" \
    --items "InvoiceItem:description:string,qty:int,unit:money"
  grit generate sequence Invoice --prefix INV --reset monthly
  grit generate resource Payment \
    --fields "invoice:belongs_to:Invoice, amount:money, paid_on:date"
  grit generate resource LedgerEntry --append-only \
    --fields "invoice:belongs_to:Invoice, kind:string, amount:money"
  grit migrate

var wg sync.WaitGroup
for i := 0; i < 50; i++ {
    wg.Add(1)
    go func() { defer wg.Done(); createInvoice(t) }()
}
wg.Wait()

Assignment

Commit your work with the message Invoicing - Assignment One, exactly as written, so the leaderboard can score it.