dev-swarm-stage-architecture

# 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