system-architecture（系统架构）

System Architecture Designer — Orchestrator

*Productivity — Multi-agent orchestration. Transforms product specifications into a comprehensive technical blueprint covering stack, schema, APIs, and deployment.*

Core Question: "Will this still work at 10x scale with 10x team?"

Inputs Required

• Product specification, PRD, or description of what needs to be built
• Scale expectations (users, requests, data volume) — gathered via interview if missing
• Known constraints (existing stack, compliance, budget, team skills)

Output

• .agents/system-architecture.md

Chain Position

Previous: plan-interviewer or task-breakdown (optional) | Next: task-breakdown (optional) | Cross-stack: reads solution-design.md (from research-skills), user-flow.md (from product-skills)

Re-run triggers: When product spec changes significantly, when scale requirements change (10x growth), when migrating core infrastructure, or when adding major new integrations.

Multi-Agent Architecture

Agent Manifest

Execution Layers

Layer 1 (parallel):
  stack-selection-agent ──┐
  infrastructure-agent ───┘─── run simultaneously

Layer 2 (sequential):
  schema-agent ─────────────── depends on stack choice
    → api-agent ────────────── depends on stack + schema
      → integration-agent ──── depends on stack + schema + API
        → scaling-agent ────── validates everything above
          → critic-agent ───── final quality review

Dispatch Protocol

1. Gather context — extract user types, data entities, critical flows, scale profile, and constraints from the product spec. If missing, run the Architecture Interview (see below).
2. Layer 1 dispatch — send brief + constraints to stack-selection-agent and infrastructure-agent in parallel.
3. Layer 2 sequential chain — pass stack output to schema-agent, then stack + schema to api-agent, then all three to integration-agent, then everything to scaling-agent.
4. Critic review — send assembled document to critic-agent.
5. Revision loop — if critic returns FAIL, re-dispatch affected agents with feedback. Maximum 2 revision rounds.
6. Assembly — merge all agent outputs into the 12-section artifact template. Save to .agents/system-architecture.md.

Routing Logic

Critical Gates

Before delivering, the critic-agent verifies ALL of these pass:

• Every tech choice has a rationale (not just "it's popular")
• API endpoints exist for every user-facing feature
• Database schema covers all entities mentioned in product spec
• Deployment section includes complete env var list
• File structure matches chosen framework conventions
• Auth model covers all user roles and permission levels
• At least one architectural trade-off is documented with alternatives considered

If any gate fails: the critic identifies which agent must fix it and the orchestrator re-dispatches with specific feedback.

Single-Agent Fallback

When context window is constrained or the product is simple (fewer than 3 user types, fewer than 5 data entities):

1. Skip multi-agent dispatch
2. Execute Steps 1-4 from the original process sequentially:

- Step 1: Gather context and constraints - Step 2: Architecture decisions (use references/tech-stack-patterns.md and references/tech-stack-matrix.md) - Step 3: Generate all 12 sections of the architecture document - Step 4: Validation cross-reference

1. Run the Critical Gates checklist as self-review
2. Save to .agents/system-architecture.md

Before Starting

Step 0: Product Context

Check for .agents/product-context.md. If missing: interview for product dimensions (what, who, problem, differentiator, scale, integrations) and save to .agents/product-context.md. Or recommend running icp-research (from hungv47/marketing-skills) to bootstrap it.

If .agents/product-context.md has a date field older than 30 days, recommend re-running icp-research (from marketing-skills) to refresh it.

Required Artifacts

None — this skill can run standalone.

Optional Artifacts

Two Modes of Operation

Mode 1: Tech Stack Already Chosen User provides tech stack upfront. Skip stack-selection-agent. Focus on schema, API, file structure, and implementation details.

Mode 2: Need Tech Stack Recommendations User needs help choosing stack. Run stack-selection-agent first, then chain remaining agents.

Architecture Interview

If the user provides only a vague description ("build me an app", "I need a platform"):

1. What is the product and its core value proposition?
2. Who are the primary users? Expected concurrent users at launch and at 12 months?
3. What are the 3-5 critical user flows?
4. What data needs to be stored and queried?
5. Existing tech stack or team skill constraints?
6. Specific integrations needed? (payments, email, auth providers, etc.)
7. Performance requirements? (real-time updates, complex queries, offline support)
8. Security/compliance needs? (SOC2, HIPAA, GDPR, PCI)

All 8 answers are necessary before dispatching agents.

Anti-Patterns

Worked Example

User: "I need architecture for a SaaS invoicing tool. Small businesses send invoices, clients pay online. Need Stripe integration."

Orchestrator gathers context:

• Users: business owners (send invoices), clients (view/pay)
• Scale: ~500 businesses, ~2000 invoices/month at launch
• Integrations: Stripe for payments, SendGrid for email
• Constraints: small team, fast launch needed

Layer 1 dispatch (parallel):

• stack-selection-agent → recommends Next.js + Supabase + Clerk + Stripe + Vercel
• infrastructure-agent → plans Vercel deployment, GitHub Actions CI/CD, Sentry monitoring

Layer 2 chain (sequential):

• schema-agent → designs businesses, invoices, payments, clients tables with indexes on (business_id, status) and (stripe_payment_id)
• api-agent → maps POST /api/invoices (business_owner), GET /api/pay/:token (public), POST /api/webhooks/stripe (stripe_signature)
• integration-agent → designs file structure, Stripe checkout flow, SendGrid email integration
• scaling-agent → identifies invoice PDF generation as first bottleneck at 10x, traces webhook failure modes

Critic review: PASS — all 7 quality gates pass.

Artifact saved to .agents/system-architecture.md with all 12 sections.

Artifact Template

On re-run: rename existing artifact to system-architecture.v[N].md and create new with incremented version.

---
skill: system-architecture
version: 1
date: {{today}}
status: draft
---

# System Architecture: [Product Name]

## 1. System Overview
## 2. Tech Stack
## 3. File & Folder Structure
## 4. Database Schema
## 5. API Architecture
## 6. State Management & Data Flow
## 7. Service Connections
## 8. Authentication & Authorization
## 9. Key Features Implementation
## 10. Deployment & Infrastructure
## 11. Monitoring & Debugging
## 12. Security Checklist

## Open Questions
## Next Step
Run `task-breakdown` to decompose this architecture into implementable tasks.

References

• references/tech-stack-patterns.md — Tech choice comparisons and recommendations
• references/tech-stack-matrix.md — Stack comparison matrix
• references/file-structure-patterns.md — Directory structures by framework
• references/database-patterns.md — Common schemas and query patterns
• references/api-patterns.md — REST best practices and endpoint examples
• references/auth-patterns.md — Authentication implementations
• references/deployment-patterns.md — CI/CD and infrastructure patterns
• references/failure-modes.md — Failure mode criticality, error tracing table, shadow path analysis
• references/interaction-edge-cases.md — UI and interaction edge case categories