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.
.astrofiles serve strictly as layout shells, view templates, and markup orchestrators.- Business rules, state machines, and calculations live in pure TypeScript domain models (
models/) or action handlers (actions/).
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
stnd_lint_markup: Audits HTML and CSS against the Vanilla-First design invariants. Flags arbitrary inline styles, missing responsive prefixes, and unnecessary wrapper divs.- Token Introspection: Enables AI to discover available OKLCH color roles, typography sizes, and layout utilities dynamically.
- 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:
- Architecture & Conventions: In-depth guide to Domain-Driven Design and SOLID inversion in Standard.
- Building a Module: Step-by-step tutorial for authoring your first vertical slice with
index.module.js. - The Unified Hooks System: How modules inject UI components, navigation items, and server middleware without tight coupling.
- AI Agent & MCP Guide: Connecting your local editor or agent workflow to Standard’s MCP server.
- Edge Database & Auth: Setting up Cloudflare D1 SQLite, Better Auth, and session state.