Evolutionary Architecture

Evolutionary Architecture

"An evolutionary architecture supports guided, incremental change as a first principle across multiple dimensions." — Neal Ford, Rebecca Parsons, Pat Kua

Traditional architecture tries to predict the future. Evolutionary architecture accepts that change is inevitable and builds mechanisms to guide it safely.

🎯 Core Concepts

The Three Pillars

┌─────────────────────────────────────────────────────────────┐
│              EVOLUTIONARY ARCHITECTURE                       │
│                                                              │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│   │  Incremental │  │   Fitness   │  │ Appropriate │       │
│   │    Change    │  │  Functions  │  │   Coupling  │       │
│   │              │  │             │  │             │       │
│   │ Deployment   │  │ Automated   │  │ Quantum     │       │
│   │ pipelines    │  │ tests that  │  │ boundaries  │       │
│   │ Feature      │  │ verify      │  │ Team        │       │
│   │ toggles      │  │ architecture│  │ alignment   │       │
│   │              │  │ goals       │  │             │       │
│   └─────────────┘  └─────────────┘  └─────────────┘       │
│                                                              │
│   Change without guidance = chaos                            │
│   Fitness without change = stagnation                        │
│   Coupling without fitness = fragile                         │
└─────────────────────────────────────────────────────────────┘

1️⃣ Fitness Functions

Definition: Automated tests that verify architectural goals and constraints. Like unit tests for architecture.

Types of Fitness Functions

Fitness Function Examples

Example 1: Dependency Direction (Atomic)

Goal: Domain layer must not import infrastructure layer (Clean Architecture).

Go (using import-linter):

# .importlinter
[importlinter:contract:clean-architecture]
name = Domain does not depend on Infrastructure
type = forbidden
source_modules =
    myproject.domain
forbidden_modules =
    myproject.infrastructure
    myproject.adapter

Python (using import-linter):

[importlinter:contract:domain-independence]
name = Domain layer is independent
type = forbidden
source_modules =
    myproject.domain
forbidden_modules =
    myproject.infrastructure
    myproject.adapters

Example 2: API Latency (Holistic)

Goal: 95th percentile API response time < 200ms.

# test/fitness/test_api_latency.py
import pytest
from locust import HttpUser, task, between

class APILatencyFitness:
    def test_p95_latency(self):
        """95th percentile API latency must be < 200ms"""
        result = run_load_test(
            endpoint="/api/v1/orders",
            duration="5m",
            users=100
        )
        assert result.p95_latency_ms < 200, \
            f"P95 latency {result.p95_latency_ms}ms exceeds 200ms threshold"

    def test_error_rate(self):
        """Error rate must be < 0.1%"""
        assert result.error_rate < 0.001, \
            f"Error rate {result.error_rate} exceeds 0.1% threshold"

Example 3: No Circular Dependencies (Triggered)

Go:

# .github/workflows/fitness.yml
- name: Check circular dependencies
  run: |
    go install github.com/fzipp/gocyclo@latest
    gocyclo -over 15 ./... || exit 1

- name: Check architecture boundaries
  run: |
    pip install import-linter
    lint-imports

JavaScript/TypeScript:

# package.json
{
  "scripts": {
    "fitness:deps": "madge --circular src/",
    "fitness:coverage": "jest --coverage --coverageThreshold='{\"global\":{\"branches\":80}}'"
  }
}

Example 4: Database Migration Safety (Triggered)

# test/fitness/test_migrations.py
class MigrationFitness:
    def test_no_destructive_migrations(self):
        """Migrations must not drop columns without deprecation period"""
        for migration in get_pending_migrations():
            assert not migration.has_drop_column(), \
                f"Migration {migration.name} drops column. Use deprecation first."

    def test_migration_runtime(self):
        """Migrations must complete in < 5 seconds"""
        for migration in get_pending_migrations():
            runtime = estimate_migration_runtime(migration)
            assert runtime < 5, \
                f"Migration {migration.name} estimated at {runtime}s. Break into smaller migrations."

2️⃣ Architecture Testing

Testing Architectural Characteristics ("-ilities")

CI/CD Integration

# .github/workflows/architecture-fitness.yml
name: Architecture Fitness

on: [pull_request]

