Engineering Notes
Why the engineering decisions were made. The reasoning, the trade-offs, and the failures that taught us each lesson. We collected them over decades in different shapes and forms, starting with Post-It notes and the latest maintained in our own Markdown Notes Manager connected to Github repo.
The Reepolee Approach summarizes the principles. These notes preserve the arguments, tradeoffs, and implementation decisions behind them.
Read Our ApproachNot Everything Needs an LLM
Why smart teams use LLMs to build generators, not to replace them - and how encoding domain knowledge once, deterministically, beats paying an API per token forever.
MVC Separated the Wrong Things
On code proximity, feature-per-folder, single-file templates, and why Tailwind classes tell you more about a component than a semantic class name ever will.
Default Is a Feature
On keeping tools at their defaults, the portability of skills over config, why TUIs are nostalgia dressed in Rust, and what native GUI tools are quietly getting right.
Deciding Is Not a Privilege, It Is Where the Pressure Goes
The case for one technically deep person carrying accountability for a team's delivery, release, and stakeholder relationships, framed as absorbing pressure rather than controlling ideas, including the failure modes of that arrangement.
Living on the Edge
On early adoption, one-off software, the kind of problems nobody else wants to tackle, and why code is the advantage that compounds.
The Database Is Probably Permanent
Why most teams never replace their primary database engine, and why designing for portability costs more than it returns. Covers stored procedures, views, triggers, DDL tooling, codegen as an ORM alternative, and the generator pattern behind Reepolee.
Localized URLs for Pages, Not for Apps
The two distinct URL strategies for multilingual software: fully localized slugs for content that needs to be indexed and shared, language-agnostic URLs for apps where language is a user property. Covers hreflang, the locale-prefix plus translated-slug hybrid, and the subdomain split for products that are both.
Why Scripting?
Why Reepolee builds with plain TypeScript scripts: they let platform quirks be absorbed into readable code you own, in one place, rather than leaking into configuration, plugins, or setup instructions.
We Make Our App Fail Loudly on Missing Environment Variables
On startup validation, silent fallbacks, and the principle that a process that won't start with bad config is safer than one that runs quietly with it. Covers Bun's env handling and a simple pattern for making misconfiguration impossible to miss.
Light, Dark, Do Both
On implementing light and dark mode correctly - system preference as the default, per-site user override, and why both are needed.