software-architect

name	Software Architect
description	Design scalable systems with sound trade-offs, clear boundaries, and maintainable patterns.
metadata	{"clawdbot":{"emoji":"🏗️","os":["linux","darwin","win32"]}}

Software Architecture Rules

Design Principles

• Simple until proven insufficient — complexity is a cost, not a feature
• Separate what changes from what stays stable — boundaries at change boundaries
• Design for the next 10x, not 100x — over-engineering wastes resources
• Make decisions reversible when possible — defer irreversible ones until necessary
• Constraints clarify design — embrace limitations, don't fight them early

System Boundaries

• Define clear interfaces between components — contracts enable independent evolution
• Boundaries where teams split — Conway's Law is real, design with it
• Data ownership at boundaries — one source of truth per entity
• Async communication for loose coupling — sync calls create distributed monoliths
• Fail independently — one component's failure shouldn't cascade

Trade-off Analysis

• Every decision has costs — articulate what you're giving up
• Consistency vs availability vs partition tolerance — pick two (CAP theorem)
• Performance vs maintainability — optimize hot paths, keep the rest readable
• Build vs buy — build differentiators, buy commodities
• Document the "why not" for rejected alternatives — future you needs context

Scalability

• Stateless services scale horizontally — state makes scaling hard
• Cache aggressively, invalidate carefully — caching solves and creates problems
• Database is usually the bottleneck — read replicas, sharding, or denormalization
• Queue work that can be async — users don't need to wait for everything
• Scale for expected load, prepare for 3x spikes — headroom prevents outages

Data Architecture

• Schema design constrains everything — get it right early, migrations are expensive
• Normalize for writes, denormalize for reads — optimize for access patterns
• Event sourcing when audit trail matters — reconstruct state from events
• CQRS when read/write patterns differ significantly — separate models for each
• Data gravity is real — processing moves to data, not vice versa

Reliability

• Design for failure — everything fails eventually, handle it gracefully
• Timeouts on all external calls — hung connections cascade into outages
• Circuit breakers prevent cascade failures — fail fast, recover gradually
• Idempotency for retries — duplicate messages shouldn't corrupt state
• Graceful degradation over total failure — partial functionality beats error pages

Security

• Defense in depth — multiple layers, no single point of failure
• Least privilege — minimal permissions for each component
• Encrypt in transit and at rest — assume networks and disks are hostile
• Validate at boundaries — don't trust input from outside your system
• Secrets management from day one — retrofitting is painful

Evolution

• Design for replacement, not immortality — components will be rewritten
• Incremental migration over big bang — strangler fig pattern works
• Backwards compatibility for APIs — breaking changes break trust
• Feature flags decouple deploy from release — ship dark, enable gradually
• Monitor before, during, and after changes — data beats intuition

Documentation

• Document decisions, not just structures — ADRs capture reasoning
• Diagrams at multiple zoom levels — C4 model: context, containers, components
• Keep docs near code — separate wikis go stale
• Update docs when architecture changes — wrong docs are worse than none
• Document operational aspects — runbooks, SLOs, failure modes

Communication

• Translate technical decisions to business impact — stakeholders need context
• Present options with trade-offs — don't just recommend, explain
• Listen to operators — they know what breaks
• Involve security early — bolt-on security is weak security
• Decisions need buy-in — imposed architecture breeds resentment