Fifty written case studies

ReplaySkip

skip a repeated file import

Problem A nightly file import wrote the same rows again whenever the job was retried.

Solution The reference stores a hash of the file with the UTC day and records a skip when both match.

Result A second upload of the same file is a visible skip instead of a second batch.

PythonSQLiteCSVIdempotencyFastAPI

Written reference for Backend engineer. Not a live process and not a client project.

CursorPage

keyset pagination for a list API

Problem Offset pagination drifted when rows were inserted during a long export.

Solution The reference uses a stable sort key and an opaque cursor, and rejects a cursor from another filter.

Result A client can resume a list without repeating or skipping rows that arrived mid-export.

PythonFastAPIREST APISQLitePagination

Written reference for Backend engineer. Not a live process and not a client project.

OutboxMail

an idempotent notification outbox

Problem A request that succeeded still sent a second email when the worker retried.

Solution The reference writes the message first, sends it once, and stores the provider id on that row.

Result A retry finds the same row and does not create a second message.

PythonSQLiteEmailRetriesFastAPI

Written reference for Backend engineer. Not a live process and not a client project.

SignHook

verify signed inbound webhooks

Problem Inbound webhooks were accepted with no check that the sender still held the secret.

Solution The reference checks the timestamp window and the HMAC, and stores the event id for one day.

Result A replay of an old body is rejected, and a new event id is stored once.

PythonFastAPIWebhooksHMACSecurity

Written reference for Backend engineer. Not a live process and not a client project.

TokenBucket

a per-key request budget

Problem One noisy client could fill the API while other tenants waited.

Solution The reference keeps a token bucket per API key and returns a clear retry-after when the bucket is empty.

Result A burst is absorbed, and a sustained flood is told when to call again.

PythonFastAPIRedisRate LimitingAPI

Written reference for Backend engineer. Not a live process and not a client project.

CronLock

stop overlapping scheduled jobs

Problem A slow export was still running when the next timer started a second copy.

Solution The reference takes a lease in SQLite and exits if the previous run still holds it.

Result The timer log shows a skip instead of two writers on the same table.

PythonLinuxsystemdSQLiteCron

Written reference for DevOps. Not a live process and not a client project.

StampedeLock

one refresh for a hot cache key

Problem When a cache key expired, every waiter rebuilt the same expensive report.

Solution The reference lets one worker rebuild and has the others read the new value.

Result A stampede becomes one rebuild plus a set of readers.

PythonFastAPICachingSQLiteAPI

Written reference for Backend engineer. Not a live process and not a client project.

EtagShelf

conditional GET for JSON snapshots

Problem A dashboard polled a large JSON snapshot that rarely changed.

Solution The reference returns an ETag and answers 304 when the caller still has that tag.

Result Unchanged polls stay small, and a real change still returns the new body.

PythonFastAPIHTTPCachingJSON

Written reference for Backend engineer. Not a live process and not a client project.

DeadLetter

a page for jobs that gave up

Problem Failed jobs disappeared into a log file nobody opened.

Solution The reference moves a job to a dead-letter table after the retry budget and shows the last error.

Result An operator can see the payload and the error without reading a raw log.

PythonFastAPISQLiteQueuesRetries

Written reference for Backend engineer. Not a live process and not a client project.

ReplayHook

replay one stored webhook

Problem A downstream timeout left the operator with no way to try that one event again.

Solution The reference stores the raw body and can post that same body once more under a new attempt id.

Result The original event stays intact, and the new attempt is a separate row.

PythonFastAPIWebhooksSQLiteAPI

Written reference for Backend engineer. Not a live process and not a client project.

SpamGate

score obvious form abuse

Problem A public form accepted the same body many times from disposable addresses.

Solution The reference scores duplicate bodies and disposable domains, and holds those rows for review.

Result A repeated paste is queued for a person instead of creating another ticket.

PythonFastAPIFormsSQLiteValidation

Written reference for Backend engineer. Not a live process and not a client project.

TzRoster

an on-call roster in UTC

Problem Handover notes named local times and the next person missed the window.

Solution The reference stores every shift in UTC and renders it in the viewer's zone.

Result The roster page shows one unambiguous start and end for each shift.

PythonFastAPISchedulingSQLiteLinux

