Skip to content

dbrijesh/eac

BranchesTags

Repository files navigation

Enterprise Architecture-as-Code (EAaC)

A comprehensive system for defining, analyzing, and managing enterprise architecture through declarative markup language with automated dependency resolution and change propagation.

🎯 Overview

EAaC enables you to:

  • Define complete enterprise architecture in YAML with explicit dependencies
  • Analyze impact of changes across all tiers and domains
  • Generate automated update plans with rollback procedures
  • Validate architecture consistency and dependencies
  • Propagate updates automatically through dependent systems

🏗️ Architecture Domains

The system supports six core architecture domains:

  1. Infrastructure - Compute, networking, storage, orchestration
  2. Application - Microservices, APIs, frontends, business logic
  3. Data - Databases, caches, message queues, data lakes
  4. Security - Identity providers, authentication, authorization
  5. Observability - Monitoring, logging, tracing, alerting
  6. Workflow - CI/CD pipelines, automation, orchestration

🎨 3-Tier Architecture Support

The system explicitly models the 3-tier application pattern:

┌─────────────────────────────────────────┐
│ TIER 1: Presentation Layer             │
│ (Frontend - React, React Native)       │
└─────────────────────────────────────────┘
           ↓ HTTP/REST calls ↓
┌─────────────────────────────────────────┐
│ TIER 1.5: API Gateway Layer             │
│ (Kong - Routing, Auth, Rate Limiting)  │
└─────────────────────────────────────────┘
           ↓ Routes to services ↓
┌─────────────────────────────────────────┐
│ TIER 2: Application/Business Logic      │
│ (Spring Boot, FastAPI, Go, Node.js)    │
└─────────────────────────────────────────┘
           ↓ Uses ORM/Connection Pool ↓
┌─────────────────────────────────────────┐
│ TIER 3: Data Access Layer               │
│ (Hibernate, HikariCP)                   │
└─────────────────────────────────────────┘
           ↓ Database queries ↓
┌─────────────────────────────────────────┐
│ Infrastructure: Databases & Caches      │
│ (PostgreSQL, Redis, Kafka)              │
└─────────────────────────────────────────┘

📦 Installation

# Clone repository
git clone <repository-url>
cd eac

# Install dependencies
pip install -r requirements.txt

# Verify installation
python -m src.cli examples/enterprise-platform.yaml validate

🚀 Quick Start

1. Validate Architecture

python -m src.cli examples/enterprise-platform.yaml validate

2. View Architecture Summary

python -m src.cli examples/enterprise-platform.yaml summary

3. List Components by Tier

# List all application tier components
python -m src.cli examples/enterprise-platform.yaml list --tier application

# List all infrastructure domain components
python -m src.cli examples/enterprise-platform.yaml list --domain infrastructure

4. Show Component Details

python -m src.cli examples/enterprise-platform.yaml show svc-business-logic

5. Analyze Impact of Changes

# Analyze what's affected if PostgreSQL changes
python -m src.cli examples/enterprise-platform.yaml impact db-primary-postgres --version 16.1

6. Generate Update Plan

# Generate plan to update Spring Boot version
python -m src.cli examples/enterprise-platform.yaml update svc-business-logic 3.2.1

7. View Dependency Tree

python -m src.cli examples/enterprise-platform.yaml deps svc-business-logic

🧪 Running the Demo

The demo script shows three comprehensive scenarios:

python demo.py

Scenario 1: Java Runtime Update

  • Updates Java from 17 to 21 in business logic service
  • Shows impact on Data Access Layer and application tier
  • Demonstrates zero-downtime rolling update

Scenario 2: PostgreSQL Major Version Upgrade

  • Upgrades PostgreSQL from 15.2 to 16.1
  • Shows cascade through all database-dependent services
  • Demonstrates phased deployment with standby replica

Scenario 3: Spring Boot Framework Upgrade

  • Updates Spring Boot from 3.1.5 to 3.2.1
  • Shows cross-tier impact analysis
  • Demonstrates API compatibility checking

📝 Architecture Definition Format

Basic Structure

architecture:
  version: "1.0.0"
  name: "My Architecture"
  metadata:
    organization: "my-org"
    environment: "production"
    created: "2025-01-15"
    modified: "2025-01-15"

  domains:
    application:
      components:
        - id: "my-service"
          name: "My Service"
          type: "microservice"
          framework: "spring-boot"
          version: "3.1.5"
          runtime: "java"
          runtime_version: "21"
          configuration:
            replicas: 3
          dependencies:
            - id: "my-database"
              type: "hard"
              constraint: ">=15.0"
          metadata:
            tier: "application"
            critical: true

