Designing Architecture

Goal

Transform a structured requirements document into a system architecture that defines components, their boundaries, communication patterns, data storage, and key technology choices -- all documented with rationale.

When to Use

• •Requirements have been analyzed and a requirements document exists
• •You need to decide on system structure before implementation begins
• •A significant new feature requires architectural changes to an existing system
• •You need to evaluate trade-offs between different architectural approaches

Instructions

1. Review Requirements

Read the requirements document produced by the analyzing-requirements skill. Pay close attention to:

• •Scale and performance targets (non-functional requirements)
• •Number of distinct user roles and their permission models
• •Data entities and their relationships
• •Workflows that cross domain boundaries

2. Select an Architecture Pattern

Consult references/architecture-patterns.md and choose a pattern based on the decision matrix. Start simple -- a monolith or modular monolith is the right default for most projects.

3. Define System Components

Break the system into components. Each component should:

• •Own a single domain or bounded context
• •Have a clear public interface (API, event contract, or function signature)
• •Be independently testable

Example -- a typical web application:

[Browser] --> [React Frontend (SPA)]
                  |
                  v
            [Flask API Server]
                  |
          +-------+-------+
          |               |
          v               v
   [PostgreSQL DB]   [Redis Cache]

Components:

1. •React Frontend: Renders UI, manages client state, calls API
2. •Flask API Server: Handles HTTP requests, enforces business logic, manages auth
3. •PostgreSQL Database: Persists entities and relationships
4. •Redis Cache: Stores sessions and frequently accessed data

4. Design API Contracts

Define the API surface between frontend and backend (and between backend services if applicable). For each endpoint, specify:

• •Path, method, and description
• •Request shape (body, params, query)
• •Response shape (success and error)
• •Authentication requirements

Use the OpenAPI (Swagger) format as the canonical contract when possible.

5. Choose Data Storage Strategy

Based on the data entities from the requirements document:

• •Select a primary database (relational vs document vs key-value)
• •Define indexing strategy for common query patterns
• •Plan for migrations and schema evolution
• •Decide on caching layers if performance requirements demand them

6. Plan Authentication and Authorization

• •Choose an auth mechanism (session-based, JWT, OAuth2)
• •Define the permission model (RBAC, ABAC, or simple role checks)
• •Map user roles from requirements to permission sets
• •Identify which endpoints or components need which level of access

7. Document Decisions with ADRs

For every significant choice, write a brief Architecture Decision Record:

• •Context: What is the situation or constraint?
• •Decision: What did you choose?
• •Consequences: What are the trade-offs?

8. Produce the Architecture Document

Compile the architecture into a clear document with diagrams (described in text or ASCII), component descriptions, API contracts, and ADRs.

Constraints

✅ Do

• •Start with the simplest architecture that satisfies requirements
• •Define clear boundaries between components
• •Document trade-offs for every significant decision
• •Specify API contracts before implementation starts
• •Consider failure modes and error handling at the architecture level
• •Plan for observability (logging, monitoring, health checks)
• •Revisit the architecture if requirements change significantly

❌ Don't

• •Over-engineer the initial architecture for hypothetical future scale
• •Choose microservices unless the team size and complexity clearly demand it
• •Skip API contract definition and let frontend/backend evolve independently
• •Introduce distributed systems patterns (event sourcing, CQRS) without strong justification
• •Ignore security architecture and defer it to implementation
• •Make technology choices based on novelty rather than fitness for the problem

Output Format

A Markdown document containing:

1. •Architecture Overview -- 1-2 paragraph summary with an ASCII component diagram
2. •Component Descriptions -- table or list with responsibility, tech stack, interfaces
3. •API Contracts -- endpoint definitions with request/response shapes
4. •Data Storage -- database choice, schema overview, caching strategy
5. •Auth Architecture -- mechanism, permission model, token flow
6. •Architecture Decision Records -- one ADR per significant choice
7. •Open Risks -- known risks and mitigation strategies

Dependencies

• •../analyzing-requirements/SKILL.md -- provides the requirements document as input
• •references/architecture-patterns.md -- reference for choosing the right pattern