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

bound-service-internal-architecture.mdclean-architecture/references/

title:
Services Must Have Internal Clean Architecture
impact:
MEDIUM-HIGH
impactDescription:
microservices don't replace architecture, they require it
tags:
bound, services, microservices, internal

Services Must Have Internal Clean Architecture

Breaking a monolith into microservices doesn't solve architectural problems. Each service still needs internal architecture. Services are a deployment option, not an architecture.

Incorrect (microservices as architecture replacement):

"We use microservices architecture"

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│  order-service  │  │  user-service   │  │ payment-service │
│                 │  │                 │  │                 │
│  routes.js      │  │  routes.js      │  │  routes.js      │
│  database.js    │  │  database.js    │  │  database.js    │
│  helpers.js     │  │  helpers.js     │  │  helpers.js     │
│                 │  │                 │  │                 │
│  (No layers,    │  │  (No layers,    │  │  (No layers,    │
│   no boundaries,│  │   no boundaries,│  │   no boundaries,│
│   just smaller  │  │   just smaller  │  │   just smaller  │
│   messes)       │  │   messes)       │  │   messes)       │
└─────────────────┘  └─────────────────┘  └─────────────────┘

# Result: Distributed monolith
# All the downsides of microservices (network, deployment, consistency)
# None of the benefits (each service still a tangled mess)

Correct (clean architecture within each service):

┌───────────────────────────────────────────────────────────┐
│                      order-service                         │
│  ┌─────────────────────────────────────────────────────┐  │
│  │                      domain/                         │  │
│  │   Order.ts  OrderLine.ts  OrderStatus.ts            │  │
│  └─────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────┐  │
│  │                   application/                       │  │
│  │   PlaceOrderUseCase.ts                               │  │
│  │   ports/                                             │  │
│  │     OrderRepository.ts                               │  │
│  │     PaymentGateway.ts  ← calls payment-service       │  │
│  └─────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────┐  │
│  │                  infrastructure/                     │  │
│  │   PostgresOrderRepository.ts                         │  │
│  │   HttpPaymentGateway.ts  → payment-service API       │  │
│  │   KafkaEventPublisher.ts                             │  │
│  └─────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────┐  │
│  │                   interface/                         │  │
│  │   OrderController.ts                                 │  │
│  │   OrderEventHandler.ts                               │  │
│  └─────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────┘

# Each service has:
# - Domain layer with business rules
# - Application layer with use cases and ports
# - Infrastructure layer implementing ports
# - Clean dependency direction within service

Cross-service communication:

// application/ports/PaymentGateway.ts
interface PaymentGateway {
  charge(amount: Money, method: PaymentMethod): Promise<PaymentResult>
}

// infrastructure/HttpPaymentGateway.ts
class HttpPaymentGateway implements PaymentGateway {
  async charge(amount: Money, method: PaymentMethod): Promise<PaymentResult> {
    // Calls payment-service over HTTP
    // Service boundary is an infrastructure detail
    const response = await fetch('http://payment-service/charge', { ... })
    return this.mapResponse(response)
  }
}

Benefits:

  • Services testable without other services
  • Can extract or merge services without rewriting business logic
  • Network boundaries don't compromise internal architecture

Reference: Clean Architecture - Services: Great and Small

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