Engineering Journal

This document captures the why behind every significant architecture decision in Shurli. Each entry follows a lightweight ADR (Architecture Decision Record) format: what problem we faced, what options we considered, what we chose, and what trade-offs we accepted.

New developers, contributors, and future-us should be able to read this and understand not just what the code does, but why it’s shaped the way it is.

Reading Guide

• ADR-0XX: Core architecture decisions made before the batch system
• ADR-X0Y: Batch-specific decisions (A=reliability, B=code quality, etc.)
• Each ADR is self-contained - read any entry independently
• Entries link to source files and commits where relevant

Sections