Quality standards

Coding

Static analysis runs on every commit and in CI: ruff for style and lint errors, mypy for type checking, bandit for known security risks in the code itself. All three must be clean before anything merges — a hard CI gate, not a guideline that can be ignored.

Dependencies are pinned via pip-compile: an .in file with the deliberately chosen direct dependencies is compiled into a full, reproducible lock. The production image installs only that lock, never the test tooling.

The final image runs on a hardened, distroless base image with no shell and no package manager, as a non-root user. That changes how you debug it, but shuts an entire class of attacks out.

Background: Ruff, mypy, OWASP Cheat Sheet Series.

Testing

Unit and integration tests are separated and marked, so a fast set — no database, no external services — can run independently of the full set. Five required checks must pass before a pull request can merge, enforced by branch protection itself, not by convention.

Coverage percentages measure execution, not verification: a line can run inside a test without anything actually checking its behaviour. That's why mutation testing also runs: small bugs are deliberately introduced into the source — a comparison flipped, a boundary shifted — and checked whether a test fails. A mutant that survives means that line of code runs under test but nothing verifies it. The core security and isolation modules carry a minimum score for this, checked every night.

Background: Martin Fowler on the test pyramid, mutmut.

Documenting

Changes live in a changelog following Keep a Changelog, with Semantic Versioning for version numbers. Major architectural choices sit apart, as a short numbered decision with context and consequences — not scattered across commit messages and conversations no one can find again.

Documentation lives in the repository itself, next to the code it describes, rather than in a separate wiki that can drift from reality. Every release checks whether the documentation still matches what the code actually does — a claim that doesn't match the code counts as a bug.

Background: Keep a Changelog, Semantic Versioning, Michael Nygard's proposal for Architecture Decision Records.

Lessons learned

Alongside the changelog — what changed — there's a separate document that reconstructs why: a chronological account, built from the git history, citing the commits each conclusion rests on. Recent chapters run longer than old ones, not because they mattered more, but because they were written while the event was still fresh — a bias the document names explicitly about itself.

Background: the broader idea of blameless postmortems, as described in Google's SRE book.

Data integrity: the Clark-Wilson model

One rule applies to all persistent data: no operation may leave data in a state that fails an integrity check. In practice: rows referenced by other data — documents, conversations, users, workspaces — are never hard-deleted. Deleting sets a timestamp; a permanent purge is a separate, explicitly authorised operation with one precondition: no active references may remain. "Retiring" and "destroying" are therefore never the same action.

Background: Clark & Wilson, "A Comparison of Commercial and Military Computer Security Policies" (1987).

The twelve factors, applied where they fit

The Twelve-Factor App describes twelve guidelines for portable, scalable web applications: configuration via environment variables, port binding without an external web server, fast startup and graceful shutdown, logs as an event stream. We follow some of them to the letter: all secrets and settings come from the environment, never from code; the process binds its own port; it runs as PID 1, so stop and restart signals reach it directly instead of through an intermediary.

We deliberately don't follow some of them fully, and that's recorded as such: the process keeps in-memory state instead of being fully stateless, and the database layer is synchronous instead of async. That's an explicit choice for a single-node application for a small team, not a forgotten chapter — including the point at which that choice should be revisited.

Background: The Twelve-Factor App (Adam Wiggins, Heroku, 2011).

When something gets called "production-grade"

"Production-grade" isn't a feeling but a list of eight measurable criteria: fail-closed boot, authorisation on by default, a tested restore operation, a reproducible release, and more. Only once all eight are green may that claim appear in the documentation. Even once that was true, the actual release still sat for a few more days — lifting that gate is deliberately a human decision, not an automatic checklist.

Background: the broader idea of release readiness reviews, also from Google's SRE book.

Era-defining articles in IT

Some articles have permanently shaped how software gets built. A small, personal selection — three of them already appear in practice above.

A Comparison of Commercial and Military Computer Security Policies

Clark & Wilson, 1987 — laid the foundation for the integrity model applied above to all persistent data. Original paper.

MapReduce: Simplified Data Processing on Large Clusters

Dean & Ghemawat, Google, OSDI 2004 — the model that let huge volumes of data be processed across thousands of machines without every developer having to program distribution, failure and recovery themselves. Laid the groundwork for Hadoop and a whole generation of data-processing systems after it. Original paper.

Attention Is All You Need

Vaswani et al., Google, NeurIPS 2017 — introduced the transformer architecture and the attention mechanism (query, key, value — what the Solbyco logo refers to), and underlies almost every language model built since, including the models LocalChat runs locally. Original paper.

The Twelve-Factor App

Adam Wiggins, Heroku, 2011 — not a scientific paper but just as influential: a compact set of rules for cloud-native applications that's still, years later, the standard vocabulary for how teams talk about deployment. Full text.

Documenting Architecture Decisions

Michael Nygard, 2011 — the simple idea that an architectural choice is worth as much as the reason behind it, recorded next to the code instead of in a meeting no one can find again. Original blog post.

Vibe coding

Andrej Karpathy, X, 2 February 2025 — coined the term in an offhand tweet: you "fully give in to the vibes ... and forget that the code even exists." A year later he drew the line more sharply himself: vibe coding raises the floor (a first version, fast), agentic engineering raises the ceiling (reliable, maintainable, verifiable) — and those aren't the same job.

Do: use it for exploration, throwaway prototypes and a first pass at an approach, where "it works" is the only criterion; a human stays the last step — reviewing before it merges.

Don't: merge generated code nobody has read, or assume "it runs" means "it's correct" — exactly the distinction already drawn above under Testing, between coverage and verification.

Background: Karpathy's original post (2 February 2025).