Enterprise Architecture

Enterprise Architecture

Identity

Reference System Usage

You must ground your responses in the provided reference files, treating them as the source of truth for this domain:

• For Creation: Always consult `references/patterns.md`. This file dictates how things should be built. Ignore generic approaches if a specific pattern exists here.
• For Diagnosis: Always consult `references/sharp_edges.md`. This file lists the critical failures and "why" they happen. Use it to explain risks to the user.
• For Review: Always consult `references/validations.md`. This contains the strict rules and constraints. Use it to validate user inputs objectively.

Note: If a user's request conflicts with the guidance in these files, politely correct them using the information provided in the references.

Enterprise Architecture

Patterns

Golden Rules

---

Rule

Architecture serves business

Reason

Technology for its own sake fails

---

Rule

Iterate, don't waterfall

Reason

Big-bang transformations rarely work

---

Rule

Govern, don't gatekeep

Reason

Enable teams while ensuring alignment

---

Rule

Document decisions

Reason

Future architects need context

---

Rule

Measure outcomes

Reason

Architecture must prove value

Togaf Adm

Preliminary

Framework and principles

Phase A

Architecture Vision

Phase B

Business Architecture

Phase C

Information Systems Architecture

Phase D

Technology Architecture

Phase E

Opportunities and Solutions

Phase F

Migration Planning

Phase G

Implementation Governance

Phase H

Architecture Change Management

Center

Requirements Management

Architecture Domains

Business

Artifacts

• Business Capability Map
• Value Stream Map
• Business Process Models (BPMN)

Stakeholders

• CEO
• COO
• Business Unit Leads

Data

Artifacts

• Conceptual Data Model
• Logical Data Model
• Data Dictionary

Stakeholders

• CDO
• Data Stewards
• DBA

Application

Artifacts

• Application Portfolio
• Service Catalog
• API Specifications

Stakeholders

• CIO
• Application Owners
• Developers

Technology

Artifacts

• Infrastructure Diagram
• Network Topology
• Security Architecture

Stakeholders

• CTO
• Infrastructure Team
• Security

Capability Maturity

Initial

Ad-hoc, chaotic

Repeatable

Basic processes

Defined

Standardized

Managed

Measured

Optimizing

Continuous improvement

Anti-Patterns

---

Pattern

Ivory Tower

Problem

Architecture disconnected from delivery

Solution

Embed architects in teams

---

Pattern

Analysis Paralysis

Problem

Endless planning, no delivery

Solution

Time-box phases, iterate

---

Pattern

Big Bang Transformation

Problem

All-or-nothing approach

Solution

Incremental transitions

---

Pattern

Technology-First

Problem

Choosing tech before understanding problem

Solution

Capability-driven design

---

Pattern

Documentation Overload

Problem

Diagrams no one reads

Solution

Just-enough, living documentation

---

Pattern

Governance as Gatekeeping

Problem

Architecture review as bottleneck

Solution

Enablement over control

Enterprise Architecture - Sharp Edges

Ivory Tower Architecture

Id

ivory-tower-architecture

Severity

high

Summary

Architecture team disconnected from development reality

Symptoms

• Architecture documents nobody follows
• Developers work around official architecture
• No feedback loop from implementation

Why

When architects sit separate from delivery teams, they create designs based on theoretical ideals rather than practical constraints. Teams ignore impractical mandates and create shadow architectures.

Gotcha

"The Enterprise Architecture team has mandated a 6-month review cycle for all technology decisions. Meanwhile, we need to ship in 2 weeks."

Teams will just ignore the process and accumulate tech debt!

Solution

1. Embed architects in delivery teams:

• Rotate architects through product teams
• Architects write code sometimes
• Attend standups and retros

2. Lightweight governance:

• Self-service architecture review templates
• Async reviews for standard patterns
• Reserve sync reviews for novel decisions

3. Feedback loops:

• Track actual vs. intended architecture
• Post-mortems inform future guidance
• Architecture debt is visible

Big Bang Transformation Failure

Id

big-bang-transformation

Severity

critical

Summary

Attempting to replace everything at once leads to project failure

Symptoms

• Multi-year transformation timeline
• All-or-nothing migration approach
• No intermediate value delivery

Why

Large transformations fail because requirements change during execution, key people leave, budgets get cut, and complexity compounds. The longer the timeline, the higher the failure probability.

Gotcha

"We'll spend 18 months building the new platform, then migrate everything over a weekend. The old system will be decommissioned Monday."

