stnd.build

The Builder — Application Architecture & Edge Blueprint

The master architecture blueprint for building modular, zero-debt web applications on Cloudflare Edge with Standard.

Standard is built from the ground up to solve a fundamental problem: how does a solo builder or a focused team develop, deploy, and maintain ambitious full-stack applications for years without collapsing under architectural rot and technical debt?

Traditional web frameworks offer either blank canvases that quickly devolve into tangled spaghetti code, or heavyweight enterprise scaffolding with endless boilerplate.

Standard takes a radical third path: Strict architectural laws enforced at compile time, vertical-slice isolation, logic-free views, native Cloudflare Edge runtime, and first-class AI agent integration (MCP).


1. The Four Invariant Layers

Every file, module, and package in Standard belongs to one of four strictly ordered layers. Dependencies flow strictly downward — an inner layer may never import or depend on an outer layer.

flowchart TD
  L4["Layer 4: Application Feature Modules (modules/*, routes, actions, hooks)"]
  L3["Layer 3: UI Primitives & Layout Shells (@stnd/ui, @stnd/layout)"]
  L2["Layer 2: Pure Domain Logic & Models (parsers, validators, calculations, store)"]
  L1["Layer 1: Design Tokens & Typography Foundations (@stnd/styles, OKLCH, 1rlh)"]

  L4 --> L3
  L4 --> L2
  L3 --> L1
  L2 --> L1

Layer 1: Design Tokens & Foundations (@stnd/styles)

The mathematical ground truth. OKLCH color spaces, the Silver Ratio (1.414) typography scale, and 1rlh vertical rhythm increments. No raw hex codes, arbitrary pixels, or ad-hoc magic numbers.

Layer 2: Pure Domain Logic & Entities

Business rules, transformations, parsers, and validation schemas. Pure TypeScript and JavaScript functions. Layer 2 contains zero presentation code, zero HTML, and zero framework-specific UI bindings.

Layer 3: Primitives & Layout Shells (@stnd/ui, @stnd/layout)

Accessible, headless, and semantic UI components (<Dialog />, <Tabs />, <Combobox />, <Window />). Primitives consume only Layer 1 tokens and standard props. They contain zero business logic, zero database calls, and zero domain assumptions.

