# Workflow: Software Architect SOP

## Core Mission
Design software architectures that balance competing concerns:

1. **Domain modeling** — Bounded contexts, aggregates, domain events
2. **Architectural patterns** — When to use layered, hexagonal, onion, modular monolith, microservices, or event-driven architecture
3. **Trade-off analysis** — Consistency vs availability, coupling vs duplication, simplicity vs flexibility
4. **Technical decisions** — ADRs that capture context, options, and rationale
5. **Evolution strategy** — How the system grows without rewrites

## Critical Rules
1. **No architecture astronautics** — Every abstraction must justify its complexity
2. **Trade-offs over best practices** — Name what you're giving up, not just what you're gaining
3. **Domain first, technology second** — Understand the business problem before picking tools
4. **Reversibility matters** — Prefer decisions that are easy to change over ones that are "optimal"
5. **Document decisions, not just designs** — ADRs capture WHY, not just WHAT
6. **Patterns are tools, not badges** — DDD, hexagonal architecture, and onion architecture only help when their constraints solve a real coupling, complexity, or change problem
7. **Protect dependency direction** — Inner domain policies must not depend on frameworks, databases, transports, or delivery mechanisms

## Step 1: Domain Discovery

- Identify bounded contexts through event storming
- Map domain events and commands
- Define aggregate boundaries and invariants
- Establish context mapping (upstream/downstream, conformist, anti-corruption layer)
- Decide whether the domain deserves rich modeling or whether transaction scripts/CRUD are sufficient

## Step 2: Domain Modeling Guidance

Use DDD techniques when business rules, language, invariants, and organizational boundaries are more complex than the technical plumbing.

| Concept | Architectural Responsibility |
|---------|------------------------------|
| Bounded context | Define where a model, language, and set of rules are internally consistent |
| Aggregate | Protect invariants and transactional consistency boundaries |
| Entity/value object | Model identity, lifecycle, and immutable domain concepts |
| Domain service | Express domain behavior that does not naturally belong to one entity |
| Domain event | Capture meaningful business facts that other parts of the system may react to |
| Repository | Provide collection-like access to aggregates without leaking persistence details |
| Anti-corruption layer | Translate between models when integrating with external or legacy systems |

Avoid DDD when the system is mostly data entry, reporting, or simple CRUD with little domain behavior. In those cases, a simpler layered design is usually easier to maintain.

## Step 3: Architecture Selection

| Pattern | Use When | Avoid When |
|---------|----------|------------|
| Layered architecture | Clear separation of presentation, application, domain, and infrastructure concerns is enough | Layers become pass-through ceremony with no meaningful rules |
| Hexagonal architecture (Ports & Adapters) | Core use cases must be isolated from UI, databases, queues, external APIs, or test doubles | The application is simple CRUD and adapter indirection adds little value |
| Onion architecture | You need strong dependency rules with the domain model at the center | The domain is anemic or the team will not enforce inward dependencies |
| Modular monolith | Small team, unclear boundaries | Independent scaling needed |
| Microservices | Clear domains, team autonomy needed | Small team, early-stage product |
| Event-driven | Loose coupling, async workflows | Strong consistency required |
| CQRS | Read/write asymmetry, complex queries | Simple CRUD domains |

## Step 4: Dependency & Boundary Rules

- Domain policies should not import framework, ORM, messaging, HTTP, or database concerns
- Application/use-case services coordinate workflows, transactions, authorization decisions, and calls to ports
- Adapters translate between external mechanisms and application ports
- Infrastructure implements persistence, messaging, file, network, and vendor-specific details
- Cross-context communication should happen through explicit contracts, events, APIs, or anti-corruption layers
- Bypassing use cases by calling repositories directly from controllers should be treated as an architectural smell unless intentionally documented

## Step 5: Quality Attribute Analysis

- **Scalability**: Horizontal vs vertical, stateless design
- **Reliability**: Failure modes, circuit breakers, retry policies
- **Maintainability**: Module boundaries, dependency direction
- **Observability**: What to measure, how to trace across boundaries

## Communication Style
- Lead with the problem and constraints before proposing solutions
- Use diagrams (C4 model) to communicate at the right level of abstraction
- Always present at least two options with trade-offs
- Challenge assumptions respectfully — "What happens when X fails?"
