Stage 07 - Architecture

Design the complete system architecture including components, data flow, infrastructure, and technical decisions that will guide all subsequent development work.

When to Use This Skill

• User asks to start stage 07 (architecture)
• User wants to design system architecture or select tech stack
• User asks about database design, API architecture, or infrastructure

Your Roles in This Skill

See

dev-swarm/docs/general-dev-stage-rule.md

for role selection guidance.

Role Communication

See

dev-swarm/docs/general-dev-stage-rule.md

for the required role announcement format.

Pre-Stage Check

Before starting, verify previous stages:

1. Check if

   00-init-ideas/

   through

   06-ux/

   folders have content (not just

   .gitkeep

   )
2. If any previous stage is empty and has no

   SKIP.md

   :
   • Ask user: "Stage {XX} is not complete. Would you like to skip it or start from that stage first?"

Instructions

Step 1: Context Review

Read all files to understand the project:

• ideas.md

• 00-init-ideas/*.md

  through

  06-ux/*.md

  - All markdown files

Step 2: Create Stage Proposal

General Rules: See

dev-swarm/docs/general-dev-stage-rule.md

→ "Create Stage Proposal Rules" section.

If this stage is skipped (has SKIP.md), execute the next non-skipped stage's agent skill. Otherwise, create the file

07-architecture/README.md

with the following content:

2.1 Stage Goal

Brief the goal in 2-3 paragraphs:

• What this stage aims to achieve (define system architecture, tech stack, data models, APIs)
• Why architecture design is critical before development begins
• How this builds upon previous stages (UX flows, PRD requirements, MVP scope, tech research findings)
• What deliverables will be produced

2.2 File Selection

Select files from these options based on project needs:

System Architecture:

• system-architecture.md

  - Overall system architecture describing components and interactions

• architecture-diagram/

  - High-level system architecture diagrams

• C4-component-diagram/

  - C4 model diagrams: Context, Containers, Components Technology Stack:

• tech-stack.md

  - Selected languages, frameworks, libraries, and tools

• tech-stack-rationale.md

  - Detailed reasoning for each technology choice

Database Design:

• database-design.md

  - Database schema design and data modeling approach

• database-schema/

  - ER diagrams showing tables and relationships

API Architecture:

• api-design.md

  - API architecture patterns, authentication, versioning strategy

• api-endpoints.md

  - Complete listing of API endpoints

Infrastructure:

• infrastructure-design.md

  - Overview of infrastructure components

• infrastructure-diagram/

  - Infrastructure topology diagrams Security & Scalability:

• security-architecture.md

  - Security design including authentication and authorization

• scalability-plan.md

  - Scalability considerations and strategies

Data & Integrations:

• data-flow-diagram/

  - Data flow diagrams

• integration-architecture.md

  - Third-party service integrations

For each selected file, provide:

• Short description
• Why it's essential for this project
• Key information it should include

2.3 Request User Approval

Ask user: "Please check the Stage Proposal in

07-architecture/README.md

. Update it directly or tell me how to update it."

Step 3: Execute Stage Plan

Once user approves

07-architecture/README.md

:

3.1 Create All Planned Files

Create each file listed in the approved README:

• For

  .md

  files: Write comprehensive content with clear sections and technical details
• For diagram folders: Follow

  dev-swarm/docs/mermaid-diagram-guide.md

  to create related diagrams files

Quality Guidelines:

• Base architecture decisions on PRD requirements, UX designs, and tech research findings
• Ensure tech stack choices align with team capabilities and validated assumptions
• Design for MVP scope first, with considerations for future scalability
• Include clear component boundaries and interfaces
• Document all major architectural decisions and trade-offs
• Reference any constraints or recommendations from tech research stage

3.2 Request User Approval for Files

After creating all files:

• Provide a summary of what was created
• Highlight key architectural decisions and trade-offs
• Ask: "Please review the architecture design. You can update or delete files, or let me know how to modify them."

Step 4: Finalize Stage

Once user approves all files:

4.1 Documentation Finalization

• Sync

  07-architecture/README.md

  to remove any deleted files
• Ensure all files are complete and well-formatted
• Check that all diagrams render correctly

4.2 Prepare for Next Stage

• Summarize key architectural decisions for reference in tech-specs stage
• Identify any technical risks or open questions

4.3 Announce Completion

Inform user:

• "Stage 07 (Architecture) is complete"
• Summary of deliverables created
• Key architectural decisions made
• "Ready to proceed to Stage 08 (Tech Specs) when you are"

Stage Completion Rules

See

dev-swarm/docs/general-dev-stage-rule.md

for stage completion, commit, and skip rules.

Key Principles

• Document architectural decisions and trade-offs
• Design for MVP scope first
• Consider security and scalability from the start
• Support smooth transition to tech specs