Written reference for DevOps. Not a live process and not a client project.

SlugTenant

route a host to one tenant

Problem Two customers shared a process and a request could read the other customer's rows.

Solution The reference maps the host header to a tenant id and applies that id on every query.

Result A request for an unknown host is refused before it touches tenant data.

PythonFastAPIMulti-tenantSQLiteHTTP

Written reference for Backend engineer. Not a live process and not a client project.

SqlReader

a read-only query allowlist

Problem Support wanted answers from the database without a writable login.

Solution The reference exposes a fixed set of SELECT statements with bound parameters.

Result A viewer can run those queries and cannot send arbitrary SQL.

PythonSQLiteSQLFastAPISecurity

Written reference for Backend engineer. Not a live process and not a client project.

MigrateDry

a migration dry-run report

Problem A schema change was applied before anyone saw which tables it touched.

Solution The reference prints the planned statements and the row counts they would scan, and stops there.

Result The report is a review artifact. It does not alter the database.

PythonSQLiteMigrationsSQLFastAPI

Written reference for Backend engineer. Not a live process and not a client project.

FixtureLab

deterministic fixtures for tests

Problem Tests failed when they depended on wall-clock time or insert order.

Solution The reference builds fixtures from a seed and freezes the clock used by the test.

Result The same seed produces the same rows on a second run.

PythonpytestSQLiteTestingFastAPI

Written reference for Backend engineer. Not a live process and not a client project.

PactFixture

consumer examples for one API

Problem A client and a server drifted because each side invented its own example.

Solution The reference stores one request and response pair and checks both sides against it.

Result A changed field fails the fixture check before either side is released.

PythonOpenAPIJSONpytestREST API

Written reference for Backend engineer. Not a live process and not a client project.

LoadNote

summarize a local load-test log

Problem A load test left a raw log and no single page of what it actually hit.

Solution The reference reads a log the operator already recorded and charts status codes and latency.

Result The page describes that local run only. It does not send traffic anywhere.

PythonHTTPJSONFastAPITesting

Written reference for Backend engineer. Not a live process and not a client project.

CspInbox

collect Content-Security-Policy reports

Problem Browser CSP violations were invisible until a customer pasted a console screenshot.

Solution The reference accepts the report endpoint and groups the blocked URLs.

Result A reviewer sees which directive fired and how often, with no page content stored.

PythonFastAPISecurityHTTPSQLite

Written reference for DevOps. Not a live process and not a client project.

UnitLint

review a systemd unit file

Problem A unit file shipped without a restart limit or a writable directory of its own.

Solution The reference reads the unit text and lists missing Restart, User, and ProtectSystem lines.

Result The output is a checklist. It does not install or start the unit.

LinuxsystemdPythonDevOpsSecurity

Written reference for DevOps. Not a live process and not a client project.

DiskMark

alert before a disk fills

Problem A host filled its disk overnight and the only signal was a failed write.

Solution The reference records free space on a timer and opens a row when it crosses a watermark.

Result The page shows the samples it recorded. It does not page a real phone.

PythonLinuxMonitoringSQLitesystemd

Written reference for DevOps. Not a live process and not a client project.

CertCal

a calendar of certificate dates

Problem Certificate expiry was a date in a ticket that nobody reread.

Solution The reference reads PEM files the operator points at and lists the not-after dates.

Result A certificate inside the warning window is a row on the calendar.

PythonTLSLinuxMonitoringFastAPI

Written reference for DevOps. Not a live process and not a client project.

DnsLog

diff two zone files

Problem A zone edit had no record of which records moved.

Solution The reference parses two zone files and lists added, removed, and changed records.

Result The diff is a review file. It does not publish DNS.

PythonDNSLinuxDiffDevOps

Written reference for DevOps. Not a live process and not a client project.

RedirectMap

test a table of redirects

Problem A redirect spreadsheet and the live server disagreed about status codes.

Solution The reference reads the table and checks each path against a base URL the operator supplies.

Result Mismatched status or location lines are listed. The tool only reads.

PythonnginxHTTPTestingDevOps

Written reference for DevOps. Not a live process and not a client project.

I18nCover

find missing translation keys

Problem A locale file shipped with keys the template never used, and missed keys the template did use.

Solution The reference compares template keys with each locale file.

