architecture-design

Iron Law: Never start implementation without an approved architecture plan; always produce API contracts and sequence diagrams before code.

Architecture Design Skill

Design system architecture, API contracts, deployment topologies, and technology decisions for full-stack applications.

Supported Design Artifacts:

• System context diagrams (C4 model, Mermaid)
• Sequence diagrams (service interactions)
• API contracts (OpenAPI 3.x)
• Deployment topologies (Docker Compose)
• Architecture Decision Records (ADRs)

Process:

1. Analyze Request

   • Identify which artifacts the user needs
   • Determine scope: single service, multi-service, full system

2. Load Templates

   • Read reference/architecture-templates.md for diagram and deployment templates
   • For detailed ADR workflows: delegate to the architecture-decision-records skill
   • For full OpenAPI spec generation: delegate to the openapi-spec-generation skill

3. Generate Artifacts

   • Use loaded templates as starting points
   • Adapt to the project's tech stack (Spring Boot, Node.js, Angular, Flutter, PostgreSQL, Firebase)
   • Follow conventions from CLAUDE.md (package structure, naming, reactive patterns)

4. Present and Iterate

   • Show generated artifacts with explanations
   • Offer refinement options (add services, change patterns, adjust topology)

Documentation Sources

Before making architecture decisions, consult these sources:

| Source | URL / Tool | Purpose | |--------|-----------|---------| | Docker | https://docs.docker.com/llms.txt | Container config, Compose, multi-stage builds | | MCP Protocol | https://modelcontextprotocol.io/llms-full.txt | MCP integration architecture and patterns | | All libraries | Context7 MCP | Latest API references for any technology |

Error Handling

Unclear artifact type: Ask user to specify (diagram, API contract, deployment, ADR).

Ambiguous tech stack: Default to project conventions in CLAUDE.md or ask for clarification if multiple options exist.

Reference Files

| File | When to Load | |------|-------------| | reference/architecture-templates.md | Always — diagram and deployment templates | | reference/context-discovery.md | Before recommending any architecture — gather scale, team, timeline context first | | reference/pattern-selection.md | When choosing between architectural patterns — decision trees per concern | | reference/implementation-patterns.md | When implementing Clean Architecture or Hexagonal Architecture — Python examples | | reference/cloud-service-mapping.md | GCP-primary cross-cloud service equivalents |

Load order for new system design:

1. context-discovery.md — classify the project (MVP / SaaS / Enterprise)
2. pattern-selection.md — choose the right pattern for the complexity
3. architecture-templates.md — generate diagrams and deployment topology
4. implementation-patterns.md — if Clean Arch or Hexagonal is chosen