4.2 Code Standards

The Standard Framework is built on a set of non-negotiable architectural principles. These rules ensure that the codebase remains clean, predictable, and maintainable as it scales.

1. Architectural Layers & Import Hierarchy

Standard enforces a strict, multi-tiered dependency model. Code in a given layer is only allowed to import modules from the layers below it. No circular or sideways climbing is permitted.

+-------------------------------------------------------------+
| APP Layer (Apps & Boots)                                    |
|   ↳ e.g. [apps/stnd.gd](../../../../apps/stnd.gd/README.md), apps/ade                             |
+-------------------------------------------------------------+
                            ↓ imports
+-------------------------------------------------------------+
| FEATURE Layer (Capabilities)                                |
|   ↳ [@stnd/press](../../../../packages/press/README.md), [@stnd/client](../../../../packages/client/README.md), [@stnd/ui](../../../../packages/ui/README.md), [@stnd/layout](../../../../packages/layout/README.md)       |
+-------------------------------------------------------------+
                            ↓ imports
+-------------------------------------------------------------+
| CORE Layer (Infrastructure Frame)                           |
|   ↳ [@stnd/server](../../../../packages/server/README.md), [@stnd/core](../../../../packages/core/README.md), [@stnd/modules](../../../../packages/modules/README.md)                 |
+-------------------------------------------------------------+
                            ↓ imports
+-------------------------------------------------------------+
| SHARED Layer (Pure utilities, design tokens, & fonts)       |
|   ↳ [@stnd/log](../../../../packages/log/README.md), [@stnd/utils](../../../../packages/utils/README.md), [@stnd/styles](../../../../packages/styles/README.md), [@stnd/fonts](../../../../packages/fonts/README.md)       |
+-------------------------------------------------------------+

The Architectural Tiers

1. SHARED Layer (Pure Foundation): 
   • Contains code that has zero opinion and zero side-effects.
   • Examples: @stnd/log (logging), @stnd/utils (pure strings/dates/math functions), and @stnd/styles (the CSS variable design system tokens).
   • Rule: Pure modules must never import anything from layers above them.
2. CORE Layer (Infrastructure Frame): 
   • Provides the frame for running applications.
   • Examples: @stnd/server (orchestrating environment, visitor contexts, and model caches) and @stnd/core (the Astro integration engine).
   • Rule: Core modules may only import from the SHARED layer.
3. FEATURE Layer (Capabilities): 
   • Represents decoupled features that add specific behaviors.
   • Examples: @stnd/press (markdown parsing), @stnd/client (shortcuts, gestures), and @stnd/ui (components).
   • Rule: Features never import another feature’s logic. (The only exception is visual primitives like @stnd/icon and @stnd/ui components meant to be composed).
4. APP Layer (Consumer): 
   • The final rendering sites. Includes Astro sites and companion native client packages.

2. The Golden Rule of Naming

We follow a “Universal vs. Unique” naming philosophy to balance developer experience (DX) with brand identity:

1. Technical Utilities? Use Industry Standards.
   If a package performs a standard technical function, use the universal industry name (e.g., @stnd/styles instead of design, @stnd/ui instead of components). This makes the DX invisible and predictable for newcomers.
2. Unique Concepts? Give it a Proper Name.
   If a package creates a new experience or unique product category (e.g., Module, Garden), give it a poetic, branded name.

3. Core Development Mandates

1. Vertical Slice Architecture

All application logic follows the vertical slice pattern. Features are encapsulated in self-contained Modules inside modules/.

• A module folder contains its own routes, layouts, models, and styles.
• The Litmus Test: If you delete a module folder, the site must not crash; the feature simply disappears.

2. Logic-less Templates

.astro files must contain zero business logic.

• They are reserved for template rendering and model instance usage.
• All server-side logic, database queries, and data transformations live in Model classes or Helper files.

3. Zero Backward Compatibility

We prioritize clean architecture over legacy support.

• No shims, no legacy aliases, no “workaround” shims for old code.
• If code is obsolete, it is removed immediately.

4. Minimal src/ Folder

In a Standard application, the src/ folder is kept to an absolute minimum (only Astro-mandated files).

• 100% of application code lives within modules. This enforces strict boundaries and makes the project structure navigable at a glance.

5. No Assumption Bleed

A shared framework package must never encode assumptions that are only true for one specific app.

• Bad: Having @stnd/press check if the origin is standard.garden to rewrite a URL.
• Good: Passing an application configuration object to configure rewrite behaviors.
• Litmus Test: Would this code do the wrong thing if a different app with a different content source imported it unchanged? If yes, the per-source part belongs in config, not in the shared path. Fail loud on ambiguity.