Result Missing and unused keys are two lists a reviewer can fix.

Pythoni18nJSONTestingFastAPI

Written reference for Full-Stack & DevOps. Not a live process and not a client project.

AuditTrail

an admin action log

Problem Support could not tell who changed a setting after a complaint.

Solution The reference appends actor, action, and target for each write, and does not store secrets.

Result A viewer can filter the log by day and by actor.

PythonFastAPISQLiteAuditSecurity

Written reference for Backend engineer. Not a live process and not a client project.

RoleGrid

a permission matrix a reviewer can read

Problem Role rules lived in code and a new hire could not see them.

Solution The reference renders role against action from one table the tests also read.

Result The page and the tests disagree if someone edits only one of them.

PythonFastAPIAuthorizationSQLiteOpenAPI

Written reference for Backend engineer. Not a live process and not a client project.

CsvGate

a CSV import with a dry-run

Problem A bad CSV was imported before anyone saw the rejected rows.

Solution The reference parses the file, reports row errors, and writes nothing unless the operator confirms.

Result The dry-run page lists the rows that would be skipped and why.

PythonCSVSQLiteFastAPIValidation

Written reference for Backend engineer. Not a live process and not a client project.

JobTable

a table of background jobs

Problem Background work had no list of what was waiting, running, or finished.

Solution The reference stores state transitions and shows them on one page.

Result An operator can see a queued job become running and then finished or failed.

PythonFastAPISQLiteQueuesLinux

Written reference for Backend engineer. Not a live process and not a client project.

RetryBudget

a ceiling on retries

Problem A failing dependency was retried without a limit and crowded out other work.

Solution The reference counts attempts and stops at a budget, then records the stop.

Result The job page shows how many tries remain before it gives up.

PythonRetriesSQLiteFastAPIQueues

Written reference for Backend engineer. Not a live process and not a client project.

IncidentNote

a short incident write-up

Problem Incident notes were a chat thread that vanished by the next day.

Solution The reference stores start, impact, and the next update as a page.

Result A reader sees the timeline without joining the chat.

PythonFastAPIMarkdownSQLiteStatus Page

Written reference for DevOps. Not a live process and not a client project.

BackupRotate

keep a fixed number of snapshots

Problem Backups accumulated until the disk, not a policy, decided what to delete.

Solution The reference keeps a named count of snapshots and deletes only older ones after a successful new copy.

Result The page lists what it kept and what it removed.

PythonSQLiteLinuxBackupssystemd

Written reference for DevOps. Not a live process and not a client project.

LogSample

sample structured logs

Problem A busy service logged every line and the useful errors were hard to find.

Solution The reference keeps error lines and a sample of the rest, with the rule written on the page.

Result A reviewer can see the sample rate instead of guessing which lines were dropped.

PythonJSONLoggingLinuxFastAPI

Written reference for DevOps. Not a live process and not a client project.

SecretPre

a pre-commit secret scan

Problem A token in a fixture had landed in a commit before review.

Solution The reference scans the staged diff for a fixed set of token shapes and exits non-zero on a hit.

Result The report names the file and the rule. It does not print the secret.

PythonGitSecurityCILinux

Written reference for DevOps. Not a live process and not a client project.

DepAudit

a dependency advisory report

Problem Dependency review was a spreadsheet updated after an incident.

Solution The reference reads a lockfile and writes the advisory ids it was given.

Result The page is a report of that input. It does not claim a live vulnerability feed.

PythonpipSecurityCILinux

Written reference for DevOps. Not a live process and not a client project.

SitemapDiff

see what a sitemap added

Problem A release changed the sitemap and nobody listed the new URLs.

Solution The reference diffs two sitemap files and groups added and removed locations.

Result The result is a review list, not a crawl of someone else's site.

PythonSEOXMLHTTPDiff

Written reference for Backend engineer. Not a live process and not a client project.

LinkCheck

list broken links on one site

Problem A content site shipped links that 404'd a week later.

Solution The reference reads a seed URL the operator owns and records status codes.

Result Broken links are a table. The tool stops at the host it was given.

PythonHTTPHTMLTestingSEO

Written reference for Backend engineer. Not a live process and not a client project.

ThumbPipe

thumbnails with a width cap