Component Types

Infrastructure:

  • compute, container-orchestration, networking, storage, load-balancer

Application:

  • microservice, api-gateway, frontend-application, mobile-application, data-access-service

Data:

  • relational-database, nosql-database, cache, message-queue, data-warehouse

Security:

  • identity-provider, api-security, secrets-manager

Observability:

  • metrics-collector, log-aggregator, distributed-tracing, apm

Dependency Types

  • hard - Required dependency (component cannot function without it)
  • soft - Optional dependency (reduced functionality)
  • deployment - Deployment target (e.g., Kubernetes cluster)
  • monitoring - Observability dependency
  • backend-routing - API Gateway routing to backend services
  • authentication - Authentication provider
  • caching - Cache dependency
  • event-streaming - Message queue/streaming

Version Constraints

# Exact version
constraint: "=3.1.5"

# Range
constraint: ">=3.1.0,<4.0.0"

# Compatible (same major)
constraint: "^3.1.5"  # Allows 3.x.x

# Approximately equivalent (same minor)
constraint: "~3.1.5"  # Allows 3.1.x

🔧 Core Features

1. Dependency Resolution

The system builds a complete dependency graph and:

  • Identifies direct and transitive dependencies
  • Detects circular dependencies
  • Calculates topological ordering
  • Finds critical paths

2. Version Constraint Checking

Semantic versioning with:

  • Range constraints (>=1.0.0, <2.0.0)
  • Compatibility constraints (^1.2.3)
  • Breaking change detection
  • Upgrade path suggestions

3. Impact Analysis

When a component changes:

  • Identifies all affected components
  • Shows domain-level impacts
  • Detects breaking changes
  • Verifies version compatibility

4. Update Plan Generation

Automatically generates:

  • Step-by-step update sequence
  • Testing requirements
  • Rollback procedures
  • Downtime estimates
  • Warnings for critical components

5. Cross-Tier Propagation

Updates cascade correctly through tiers:

  • Tier 3 (Data Access) → Tier 2 (Application)
  • Tier 2 (Application) → Tier 1.5 (API Gateway)
  • Tier 1.5 (API Gateway) → Tier 1 (Presentation)

📊 Example Use Cases

Update Database Version

# Analyze impact
python -m src.cli examples/enterprise-platform.yaml impact db-primary-postgres --version 16.1

# Generate update plan
python -m src.cli examples/enterprise-platform.yaml update db-primary-postgres 16.1

Result: Shows all services affected, required JDBC driver updates, migration steps

Upgrade Framework

# Update Spring Boot in business logic service
python -m src.cli examples/enterprise-platform.yaml update svc-business-logic 3.2.1

Result: Identifies Data Access Layer compatibility, API contract checks, testing requirements

Analyze Critical Components

# Show what depends on Kubernetes cluster
python -m src.cli examples/enterprise-platform.yaml show compute-k8s-prod

Result: Lists all services deployed to the cluster

🎯 Update Plan Example

When you generate an update plan, you get:

📝 Generating update plan...
   Component: Business Logic Service
   Current version: 3.1.5
   Target version: 3.2.1

⚠️  Warnings:
   ⚠️  CRITICAL COMPONENT - Extra caution required

📦 Affected components (3):
   • Data Access Layer (Hibernate 6.3.1)
   • API Gateway Service (Kong 3.2.1)
   • Web Frontend Application (React 18.2.0)

✅ Zero-downtime deployment possible

📋 Update Sequence:
=== PHASE 1: PREPARATION ===
1. Review change log: spring-boot 3.1.5 -> 3.2.1
2. Backup current configuration for Business Logic Service
3. Verify java 21 compatibility
4. Verify compatibility with 8 dependencies

=== PHASE 2: UPDATE TARGET COMPONENT ===
1. Update Business Logic Service configuration
   Tier: application
2. Update build configuration (maven)
3. Update dependencies in package manifest
4. Run build and unit tests
5. Deploy using rolling update strategy (3 replicas)
6. Verify Business Logic Service starts successfully
7. Run smoke tests

=== PHASE 3: UPDATE AFFECTED COMPONENTS ===
1. Update Data Access Layer (svc-data-access-layer)
   - Verify compatibility with Business Logic Service 3.2.1
   - Rebuild/redeploy if necessary
   - Run integration tests

🧪 Testing Requirements:
   • Unit Tests: Business Logic Service
   • Integration Tests: 3 affected components
   • Business logic tests
   • API contract tests
   • Service mesh tests
   • Load/stress testing (CRITICAL COMPONENT)

🔄 Rollback Procedure:
   1. Revert Business Logic Service to version 3.1.5
   2. Perform rolling rollback (3 replicas)
   3. Verify Business Logic Service functionality
   ...

🏛️ Architecture Patterns

3-Tier Microservices

# Tier 1: Frontend
frontend-app → api-gateway

# Tier 1.5: API Gateway
api-gateway → [business-logic, data-processing, user-service]

# Tier 2: Application Services
business-logic → data-access-layer
data-processing → data-access-layer
user-service → data-access-layer

# Tier 3: Data Access
data-access-layer → [postgresql, redis]

Event-Driven Architecture

notification-service:
  dependencies:
    - id: kafka-broker
      type: event-streaming

data-processing:
  dependencies:
    - id: kafka-broker
      type: event-streaming

Observability Integration

business-logic:
  dependencies:
    - id: prometheus
      type: monitoring
    - id: jaeger
      type: tracing
    - id: logstash
      type: logging

🔬 Advanced Features

Circular Dependency Detection

python -m src.cli examples/enterprise-platform.yaml validate

Detects and reports any circular dependencies in the architecture.

Transitive Dependency Analysis

python -m src.cli examples/enterprise-platform.yaml deps svc-business-logic

Shows complete dependency tree including transitive dependencies.

Critical Path Identification

The system identifies critical components based on:

  • Number of dependents
  • Critical flag in metadata
  • Position in dependency graph

Update Order Optimization

When multiple components need updating, the system:

  • Calculates optimal order (dependencies first)
  • Identifies components that can be updated in parallel
  • Minimizes overall downtime

📚 API Usage

Python API

from src import (
    ArchitectureParser,
    DependencyGraph,
    UpdateEngine,
    ArchitectureValidator
)

# Load architecture
architecture = ArchitectureParser.parse_yaml_file("my-arch.yaml")

# Validate
errors = ArchitectureValidator.validate(architecture)

# Build dependency graph
graph = DependencyGraph(architecture)

# Analyze impact
impact = graph.analyze_impact("my-component", "2.0.0")

# Generate update plan
engine = UpdateEngine(architecture)
plan = engine.generate_update_plan("my-component", "2.0.0")

# Access plan details
print(f"Affected: {len(plan.affected_components)}")
print(f"Downtime: {plan.estimated_downtime_minutes} min")
for step in plan.update_sequence:
    print(step)

🧩 Extending the System

Adding New Component Types

Edit src/models.py:

class ComponentType(Enum):
    # Add your type
    MY_NEW_TYPE = "my-new-type"

Adding New Dependency Types

class DependencyType(Enum):
    # Add your type
    MY_DEPENDENCY = "my-dependency"

Custom Validation Rules

Edit src/parser.py:

def _validate_component_rules(architecture):
    # Add custom validation
    pass

🎓 Best Practices

  1. Use Explicit Dependencies: Always specify dependencies, even if they seem obvious
  2. Version Constraints: Use appropriate constraints (^ for compatible, >= for minimum)
  3. Mark Critical Components: Set critical: true for production-critical services
  4. Tier Metadata: Always specify tier for application components
  5. Replicas: Specify replica counts for accurate downtime estimation
  6. Testing First: Run impact analysis before generating update plans
  7. Validate Often: Run validation after architecture changes

🐛 Troubleshooting

Validation Errors

# Check for specific errors
python -m src.cli examples/enterprise-platform.yaml validate

Common issues:

  • Missing component IDs in dependencies
  • Circular dependencies
  • Invalid version constraints

Circular Dependencies

If detected:

  1. Review dependency chain shown in error
  2. Consider breaking cycle with event-driven pattern
  3. Use soft dependencies where appropriate

📄 License

MIT License

🤝 Contributing

Contributions welcome! Areas for enhancement:

  • Additional component types
  • More sophisticated version resolution
  • Visualization generation
  • Integration with infrastructure-as-code tools
  • Real-time architecture monitoring

📞 Support

For issues and questions:

  • Create an issue in the repository
  • Review demo.py for usage examples
  • Check examples/ directory for architecture templates

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages