architecture

name	architecture
description	Design software system architecture using requirements, constraints, data models, APIs, integrations, dependencies, and technical tradeoff analysis. Use when deciding how a system or feature will fundamentally work.

Purpose

This skill helps define the technical structure of a software product or feature before implementation decisions become expensive to reverse.

Use this skill when:

• Designing system components
• Modeling data
• Planning APIs
• Selecting dependencies
• Defining integration boundaries
• Evaluating technical tradeoffs
• Reducing implementation risk

Inputs

Expected inputs:

• Scoped requirements
• Non-goals
• Success criteria
• Functional requirements
• Non-functional requirements
• Constraints
• Existing system context
• Feasibility findings

Inputs usually come from scoping, goal-setting, and validation. If the requirements are not clear enough to design against, use scoping first.

Architecture Principles

Always optimize for:

1. Clear ownership boundaries
2. Simple data flow
3. Explicit tradeoffs
4. Compatibility with existing systems
5. Reversibility where uncertainty is high

Avoid optimizing solely for:

• Novel technology
• Premature abstraction
• Over-generalization
• Local elegance at system cost
• Ignoring operational constraints

Process

Step 1: Clarify Requirements

Determine:

• User-facing behavior
• Data requirements
• Integration points
• Performance expectations
• Security or compliance constraints
• Operational needs

Flag requirements that are ambiguous or contradictory.

---

Step 2: Define System Boundaries

Identify:

• Components
• Services
• Data stores
• APIs
• External systems
• Ownership boundaries

Make explicit what each component owns and does not own.

---

Step 3: Model Data and Interfaces

Specify:

• Core entities
• Relationships
• State transitions
• API contracts
• Event flows
• Migration needs

Use structured models or schemas when available.

---

Step 4: Evaluate Tradeoffs

Assess options across:

Factor	Questions
Simplicity	Can the team understand and operate it?
Scalability	Does it meet expected load and growth?
Reliability	What fails and how is it recovered?
Security	What data or access risks exist?
Reversibility	How hard is this to change later?

Choose the simplest design that satisfies the real constraints.

---

Step 5: Produce Architecture Decision

Generate:

• Recommended design
• Component responsibilities
• Data model or interface outline
• Key tradeoffs
• Risks
• Follow-up decisions

Anti-Patterns

Avoid:

• Designing before scope is stable enough
• Choosing dependencies without clear need
• Ignoring migration and rollout
• Treating diagrams as decisions
• Hiding unresolved tradeoffs
• Overbuilding for hypothetical scale

Reviewer Checklist

Before finalizing architecture:

• Are boundaries clear?
• Are data ownership and APIs defined?
• Are operational risks visible?
• Are major tradeoffs documented?
• Can decomposition use the design to create tasks?

Escalation Guidance

Escalate when:

• Requirements conflict
• Security or compliance impact is unclear
• Build versus buy decisions are material
• Existing system constraints block the design
• The design requires cross-team ownership changes

Example

Input:

• Scoped onboarding checklist
• Existing account setup service
• Requirement: Persist progress per workspace

Expected architecture:

1. Store checklist progress on workspace setup state
2. Expose read/update endpoints for checklist items
3. Emit completion event for analytics and support reporting

Recommended next skill:

• Use decomposition to convert the design into implementation tasks.