Never works! Something always goes wrong at cutover.

Solution

1. Strangler Fig pattern:

• Route specific traffic to new system
• Incrementally migrate features
• Old and new coexist during transition

2. Define intermediate architectures:

• Transition State 1: Core migrated
• Transition State 2: Integrations migrated
• Target State: Legacy decommissioned

3. Measure progress:

• Traffic percentage on new system
• Feature parity checklist
• Value delivered at each stage

Bounded Context Violations

Id

context-boundary-violation

Severity

high

Summary

Sharing databases or models across domain boundaries

Symptoms

• Multiple teams modifying same database tables
• Shared library with domain logic
• Changes in one domain break another

Why

When bounded contexts share implementation details, they become coupled. Changes require coordination across teams. This slows development and increases the risk of breaking changes.

Gotcha

"We'll just add a column to the customers table. The other team uses it too, but they'll be fine."

They won't be fine! Their queries will break.

Solution

1. Clear context boundaries:

• Each context owns its data
• Integration via events or APIs
• No shared databases

2. Anti-corruption layer:

• Translate between context models
• Don't leak internal structure
• Version integration contracts

3. Context mapping:

• Document relationships between contexts
• Define integration patterns
• Assign ownership

Architecture Review Bottleneck

Id

governance-bottleneck

Severity

high

Summary

All decisions require architecture board approval

Symptoms

• Long wait times for architecture review
• Teams waiting on approval to proceed
• Architecture board overwhelmed

Why

Centralized review creates bottlenecks. Teams queue for approval while competitors ship. Eventually teams bypass the process entirely, defeating the purpose of governance.

Gotcha

"All technology decisions must go through the Architecture Review Board, which meets monthly."

Teams waiting 4-6 weeks for approval! They'll just do it anyway.

Solution

1. Tiered governance:

• Tier 1: Team decides (standard patterns)
• Tier 2: Architect advises (minor deviations)
• Tier 3: ARB approves (novel or risky)

2. Pre-approved patterns:

• Reference architectures for common cases
• Technology radar with recommended defaults
• Self-service compliance checks

3. Asynchronous review:

• ADR (Architecture Decision Record) review
• Comment period instead of meetings
• Escalate only on objection

Enterprise Architecture - Validations

Architecture Decision Without Record

Id

missing-adr

Severity

warning

Type

regex

Pattern

• // TODO: document architecture decision
• # DECISION: .*(?!ADR|adr)

Message

Architecture decision may not be documented in ADR.

Fix Action

Create Architecture Decision Record (ADR) for significant decisions

Applies To

• */.ts
• */.js
• */.py

Cross-Context Import

Id

cross-boundary-import

Severity

warning

Type

regex

Pattern

• from.domains\.[a-z]+.import.*(?!interface|event)
• import.*@/domains/[a-z]+/(?!shared|contracts)

Message

Importing implementation details across bounded context boundaries.

Fix Action

Use events or public interfaces for cross-context communication

Applies To

• */.ts
• */.py

Shared Database Table Access

Id

shared-database-access

Severity

warning

Type

regex

Pattern

• FROM\s+(users|customers|orders)\s+.JOIN.WHERE

Message

Query may access tables owned by another context.

Fix Action

Access other context data via API or events, not direct DB

Applies To

• */.sql
• */.ts
• */.py

Hardcoded Technology Choice

Id

hardcoded-technology

Severity

info

Type

regex

Pattern

• PostgreSQL|MySQL|MongoDB
• Redis|Kafka|RabbitMQ

Message

Technology choice may need abstraction for portability.

Fix Action

Consider abstraction layer for technology-specific code

Applies To

• */.ts
• */.js

API Without Contract Documentation

Id

undocumented-api-contract

Severity

warning

Type

regex

Pattern

• app\.get\(|app\.post\((?!.openapi|.swagger|.*schema)
• router\.get\(|router\.post\((?!.*docs)

Message

API endpoint may lack contract documentation.

Fix Action

Document API contract with OpenAPI/Swagger specification

Applies To

• */.ts
• */.js

Feature Without Capability Mapping

Id

missing-capability-mapping

Severity

info

Type

regex

Pattern

• // Feature:.*(?!Capability:|CAP-)
• # Feature.*(?!maps to|capability)

Message

Feature may not be mapped to business capability.

Fix Action

Map features to business capabilities for traceability

Applies To

• */.ts
• */.py
• */.md