SUPER Architecture Principles

S.U.P.E.R Architecture Principles

S.U.P.E.R is the architecture model used by Spec-Driven Develop to evaluate existing code and guide future changes.

The core idea: write code like building with LEGO. Each brick has one job, a standard interface, a clear direction, runs anywhere, and can be swapped without disturbing the rest of the system.

The Five Principles

Letter	Principle	Meaning
S	Single Purpose	Each module, file, and function should solve one clear problem.
U	Unidirectional Flow	Data and dependencies should flow in one direction, without circular dependencies.
P	Ports over Implementation	Interfaces and data contracts should come before concrete implementations.
E	Environment-Agnostic	Configuration and dependencies should be explicit, portable, and not hardcoded.
R	Replaceable Parts	Components should be replaceable without cascading changes.

S: Single Purpose

Single Purpose means every module has one responsibility. If a module fetches data, computes metrics, renders output, and sends notifications, it should be split.

Healthy pattern:

fetch_data    -> retrieve data
compute       -> transform data
render        -> generate output
notify        -> send notification

Litmus test: if you cannot describe the module's responsibility in one sentence, it probably needs decomposition.

U: Unidirectional Flow

Unidirectional Flow means dependencies point in a stable direction. Core logic should not depend on UI, database clients, API clients, or deployment details.

Typical layering:

Infrastructure: API, database, UI
Adapters: transformation and formatting
Core business logic: pure rules and behavior

Core logic should be testable without external services.

P: Ports over Implementation

Ports over Implementation means the boundary matters more than the current implementation.

The workflow favors:

• Explicit input and output contracts.
• Serializable module boundaries.
• JSON files or standard data structures at cross-module seams.
• Schemas or types that make data shape visible.

This lets a project replace a data source, renderer, model, service, or storage layer without rewriting unrelated code.

E: Environment-Agnostic

Environment-Agnostic code can run on another machine or deployment target without editing source files.

The workflow looks for:

• Environment variables or config files instead of hardcoded secrets.
• Explicit dependencies in dependency files.
• No hardcoded local paths.
• Logs to standard output where appropriate.
• Stateless processes when deployment portability matters.

R: Replaceable Parts

Replaceable Parts is the result of the first four principles. If one component can be swapped without touching unrelated modules, the architecture has healthy boundaries.

Examples:

Replacing	Healthy Impact Scope
Data source API	Adapter layer only
Frontend renderer	Rendering layer only
Notification channel	Notification adapter only
Deployment platform	Deployment config only
Programming language	Implementation only, if contracts remain stable

How the Workflow Uses S.U.P.E.R

Spec-Driven Develop applies S.U.P.E.R throughout the workflow:

• Phase 1 rates modules against the five principles.
• Phase 2 uses architecture findings to refine scope.
• Phase 3 annotates each task with S.U.P.E.R design drivers.
• Phase 5 runs a S.U.P.E.R quick check before marking work complete.
• Adaptive control can count S.U.P.E.R stagnation or regression as execution drift.

S.U.P.E.R Quick Check

Use this checklist after each task:

• Does each new module or file have one responsibility?
• Does data flow in one direction?
• Are cross-module inputs and outputs defined?
• Can the code run in another environment without source edits?
• Can the changed component be replaced without ripple effects?
• Did the relevant tests pass?

All pass means the task can proceed. One or two failures mean fix before marking complete. Three or more failures mean the architecture likely needs refactoring.

Related Pages

• Spec-Driven-Develop-Workflow
• Adaptive-Control-and-Drift-Score