jobs:
  fitness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # 1. Dependency direction
      - name: Check Clean Architecture boundaries
        run: |
          pip install import-linter
          lint-imports

      # 2. Cyclomatic complexity
      - name: Check complexity
        run: |
          go install github.com/fzipp/gocyclo@latest
          gocyclo -over 15 ./...

      # 3. No secrets
      - name: Scan for secrets
        uses: trufflesecurity/trufflehog@main
        with:
          path: ./
          base: main

      # 4. API latency (if changes touch API)
      - name: Performance regression test
        if: contains(github.event.pull_request.changed_files, 'api/')
        run: |
          docker-compose up -d
          k6 run --summary-trend-stats="avg,min,med,max,p(95),p(99)" tests/performance/api.js

      # 5. Coverage gate
      - name: Test coverage
        run: |
          go test -coverprofile=coverage.out ./...
          go tool cover -func=coverage.out | grep total | awk '{print $3}' | sed 's/%//' | awk '{if ($1 < 80) exit 1}'

3️⃣ Strangler Fig Pattern

Definition: Gradually replace a legacy system by building new functionality around it, routing traffic incrementally, until the old system is "strangled" and can be removed.

Why Strangler Fig?

Implementation Strategy

Phase 1: ROUTE          Phase 2: EXTRACT        Phase 3: STRANGLE
┌─────────────┐        ┌─────────────┐        ┌─────────────┐
│   Client    │        │   Client    │        │   Client    │
└──────┬──────┘        └──────┬──────┘        └──────┬──────┘
       │                      │                      │
       ▼                      ▼                      ▼
┌─────────────┐        ┌─────────────┐        ┌─────────────┐
│  Facade/    │        │  Facade/    │        │   New       │
│  Router     │        │  Router     │        │   Service   │
│  (new)      │        │  (new)      │        │  (full)     │
└──────┬──────┘        └──────┬──────┘        └─────────────┘
       │                      │
       ▼                      ▼
┌─────────────┐        ┌─────────────┐
│   Legacy    │        │   Legacy    │
│   System    │        │   System    │
│  (monolith) │        │  (partial)  │
└─────────────┘        └──────┬──────┘
                              │
                              ▼
                        ┌─────────────┐
                        │   New       │
                        │   Service   │
                        │  (extracted)│
                        └─────────────┘

Routing Strategies

Example: Feature Flag Router

type OrderRouter struct {
    legacyService *LegacyOrderService
    newService    *NewOrderService
    flags         FeatureFlagClient
}

func (r *OrderRouter) GetOrder(ctx context.Context, id uuid.UUID) (*Order, error) {
    // Check if this user should use new service
    if r.flags.IsEnabled(ctx, "new-order-service", getUserID(ctx)) {
        return r.newService.GetOrder(ctx, id)
    }
    return r.legacyService.GetOrder(ctx, id)
}

func (r *OrderRouter) CreateOrder(ctx context.Context, cmd CreateOrderCommand) (*Order, error) {
    // All new orders go to new service
    return r.newService.CreateOrder(ctx, cmd)
}

4️⃣ Architectural Dimensions

Identify which dimensions of your architecture need to evolve:

┌─────────────────────────────────────────────────────────────┐
│                    ARCHITECTURAL DIMENSIONS                  │
│                                                              │
│  Technical          Business           Operational          │
│  ─────────          ────────           ───────────          │
│  • Tech stack       • Features         • Scalability        │
│  • Data storage     • Domain model     • Performance        │
│  • Communication    • Business rules   • Security           │
│  • Integration      • Regulations      • Observability      │
│                                                              │
│  Each dimension needs:                                       │
│  1. Current state measurement                                │
│  2. Target state definition                                  │
│  3. Fitness function to guard it                             │
└─────────────────────────────────────────────────────────────┘

Dimension Example: Scalability

5️⃣ Conway's Law & Team Alignment

"Organizations which design systems are constrained to produce designs which are copies of the communication structures of these organizations." — Melvin Conway

Implications

Team Topologies Mapping

🚫 Evolutionary Anti-Patterns

📋 Evolutionary Architecture Checklist

When starting a new project:

• Identified 3-5 critical architectural dimensions
• Defined fitness functions for each dimension
• Integrated fitness functions into CI/CD
• Chose appropriate coupling (monolith → modular → microservices)
• Aligned team structure with architecture boundaries
• Planned strangler fig path for legacy integration (if applicable)
• Documented architecture decisions in ADRs

🔗 Integration with Other Skills

📚 References

• Evolutionary Architecture — Neal Ford, Rebecca Parsons, Pat Kua (O'Reilly)
• Software Architecture: The Hard Parts — Ford, Richards, Sadalage, Dehghani
• Fitness Function-Driven Development — ThoughtWorks
• Strangler Fig Pattern — Martin Fowler
• Team Topologies — Skelton, Pais
• Conway's Law — Martin Fowler