stnd.build

Engineering Philosophy

The structural invariants, the laws, and the layered architecture of the Standard Framework.

“A system must be rigid enough to prevent collapse, yet invisible enough to allow life.” — Standard Technical Directives, 2026

The Standard Framework @stnd is engineered as an industrial-grade spec. It borrows its rigor from the structural manuals of the 1970s — such as the NASA or EPA Graphic Standards. It does not suggest; it dictates. It establishes absolute boundaries within which chaos and creativity can safely operate. These are the non-negotiables that keep a one-person framework coherent across years and across agents — every rule here is enforceable by reading the code; several are enforced by scripts.


The Duality: The Grid and The Garden

The architecture is built upon a deliberate duality:

  1. The Standard (stnd.build): The mechanical grid. Unforgiving, mathematically absolute (anchored in the golden ratio φ), and completely modular. It is the sterile laboratory environment where layout, performance, and security rules are enforced without exception.
  2. The Garden (stnd.gd): The organic outcome. A chaotic, living ecosystem where human thought, notes, and communities intertwine.

The Garden can only flourish because the Standard provides an indestructible trellis. If the framework leaks, the garden dies. Therefore, the framework’s architecture is defensive by design.


The Eight Inviolable Laws

The ecosystem operates under eight non-negotiable invariants, enforced across both human developers and autonomous AI agents:

  1. No backward compatibility — Pre-release; deprecated code is deleted, never shimmed. No legacy aliases.
  2. DRY (Don’t Repeat Yourself) — Reuse existing domain models, utilities, and primitives before you write new ones.
  3. Logic-less .astro templates — .astro files hold zero business logic. They render; domain models (modules/core/models/) and actions think.
  4. Vertical slices over horizontal layers — Applications are organized into vertical-slice modules (@modules/). Slices never climb through parent folders with relative paths, and feature modules never import sibling feature modules.
  5. Minimal src/ — All application code lives in modules/. src/ contains only framework integration shims.
  6. Agent Lock — Do not touch lines marked // @agents lock true without explicit human permission.
  7. Fatal Errors — Every fatal error links directly to a documented diagnostic page on stnd.build (/manual/diagnostic/<code-name>).
  8. Build & Secrets — Always verify integrity with pnpm build and pre-push ratchets. Secrets must never live in wrangler.toml (use .dev.vars locally, wrangler secret put in production).

For full technical specifications and code examples, see The Eight Inviolable Laws.


The Layers

APP      (consumer: apps/stnd.gd, apps/stnd.build, apps/reveal…)
   ↑ imports
FEATURE  (capabilities: press, loader, launcher, account…)
   ↑ imports
CORE     (infrastructure: core, modules, server, store)
   ↑ imports
SHARED   (pure: utils, dom, log, styles, fonts, themes)

Code in a given layer may only import from the layers below it — no circular or sideways climbing. Features never import a sibling feature’s logic (the one exception is visual primitives like @stnd/icon and @stnd/ui, meant to be composed). Boundaries are checked mechanically (pnpm boundaries, dependency-cruiser).


Concrete Invariants

Beyond the laws, three implementation choices are load-bearing — not stylistic preferences, but guarantees the rest of the system depends on:

Edge-Native and Stateless

The backend targets Cloudflare’s Edge exclusively (Workers, D1, R2, KV Cache). Connections to the database (Kysely-D1 via Better-Auth) are dynamically bound per-request; Node.js singletons are forbidden, preventing state-leakage between parallel requests across edge nodes. The guarantee: extreme global scalability with near-zero latency.

CSS-First, Zero-JS by Default

UI elements (buttons, badges, inputs) are pure CSS classes mapped by @stnd/styles — not every element wrapped in a JS framework. Components (Svelte/Astro) are reserved for complex state management (dialogs, command palettes) using Svelte 5 runes for surgical DOM updates without VDOM overhead. The guarantee: minimal payload, instant time-to-interactive.

Provide / Inject State Management

Prop-drilling across the Astro Server/Client boundary is an anti-pattern. @stnd/store implements a reactive nanostores registry: modules provide services (provide('user', userStore)) at boot, isolated Svelte islands inject them (inject('user')). The guarantee: Astro Islands stay perfectly agnostic of each other.


The Golden Rule of Naming

A “Universal vs. Unique” philosophy balances developer experience with brand identity:

  1. Technical utilities get industry-standard names. If a package performs a standard technical function, name it the way the industry already does (@stnd/styles, not design; @stnd/ui, not components). This makes the DX invisible and predictable for newcomers.
  2. Unique concepts get a proper name. If a package creates a new experience or product category (Module, Garden), give it a poetic, branded name.

The Lightroom Rule (Documentation)

Information is ordered by frequency of need, not by internal architecture. Lightroom’s develop panel opens with exposure and white balance and ends with camera calibration; documentation does the same:

Cognitive load is a budget; spend it on what the reader came for.


Conclusion for the Auditor

The Standard Framework is not a prototype; it is an industrial tool. It enforces zero technical debt by aggressively purging backward-compatibility shims. It trades developer flexibility for absolute system predictability.

By understanding these constraints, one understands why the system can confidently support 10,000 active instances on a negligible resource footprint. We build the rigid box so that the mind can wander freely inside it.