Problem Uploads were stored at original size and the list page became heavy.

Solution The reference writes a bounded thumbnail beside the original and refuses a file over the cap.

Result The list page uses the thumbnail. The original stays available.

PythonImagesFastAPILinuxPillow

Written reference for Backend engineer. Not a live process and not a client project.

MdPreview

preview Markdown before publish

Problem Authors published Markdown that rendered differently from the editor.

Solution The reference renders with the same rules as the public page and shows a side-by-side preview.

Result A heading or table that will break is visible before publish.

PythonMarkdownFastAPIHTMLContent

Written reference for Full-Stack & DevOps. Not a live process and not a client project.

ClogGen

a changelog from commit titles

Problem Release notes were rewritten from memory after the tag already existed.

Solution The reference groups conventional commit titles between two refs.

Result The changelog is a draft a person still edits. It does not push a tag.

PythonGitMarkdownCIRelease

Written reference for DevOps. Not a live process and not a client project.

BadgeSvg

an uptime badge from local checks

Problem A status badge on a README was a static image that never changed.

Solution The reference draws an SVG from checks the same process already stored.

Result The badge matches the stored rows. It does not invent an uptime percentage.

PythonSVGMonitoringFastAPISQLite

Written reference for DevOps. Not a live process and not a client project.

HealthSide

a health file beside a process

Problem A process looked running while its port was refusing connections.

Solution The reference writes a health file only after a local HTTP check succeeds.

Result A supervisor can read that file and tell a live port from a live PID.

PythonLinuxsystemdHTTPMonitoring

Written reference for DevOps. Not a live process and not a client project.

OpenapiDiff

diff two OpenAPI files

Problem An API change removed a field and the client found out in production.

Solution The reference diffs two OpenAPI documents and lists removed paths and required fields.

Result The diff fails a check when a previously required field disappears.

PythonOpenAPIREST APIDiffpytest

Written reference for Backend engineer. Not a live process and not a client project.

FlagFile

feature flags in a file

Problem A feature flag lived in code and needed a deploy to turn off.

Solution The reference reads a JSON file on a timer and exposes the current flags on a page.

Result Turning a flag off is a file change. The page shows the value it loaded.

PythonFastAPIJSONConfigurationTesting

Written reference for Backend engineer. Not a live process and not a client project.

ReleaseNote

a one-page release note

Problem A release had a tag and no note of what an operator should watch.

Solution The reference fills a fixed template: changes, checks, and how to roll back.

Result The note is a file in the repo. It does not deploy anything.

PythonMarkdownGitCIRelease

Written reference for DevOps. Not a live process and not a client project.

BudgetPage

error budget from a probe log

Problem An error budget was a number in a slide, not a calculation from probes.

Solution The reference reads a probe log and shows remaining budget for a stated window.

Result The figure is the arithmetic of that log. It is labelled as such.

PythonMonitoringSQLiteFastAPISLO

Written reference for DevOps. Not a live process and not a client project.

RollbackCard

a rollback card before release

Problem A release had no written way back to the previous build.

Solution The reference is a one-page card: the previous artifact, the reload command, and the check URL.

Result The card is documentation. Running it is still a person's decision.

LinuxsystemdnginxPythonRunbooks

Written reference for DevOps. Not a live process and not a client project.

ComposeLint

review a Compose file

Problem A Compose file published a database port and had no healthcheck.

Solution The reference reads the file and lists ports bound on all interfaces and services without a healthcheck.

Result The output is a review list. It does not start containers.

Docker ComposeDockerYAMLPythonSecurity

Written reference for DevOps. Not a live process and not a client project.

NginxMap

explain a location map

Problem An nginx config grew location blocks that nobody could summarize.

Solution The reference parses location and proxy_pass lines into a table.

Result A reviewer sees which path goes to which upstream. The tool does not reload nginx.

nginxLinuxPythonHTTPDevOps

Written reference for DevOps. Not a live process and not a client project.

RunbookIndex

an index of handover notes

Problem Handover notes were scattered and a new operator could not find the restart steps.

Solution The reference indexes Markdown titles and the first command in each note.

Result The index is a page of links. It does not execute the commands.

MarkdownPythonLinuxRunbooksFastAPI

Written reference for DevOps. Not a live process and not a client project.