Architecture & Conventions
Vertical Slice Architecture, Domain-Driven Design, SOLID Dependency Inversion, and why the Foundation Spine prevents spaghetti code.
Every architectural choice in the Standard framework exists to solve a single problem: keeping codebases clean, maintainable, and modular over years of continuous solo development.
This guide explains how Standard combines Vertical Slice Architecture (VSA), Domain-Driven Design (DDD), and the SOLID Dependency Inversion Principle into a pragmatic development workflow that prevents technical debt and architectural rot.
1. The Core Dilemma: Why Classic MVC Degrades
In traditional Model-View-Controller (MVC) and three-tier layered architectures, code is organized horizontally by technical file type:
src/
├── controllers/ # All controllers for every feature
├── models/ # All database models for every feature
└── views/ # All templates and UI for every feature
This horizontal organization works well in small tutorials, but quickly degenerates in production applications:
- High coupling across distance: Adding or altering a single feature requires touching files scattered across three or four directories.
- The Spaghetti Effect: Over time, controller A starts importing helper B from controller C. A model starts reaching into another model’s private helper.
- Fear of Deletion: When a feature is retired, removing it is terrifying because its tentacles are invisibly entangled across global folders. Developers end up leaving dead code out of fear.
Standard replaces horizontal layering with Vertical Slices.
2. Vertical Slice Architecture (VSA)
In Standard, applications are organized vertically around user features, not technical categories. Every feature is a self-contained slice located in modules/<feature-name>/:
apps/reveal/modules/culling/
├── index.module.js # Manifest (routes, actions, shortcuts, hooks)
├── components/ # UI components specific to photo culling
├── views/ # Full view layouts (e.g., CullingWorkspace.svelte)
├── actions/ # Server and client mutations (e.g., flagAsset.ts)
└── styles/ # Scoped styles for the culling experience
The Litmus Test of a Vertical Slice
If you delete
modules/culling/, the photo culling feature disappears completely, but the application continues to build and run without errors.
To guarantee this independence, 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.
3. The Foundation Spine (role: "foundation")
If feature modules are completely isolated and cannot import from each other, how do they share core application state and data models?
The answer is the Foundation Spine (by convention located at modules/core/ and declared with role: "foundation" in its manifest):
// modules/core/index.module.js
export default {
id: "core",
role: "foundation", // Declares this module as the architectural spine
name: "Application Spine",
description: "Domain models, session context, and root application shell."
};
Dependency Flow (Strictly Unidirectional)
Dependencies flow strictly in one direction:
┌────────────────────────────────────────────────────────┐
│ Feature Modules (modules/writer, modules/culling...) │
│ Isolated vertical slices — never import each other. │
└──────────────────────────┬─────────────────────────────┘
│ imports from
┌──────────────────────────▼─────────────────────────────┐
│ Foundation Spine (modules/core — role: "foundation") │
│ Domain models, session auth, provider contracts. │
│ NEVER imports from any feature module. │
└──────────────────────────┬─────────────────────────────┘
│ imports from
┌──────────────────────────▼─────────────────────────────┐
│ Standard Framework Packages (@stnd/*) │
│ Universal primitives: @stnd/ui, @stnd/layout, styles │
└────────────────────────────────────────────────────────┘
- Features may import from the Foundation: Any module can freely import models, session state, and contracts from
@modules/core. - The Foundation never imports from Features: The Foundation Spine knows nothing about individual feature slices.
- No Sibling Imports:
modules/writercannot import frommodules/launcher. If both need a concept, that concept belongs in the Foundation Spine.
4. Domain-Driven Design (DDD): Entities in the Core
Every substantive application has a small number of core domain entities that represent the reality of the problem space:
- In Standard Garden (
stnd.gd), the domain entities areNote,User, andGarden. - In Reveal (
reveal.photos), the domain entities areAsset,Album, andPhotoLibrary. - In Avelo (
avelo-stat), the domain entities areStation,Trip, andSeason.
Law #3 and Domain Models
Law #3:
.astrofiles must hold no business logic. Business logic lives in domain models (modules/core/models/) or actions (actions.ts). Core application entities must be strongly typed domain models in the foundation spine.
Because these domain models represent the shared business truth of the application, their classes and TypeScript interfaces belong in modules/core/models/:
// modules/core/models/Note.ts
export interface NoteMetadata {
title: string;
slug: string;
publishedAt?: Date;
tags: string[];
}
export class Note {
constructor(public readonly id: string, public metadata: NoteMetadata) {}
get isPublished(): boolean {
return !!this.metadata.publishedAt;
}
}
Now, every vertical slice (modules/writer, modules/cite, modules/search) can import Note from @modules/core/models/Note.js. They all speak the exact same strongly typed language without having to depend on one another.
5. SOLID & The Dependency Inversion Principle (The Provider Pattern)
What happens when a domain entity can have multiple external backends or storage drivers?
Consider Reveal, a local-first photo management application. Users can connect photos stored on their local hard drive, in an Immich self-hosted server, or from Apple Photos.
The Anti-Pattern (Violating SOLID)
If you put Immich API code and Apple Photos scripts directly into modules/core, the core becomes bloated with third-party dependencies and unstable vendor APIs.
The Standard Pattern: Dependency Inversion (D in SOLID)
Instead of the core depending on concrete drivers, concrete drivers depend on abstractions defined in the core:
-
Define the pure contract in the Foundation Spine:
// modules/core/models/Library.ts import type { Asset } from "./Asset.js"; export interface PhotoLibrary { readonly id: string; readonly title: string; scan(): Promise<Asset[]>; getAsset(id: string): Promise<Asset | null>; } -
Implement each driver in an isolated feature module:
// modules/library-immich/driver.ts import type { PhotoLibrary } from "@modules/core/models/Library.js"; import type { Asset } from "@modules/core/models/Asset.js"; export class ImmichLibrary implements PhotoLibrary { readonly id = "immich"; readonly title = "Immich Server"; async scan(): Promise<Asset[]> { // Immich-specific HTTP calls here } async getAsset(id: string): Promise<Asset | null> { // Immich-specific fetch } } -
Why this pattern is invincible:
modules/library-immichimportsPhotoLibraryfrom@modules/core(100% legal under Law #4).modules/corehas zero lines of Immich code and does not import the Immich module.- If Immich changes its API, only
modules/library-immichneeds to be edited. - If a user doesn’t want Immich, removing
modules/library-immichbreaks nothing else.
6. How Slices Coordinate: Hooks, Actions & Events
When feature modules need to coordinate without importing each other, they use three decoupling mechanisms:
| Communication Goal | Mechanism | Example |
|---|---|---|
| Injecting UI into shared layouts | Declarative Module Hooks | Registering an action button into stnd:base or launcher:action via index.module.js |
| Triggering behavior across components | Vanilla DOM Data Attributes & Events | Toggling a panel via <button data-panel-toggle="sidebar"> or listening to window.addEventListener("stnd:panel-change") |
| Navigating or mutating state | Standard Actions & URL parameters | Calling an action through Astro actions or setting URL query state (?q=search) |
7. The Decision Matrix: Where Does My Code Belong?
Whenever you write a new class, component, or utility, use this checklist to decide its location:
| Type of Code | Example | Destination |
|---|---|---|
| Feature-specific UI & workflows | A slideshow view, a photo culling grid, an article editor | modules/<feature>/ |
| Core domain models | Note, Asset, User, Library interfaces |
modules/core/models/ |
| Application session & root state | Current authenticated user, database connection binding | modules/core/session.ts |
| Provider / Connector drivers | Immich connector, Apple Photos bridge, Stripe webhook slice | modules/<provider-name>/ |
| Universal UI & style primitives | Button, Card, Accordion, color tokens, layout primitives | @stnd/ui, @stnd/layout, @stnd/styles |
| Framework utility functions | Slugification, date formatting, DOM event helpers | @stnd/utils, @stnd/dom |