stnd.build

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:

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  │
└────────────────────────────────────────────────────────┘
  1. Features may import from the Foundation: Any module can freely import models, session state, and contracts from @modules/core.
  2. The Foundation never imports from Features: The Foundation Spine knows nothing about individual feature slices.
  3. No Sibling Imports: modules/writer cannot import from modules/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:

Law #3 and Domain Models

Law #3: .astro files 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:

  1. 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>;
    }
    
  2. 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
      }
    }
    
  3. Why this pattern is invincible:

    • modules/library-immich imports PhotoLibrary from @modules/core (100% legal under Law #4).
    • modules/core has zero lines of Immich code and does not import the Immich module.
    • If Immich changes its API, only modules/library-immich needs to be edited.
    • If a user doesn’t want Immich, removing modules/library-immich breaks 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