Joseph Leporati

Engineering notes

Writing

Notes on building and running production systems: payments and ledgers, multi-tenant architecture, reliability and performance, and applied AI. By Joseph Leporati, software engineer and technical program manager in Monroe, Louisiana.

· 8 min read · ai

AI That Cites Its Sources for Louisiana Local Government

A trustworthy local government assistant only answers from an indexed copy of the agency's own ordinances, minutes and records. It refuses when retrieval finds nothing strong enough, and it checks every claim against the exact quoted text before showing it. The citation has to point to a specific version and section, and the system has to log each answer so the agency can audit it. Retrieval alone still produces wrong answers. Verification after the model writes is what catches them.

Read the article

· 7 min read · database migration

Can You Migrate an Old Database Without Taking the Business Offline?

Usually, yes. If your team or vendor controls the application code, the expand-contract pattern changes a live database in additive steps: add the new structure, write to both, backfill history, move reads over, and drop the old structure last. Nothing goes offline and every step can be reversed. If you are replacing a system whose code you cannot change, a parallel run is safer. It costs extra weeks, but it removes the hard cutover.

Read the article

· 7 min read · commissions

Designing a Commission Engine That Survives Refunds and Chargebacks

Commission balances drift because a single mutable number can't record why it changed. Build the engine as a double-entry ledger instead. Postings are insert-only, every entry sums to zero, and refunds or chargebacks are posted as exact reversals of the original entry, never as edits. Give each party and holdback its own account, derive balances from postings, and run trial-balance and clearing-account checks on every batch so drift shows up within a day.

Read the article

· 7 min read · performance

Average Response Time Looks Fine but the App Is Slow: Check p95/p99

Your average is diluting the slowest requests. Latency distributions are right-skewed, so a few multi-second requests barely move the mean, and those few are what customers remember. Track p50, p95 and p99 from histograms, broken down by route. Then trace the slow requests to their cause, which is usually GC pauses, cold starts, N+1 queries or a saturated dependency. Do all of that before anyone quotes you a rebuild.

Read the article

· 8 min read · fractional cto

What a Fractional CTO Does: Audits, Architecture and Metrics

A fractional CTO takes on CTO accountability part time: authority over architecture, vendor and contract risk, reliability targets, security posture, the roadmap and hiring. The work usually starts with a 2 to 4 week audit of code, infrastructure and delivery. After that it runs as a retainer that reports a short list of metrics. It suits organizations whose software handles money or records but that can't justify a full time technology executive.

Read the article

· 7 min read · multi-tenant

Multi-Tenant Data Isolation: Shared Schema, RLS, or Separate DBs

For most multi-client portals and SaaS products, use one shared schema with a tenantid column on every tenant-owned table, and enforce PostgreSQL row-level security (RLS) under it so the database, not each developer, filters every query by tenant. Choose database-per-tenant only when a contract or regulation requires physical separation. Schema-per-tenant rarely justifies its migration overhead. RLS is only a real backstop if you configure FORCE, WITH CHECK and CI checks correctly.

Read the article

· 7 min read · payments

Why Did We Get Charged Twice? Designing Idempotency for Payments

Most double charges come from a timeout. The first request reaches the processor, the response gets lost, and the client retries, so the system charges again. The fix is a client-generated idempotency key, stored atomically with the first attempt and backed by a database uniqueness constraint. An optional distributed lock covers the check-then-create race. Before you trust it with real money, test deliberate replays, timeouts and concurrent duplicates.

Read the article