Architecture vs. Design vs. Implementation
"The architect's role is to balance the needs of the business, the constraints of the technology, and the art of the possible." — Grady Booch
This article clarifies the boundaries and handoffs between architecture, design, and implementation so teams make decisions at the right level and avoid rework.
- Scope: definitions, responsibilities, decision types, and how to tell which level a decision belongs to. Includes examples, trade‑offs, and a quick decision flow.
- Out of scope: deep analysis of change economics (see Architectural Decision Impact & Cost of Change), and stakeholder roles/process (see Stakeholders & Concerns).
- Aligns to business goals & quality attributes
- Sets boundaries, runtime topology, data & integration
- Long‑lived; costly to change
- Shapes modules/components & contracts
- Patterns, data models, error/caching strategies
- Medium horizon; medium cost to change
- Turns design into code, tests, configs
- Local choices: language, libs, structure, logging
- Short‑lived; relatively cheap to change
Core definitions
| Level | Primary goal | Typical scope | Decision examples | Time horizon | Cost of change | Common artifacts |
|---|---|---|---|---|---|---|
| Architecture | Align the system to business goals and quality attributes | System boundaries, runtime topology, data & integration | Monolith vs microservices; sync vs async; data ownership; security posture; deployment topology | Long‑lived | High | Architecture principles, views/diagrams, ADRs |
| Design | Shape modules/components to realize the architecture | Module/API boundaries, data models, patterns | Aggregates and repositories; interfaces; error handling strategy; caching strategy | Medium | Medium | UML/C4 component views, API contracts, sequence diagrams |
| Implementation | Make the design executable, correct, and maintainable | Code, tests, frameworks, configuration | Language, framework, libraries; function/class structure; logging; retries; feature flags | Short | Low | Source code, tests, configs |
Decision placement cues
Quick decision flow
Use this mental model to place a decision at the right level.
Real‑world scenario: checkout service
Business goal: “Enable online checkout with low latency and high availability.”
Checkout service plan
Example artifacts (abbreviated)
Status: Accepted
Context: External PSP has variable latency and failure modes.
Decision: Use async outbox + worker; PSP calls via circuit breaker; idempotency keys.
Consequences: Eventual consistency for payment status; simpler failure isolation.
Client -> API: POST /orders
API -> AppSvc: CreateOrder(cmd)
AppSvc -> Domain: Order.create()
Domain -> Outbox: enqueue(PaymentRequested)
Worker -> PSP: authorize()
PSP -> Worker: result
Worker -> Domain: apply(PaymentAuthorized|Failed)
import requests, time, random
def call_psp(payload, retries=3):
for attempt in range(1, retries + 1):
try:
resp = requests.post('https://psp.example/authorize', json=payload, timeout=2)
resp.raise_for_status()
return resp.json()
except Exception as e:
if attempt == retries:
raise
time.sleep(min(0.25 * (2 ** attempt) + random.uniform(0, 0.1), 2.0))
The ADR and sequence are architectural/design artifacts; the Python snippet is implementation—replaceable without revisiting the architecture.
Patterns, anti‑patterns, and tips
Do’s and don’ts
When to use vs. when not to use formal architecture
- Decisions shape quality attributes or require coordinated change
- Cross trust boundaries or regulated data
- Many consumers depend on your contracts
- Exploratory spikes or short‑lived tools where speed dominates
- Local refactors with contained impact—use lightweight notes in reviews
Design review checklist
- Decision level is clear (architecture, design, or implementation)
- Architectural decisions align with business goals and quality attributes
- Design choices realize architecture without violating its constraints
- Implementation details are confined and don’t leak into the design
- Contracts and interfaces are explicit and tested
- Significant architectural and design decisions are documented (e.g., in ADRs)
- The cost and impact of reversing the decision have been considered
Operational, Security, and Testing Considerations
The level of a decision directly impacts how it is operated, secured, and tested.
Considerations by Level
Architecture: Defines the deployment topology, rollout strategies (blue/green, canary), and SLOs for system-wide qualities like availability and disaster recovery. For example, choosing microservices implies managing a fleet of services, each with its own operational lifecycle.
Design: Determines component-level health checks, caching strategies (and their TTLs), and error budgets for specific APIs or modules.
Implementation: Involves setting up specific alerts, configuring resource limits (CPU/memory), and managing dependencies.
Architecture: Sets the security posture. This includes defining trust boundaries, data classification policies (e.g., PII), and the authentication/authorization model (e.g., OAuth2, mTLS). Compliance requirements like GDPR or HIPAA heavily influence architectural choices.
Design: Specifies API-level authorization, secret management patterns, and how data is encrypted in transit and at rest within a component's boundary.
Implementation: Focuses on secure coding practices, vulnerability scanning for libraries (SAST/DAST), and correct use of cryptographic APIs.
Architecture: Establishes the strategy for distributed tracing and log correlation across services. It defines what constitutes a "transaction" from an end-to-end perspective.
Design: Defines the structured logging format, key metrics (e.g., RED—Rate, Errors, Duration) for a service, and dashboard requirements.
Implementation: Adds the specific trace spans, log statements, and metric counters to the code.
Architecture: Is validated with contract tests between services, integration tests for critical user journeys, and chaos engineering to test resilience.
Design: Is tested via component-level integration tests that verify interactions and adherence to contracts.
Implementation: Is verified with unit tests, which have the narrowest scope and focus on individual functions or classes.
Related topics
- Architectural Decision Impact & Cost of Change
- Stakeholders & Concerns
- See categories for deeper dives: Core Design & Programming Principles and Documentation & Modeling