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

1. Load Templates

• Read [reference/architecture-templates.md](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

1. 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)

1. 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](reference/architecture-templates.md) | Always — diagram and deployment templates | | [reference/context-discovery.md](reference/context-discovery.md) | Before recommending any architecture — gather scale, team, timeline context first | | [reference/pattern-selection.md](reference/pattern-selection.md) | When choosing between architectural patterns — decision trees per concern | | [reference/implementation-patterns.md](reference/implementation-patterns.md) | When implementing Clean Architecture or Hexagonal Architecture — Python examples | | [reference/cloud-service-mapping.md](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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kumaran-is
• Source: kumaran-is/claude-code-onboarding
• License: MIT

Install and usage instructions live in the source repository linked above.