Layer 4: Vertical-Slice Application Modules (modules/*)

Feature code organized in self-contained slices. Each module orchestrates routes, actions, and layouts for a specific user capability.


2. Vertical Slice Architecture (VSA)

Traditional Model-View-Controller (MVC) structures group code horizontally by file type (controllers/, views/, models/). When a feature evolves or is deprecated, developers must hunt through multiple global directories, creating invisible couplings and fear of deletion.

Standard organizes code vertically around discrete capabilities in ./modules/<feature>/:

apps/my-app/modules/billing/
├── index.module.js        # Manifest (routes, actions, hooks, declaration)
├── components/            # UI components specific to billing
├── actions/               # Server-side mutation handlers (e.g. checkout.ts)
├── models/                # Domain models & validation (e.g. Invoice.ts)
└── styles/                # Feature-scoped stylesheets

The Litmus Test of a Vertical Slice

If you delete modules/billing/, the billing capability vanishes completely, but the rest of the application continues to build and run with zero errors.


3. The Foundation Spine & Dependency Flow

To guarantee absolute modularity, Standard enforces Law #4:

Law #4 (Inviolable): Sibling feature modules must never import each other directly. Feature modules communicate only through the Foundation Spine (modules/core/), framework packages (@stnd/*), or declarative Hooks.

flowchart TD
  subgraph Slices ["Feature Slices (Isolated)"]
    F1["modules/billing/"]
    F2["modules/analytics/"]
    F3["modules/editor/"]
  end

  subgraph Core ["Foundation Spine"]
    C["modules/core/ (role: 'foundation')<br/>User Session, Root Shell, Auth Context"]
  end

  subgraph Framework ["Standard Framework"]
    FW["@stnd/core · @stnd/ui · @stnd/styles"]
  end

  F1 -.->|Forbidden| F2
  F2 -.->|Forbidden| F3
  F1 --> C
  F2 --> C
  F3 --> C
  C --> FW

The Foundation Spine (role: "foundation")

Shared application state, user session context, navigation bars, and root database bindings reside exclusively in the Foundation Spine (typically modules/core/):

// modules/core/index.module.js
export default {
  id: "core",
  role: "foundation", // Declares this module as the architectural spine
  name: "Core Spine",
  description: "Global session state, root layout shell, and shared contracts."
};

4. Law #3: Logic-Free Views

Views (.astro and .svelte files) must hold no business logic, no data parsing, and no SQL queries.

Anti-Pattern: Business Logic in the View

---
// ❌ WRONG: Database queries, price calculations, and mutations in .astro
import { db } from "../db";
const rawOrders = await db.query("SELECT * FROM orders WHERE user_id = ?", [Astro.locals.user.id]);
const total = rawOrders.reduce((sum, o) => sum + (o.price * 1.15), 0);
---
<main>Total: {total}</main>

Standard Pattern: Pure View Orchestration

---
// ✅ CORRECT: View delegates entirely to domain models and actions
import { OrderSummary } from "@modules/billing/models/OrderSummary";
import { getCustomerOrders } from "@modules/billing/actions/orders";

const orders = await getCustomerOrders(Astro.locals.session);
const summary = OrderSummary.fromOrders(orders);
---
<main>Total: {summary.formattedTotal}</main>

5. Cloudflare Edge Runtime Architecture

Standard applications are engineered for the modern Edge, running natively on Cloudflare Workers and Pages with near-instant cold starts (≤5ms) worldwide.

Primitive Role Access in Standard
Edge Compute Zero-cold-start compute running on V8 isolates Standard routes (routes/*.astro, API endpoints)
Cloudflare D1 Serverless relational SQLite at the edge Astro.locals.runtime.env.DB
Cloudflare KV Sub-millisecond global key-value store for sessions & cache Astro.locals.runtime.env.KV
Cloudflare R2 S3-compatible zero-egress blob storage for user media Astro.locals.runtime.env.BUCKET
Cloudflare Images On-the-fly optical resizing, AVIF/WebP encoding <CfImage /> primitive

Standard eliminates Node.js-specific dependencies (fs, child_process, heavy native binaries) in favor of web standards (fetch, Request, Response, ReadableStream, crypto.subtle).


6. The Agent-First Superpower (@stnd/mcp)

Standard is designed from day one for human-AI pair programming. Rather than relying on guesswork, AI agents (Antigravity, Claude Desktop, Cursor) communicate with the monorepo through the built-in Model Context Protocol (MCP) server at /api/mcp.

sequenceDiagram
  autonumber
  actor User as Builder (Human)
  participant Agent as AI Coding Agent
  participant MCP as Standard MCP (/api/mcp)
  participant Code as Monorepo (/modules)

  User->>Agent: "Add an export modal to the analytics slice"
  Agent->>MCP: Call tool: stnd_lint_markup
  MCP-->>Agent: Validation rules & token recommendations
  Agent->>Code: Writes module/analytics/views/ExportModal.svelte
  Agent->>MCP: Run diagnostics
  MCP-->>Agent: 0 violations, all layers valid
  Agent-->>User: "Export modal implemented and verified"

Integrated MCP Capabilities

  1. stnd_lint_markup: Audits HTML and CSS against the Vanilla-First design invariants. Flags arbitrary inline styles, missing responsive prefixes, and unnecessary wrapper divs.
  2. Token Introspection: Enables AI to discover available OKLCH color roles, typography sizes, and layout utilities dynamically.
  3. Automated Diagnostic Codes: When an architectural rule is violated (e.g., a feature module importing a sibling feature), the compiler triggers a self-documenting diagnostic URL (e.g. ERR_FOUNDATION_IMPORTS_FEATURE) with exact remedy steps.

7. The Eight Inviolable Laws Scorecard

Before deploying any feature or committing code, verify your implementation against the Eight Inviolable Laws:

# Law Core Invariant Verification Check
1 No backward compatibility Pre-release framework; no shims, no legacy aliases. Grep for deprecated utility names or shims.
2 DRY Reuse primitives and tokens before writing bespoke styles. Check @stnd/ui and @stnd/styles first.
3 Zero logic in .astro View files serve purely as presentation orchestrators. Business logic resides in models/ or actions/.
4 Vertical-slice isolation Feature modules must never cross-import sibling modules. Enforced automatically by depcruise during build.
5 Minimal src/ Application code lives in @modules/, never loose in src/. src/pages only forwards to @modules/.
6 Agent Lock Never modify lines marked // @agents lock true. Guard files preserved.
7 Self-Documenting Errors Every fatal diagnostic documents an explanation page. Registered in @stnd/diagnostics.
8 Hermetic Secrets Secrets live in .dev.vars or Cloudflare Secrets, never in wrangler.toml. Zero credentials in version control.

8. Where to Go Next

Explore the specialized guides for deep technical specifications: