Architectural Governance Epic

User Journey

The Architectural Governance bounded context enforces architectural rules and validates system design against CALM (Component-based Architecture with Layered Modularity) specifications. It provides automated compliance checking, dependency analysis, layer boundary validation, and architectural transparency through interactive visualization.

Jobs to be Done & EARS Requirements

Job: Validate Architectural Compliance

User Story: As an Architect, I want the system to automatically check my architectural designs against CALM rules, so that I can ensure compliance and prevent architectural drift.

EARS Requirement:

• While the system architecture is being developed or modified, when a ValidateArchitecture command is received, the architectural-governance context shall:
  1. Parse Architecture Definition:
     • Extract bounded contexts, modules, and integration points
     • Identify layer assignments (domain, application, infrastructure, ports)
  2. Check CALM Rules:
     • Verify hexagonal architecture compliance (ports and adapters pattern)
     • Validate layer boundary rules (no dependencies from inner to outer layers)
     • Check for circular dependencies between modules
     • Ensure proper use of dependency inversion
  3. Analyze Dependency Graph:
     • Build dependency graph from imports and references
     • Identify violations crossing layer boundaries
     • Detect anti-patterns (god classes, circular dependencies, coupling issues)
  4. Report Violations:
     • Document each violation with severity (error, warning, info)
     • Provide specific file and line references
     • Include remediation guidance
     • Calculate compliance score
  5. Prevent Architectural Drift:
     • Block deployments with critical violations
     • Enforce governance policies in CI/CD pipeline
     • Track compliance trends over time

Job: Provide Architectural Transparency

User Story: As a new team member, I want to view an up-to-date, interactive diagram of the system’s architecture, so that I can quickly grasp its components and their interactions.

EARS Requirement:

• When an architect or team member views the system documentation, the architectural-governance context shall:
  1. Generate Architectural Visualization:
     • Create interactive diagram showing bounded contexts
     • Display layer assignments within each context
     • Render integration points and data flow
     • Highlight compliance status with color coding
  2. Provide Detail Views:
     • Drill down into individual bounded contexts
     • Show modules, aggregates, and value objects
     • Display dependencies and integration patterns
     • Include port and adapter interfaces
  3. Display Compliance Status:
     • Visual indicator of overall compliance health with icon + text label
     • Highlight violating components in red with error icon and pattern overlay
     • Show warnings in yellow with warning icon and text label
     • Include compliance score and trend with ARIA labels and contrast-safe colors
  4. Enable Exploration:
     • Interactive navigation between components
     • Search for specific modules or patterns
     • Filter by layer, context, or compliance status
     • Export diagrams as images or documentation
  5. Facilitate Understanding:
     • Include annotations explaining architectural decisions
     • Link to ADRs (Architecture Decision Records)
     • Provide onboarding guides for new team members
     • Identify improvement opportunities

Job: Analyze Module Dependencies

User Story: As an Architect, I want to analyze dependencies between modules to identify coupling and potential refactoring opportunities, so that I can maintain clean architecture.

EARS Requirement:

• When dependency analysis is requested, the architectural-governance context shall:
  1. Scan codebase for import statements and references
  2. Build dependency graph showing module relationships
  3. Calculate metrics:
     • Coupling: Number of dependencies per module
     • Cohesion: Relatedness of module responsibilities
     • Stability: Likelihood of change propagation
  4. Identify problematic dependencies:
     • Cycles in dependency graph
     • Dependencies crossing layer boundaries
     • High coupling to unstable modules
  5. Provide refactoring recommendations based on SOLID principles

Job: Enforce Layer Boundary Rules

User Story: As a Developer, I want real-time feedback when I violate layer boundaries, so that I can fix architectural issues immediately.

EARS Requirement:

• While writing code, when a layer boundary violation is detected, the architectural-governance context shall:
  1. Detect invalid import or reference across layers
  2. Validate against hexagonal architecture rules:
     • Domain layer must not depend on application or infrastructure
     • Application layer must not depend on infrastructure
     • All dependencies must go inward through ports
  3. Report violation immediately to developer via IDE or CLI
  4. Provide specific guidance on correct pattern (port interface, adapter)
  5. Suggest refactoring to maintain architectural integrity

Domain Entities Summary

Root Aggregates

• ArchitectureValidation: Represents a validation run with timestamp, scope (entire system or specific module), and results
• Violation: Represents a CALM rule violation with type, severity, location (file/line), description, and remediation guidance
• DependencyGraph: Represents module relationships with nodes (modules) and edges (dependencies)
• ComplianceReport: Aggregates validation results with overall score, violation counts, and trend data

Value Objects

• LayerAssignment: Associates a module with an architectural layer (domain, application, infrastructure, ports)
• BoundedContext: Represents a context boundary with modules and integration points
• IntegrationPoint: Defines connection between contexts with protocol and direction
• ArchitectureDiagram: Visual representation with nodes, edges, and metadata

Policy Rules

• HexagonalArchitectureEnforcement: All modules must follow ports and adapters pattern
• NoCircularDependencies: Dependency graph must be acyclic
• LayerBoundaryCompliance: Dependencies must not cross from inner to outer layers
• DependencyInversion: Concrete implementations must depend on abstractions (ports)

Integration Points

• Developer Tooling Context: Provides real-time IDE feedback and diagnostics
• CI/CD Pipeline: Blocks deployments with critical violations
• Semantic Core Context: Processes architectural DSL definitions
• Governance Runtime Context: Reports architectural compliance for risk assessment
• Documentation Context: Generates architectural documentation and diagrams
• All Bounded Contexts: Validates module structure and dependencies