Performance Best Practices

Practical, high-leverage rules for writing fast code across the Code2b stack: Go services, Postgres, and the Next.js frontend. Each item is short on purpose. Apply the cheap wins first, measure, then optimize the hot path.

Rule zero: measure before you optimize. Profile, find the real bottleneck, fix that. Guessing wastes time and adds complexity for no gain.

General principles

1. The fastest work is work you don't do. Cache, skip, batch, or precompute before you micro-optimize.
2. Optimize the hot path, not the whole codebase. 5% of the code causes 95% of the slowness. Leave the rest readable.
3. Reduce round trips. One query, one request, one allocation beats N of them. N+1 is the number-one real-world killer.
4. Do work once. Compute at boot or write time, not on every read.
5. Keep data close. Memory beats cache beats disk beats network. Move work down that list.
6. Readable first, fast second, unless proven hot. A clever line that saves a nanosecond in cold code is a net loss.

Variables and memory

// Bad: reallocates on every append, unknown final size
var ids []uuid.UUID
for _, lead := range leads {
    ids = append(ids, lead.ID)
}
 
// Good: one allocation
ids := make([]uuid.UUID, 0, len(leads))
for _, lead := range leads {
    ids = append(ids, lead.ID)
}

Functions

// Bad: one DB round trip per lead
for _, lead := range leads {
    repo.UpdateStatus(ctx, lead.ID, "DONE")
}
 
// Good: one round trip
repo.UpdateStatusBulk(ctx, ids, "DONE")

Loops and algorithms

// Bad: O(n*m), scans allowed list for every lead
for _, lead := range leads {
    for _, id := range allowedIDs {
        if lead.ID == id { keep(lead) }
    }
}
 
// Good: O(n+m), set lookup
allowed := make(map[uuid.UUID]struct{}, len(allowedIDs))
for _, id := range allowedIDs { allowed[id] = struct{}{} }
for _, lead := range leads {
    if _, ok := allowed[lead.ID]; ok { keep(lead) }
}

Concurrency (Go)

// Bound fan-out to LLM_CONCURRENCY (see docvalidation card)
sem := make(chan struct{}, concurrency)
g, ctx := errgroup.WithContext(ctx)
for _, dim := range dimensions {
    dim := dim
    sem <- struct{}{}
    g.Go(func() error {
        defer func() { <-sem }()
        return audit(ctx, dim)
    })
}
if err := g.Wait(); err != nil { return err }

Database (Postgres)

The single biggest source of real slowness. Fix here first.

-- Bad: N+1, one query per job
SELECT * FROM leads WHERE lead_job_id = $1;  -- run once per job
 
-- Good: one query for all jobs
SELECT * FROM leads WHERE lead_job_id = ANY($1);

-- Index the columns you filter and join on
CREATE INDEX IF NOT EXISTS idx_leads_job_id ON leads (lead_job_id);

Caching

API and network

Frontend (Next.js / React)

// Bad: recomputed on every render
const sorted = leads.sort((a, b) => a.score - b.score)
 
// Good: recomputed only when leads change
const sorted = useMemo(
  () => [...leads].sort((a, b) => a.score - b.score),
  [leads],
)

Measuring

You cannot fix what you cannot see. Reach for these before optimizing.

Checklist for a performance pass

• Profiled and confirmed the actual bottleneck (not guessed)
• No N+1 queries; related data fetched in one round trip
• Filter, sort, and join columns are indexed
• List endpoints and queries are paginated / bounded
• Slices and maps preallocated where size is known
• No allocations or expensive calls inside hot loops
• Independent I/O runs in parallel, with bounded concurrency
• Expensive, stable reads are cached with a clear invalidation rule
• Frontend: heavy components lazy-loaded, long lists virtualized, expensive work memoized
• Re-measured after the change to confirm a real gain

When in doubt, measure first and copy the pattern already used in enrichabl (pricing cache, bounded fan-out) or docvalidation (concurrent fan-out with LLM_CONCURRENCY).