CtrlK
BlogDocsLog inGet started
Tessl Logo

pantheon-ai/design-principles

Strategic architecture, tactical design, and testable code principles (SOLID, Clean Architecture, Design Patterns, Testable Design)

97

Quality

97%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Overview
Quality
Evals
Security
Files

comp-stable-dependencies.mdclean-architecture/references/

title:
Depend in the Direction of Stability
impact:
HIGH
impactDescription:
prevents unstable components from destabilizing dependents
tags:
comp, stability, dependencies, direction

Depend in the Direction of Stability

Components should depend on components that are more stable than themselves. A stable component (many dependents, few dependencies) should not depend on an unstable component (few dependents, many dependencies).

Incorrect (stable component depends on unstable):

┌─────────────────────────────────────────────────────┐
│                     core-domain                      │
│  (Used by 50 services, should be very stable)       │
│                                                      │
│  import { formatDate } from 'ui-helpers'  // WRONG! │
│  import { sendMetrics } from 'analytics'  // WRONG! │
└──────────────────────┬──────────────────────────────┘
                       │
       ┌───────────────┼───────────────┐
       ▼               ▼               ▼
  ui-helpers      analytics      reporting
  (Changes        (Changes       (Changes
   weekly)         monthly)       often)

# When ui-helpers changes, core-domain might break
# When core-domain breaks, all 50 services break

Correct (depend toward stability):

┌─────────────────────────────────────────────────────┐
│                     core-domain                      │
│  (Used by 50 services, zero external dependencies)  │
│                                                      │
│  - Only depends on language primitives              │
│  - Defines interfaces, not implementations          │
└─────────────────────────────────────────────────────┘
                       ▲
                       │
       ┌───────────────┼───────────────┐
       │               │               │
  ui-helpers      analytics      reporting
  │               │               │
  │               │               │
  ▼               ▼               ▼
┌─────────────────────────────────────────────────────┐
│              external-dependencies                   │
│  (date-fns, axios, lodash - maintained externally)  │
└─────────────────────────────────────────────────────┘

# Unstable components depend on stable core
# Core never breaks due to UI changes

Stability Metric:

Instability = Outgoing Dependencies / (Incoming + Outgoing)
  • I = 0: Maximally stable (many dependents, no dependencies)
  • I = 1: Maximally unstable (no dependents, many dependencies)

Dependencies should flow from high I to low I.

Reference: Clean Architecture - Stable Dependencies Principle

clean-architecture

references

adapt-controller-thin.md

adapt-gateway-abstraction.md

adapt-mapper-translation.md

adapt-presenter-formats.md

bound-boundary-cost-awareness.md

bound-defer-decisions.md

bound-service-internal-architecture.md

comp-common-reuse.md

comp-screaming-architecture.md

comp-stable-dependencies.md

dep-acyclic-dependencies.md

dep-data-crossing-boundaries.md

dep-inward-only.md

dep-no-framework-imports.md

entity-encapsulate-invariants.md

entity-no-persistence-awareness.md

entity-pure-business-rules.md

entity-rich-not-anemic.md

entity-value-objects.md

frame-di-container-edge.md

frame-domain-purity.md

frame-orm-in-infrastructure.md

frame-web-in-infrastructure.md

usecase-explicit-dependencies.md

usecase-input-output-ports.md

usecase-no-presentation-logic.md

usecase-orchestrates-not-implements.md

usecase-single-responsibility.md

usecase-transaction-boundary.md

SKILL.md

tile.json