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
| Agent | File | Focus |
|---|---|---|
| stack-selection-agent | agents/stack-selection-agent.md |
Technology choices with rationale and alternatives |
| infrastructure-agent | agents/infrastructure-agent.md |
Deployment, CI/CD, monitoring, env vars |
| schema-agent | agents/schema-agent.md |
Database tables, relationships, indexes, queries |
| api-agent | agents/api-agent.md |
Endpoints, auth, request/response contracts |
| integration-agent | agents/integration-agent.md |
File structure, service connections, feature blueprints |
| scaling-agent | agents/scaling-agent.md |
Bottleneck analysis, failure modes, edge cases |
| critic-agent | agents/critic-agent.md |
Quality gate review, internal consistency |
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
- 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).
- Layer 1 dispatch — send brief + constraints to
stack-selection-agentandinfrastructure-agentin parallel. - Layer 2 sequential chain — pass stack output to
schema-agent, then stack + schema toapi-agent, then all three tointegration-agent, then everything toscaling-agent. - Critic review — send assembled document to
critic-agent. - Revision loop — if critic returns FAIL, re-dispatch affected agents with feedback. Maximum 2 revision rounds.
- Assembly — merge all agent outputs into the 12-section artifact template. Save to
.agents/system-architecture.md.
Routing Logic
| Condition | Route |
|---|---|
| User provides tech stack upfront | Skip stack-selection-agent; pass user's stack directly to schema-agent |
| User needs stack recommendations | Run stack-selection-agent first |
| Critic returns PASS | Assemble and deliver |
| Critic returns FAIL | Re-dispatch only the agents cited in critic's issues |
| Revision round > 2 | Deliver with critic's remaining issues noted as Open Questions |
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):
- Skip multi-agent dispatch
- Execute Steps 1-4 from the original process sequentially:
- Step 1: Gather context and constraints
- Step 2: Architecture decisions (use
references/tech-stack-patterns.mdandreferences/tech-stack-matrix.md) - Step 3: Generate all 12 sections of the architecture document
- Step 4: Validation cross-reference
- Run the Critical Gates checklist as self-review
- 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
| Artifact | Source | Benefit |
|---|---|---|
product-context.md |
icp-research (from hungv47/marketing-skills) |
Industry context, user personas, and constraints |
task-breakdown.md |
task-breakdown | Feature list already decomposed into buildable units |
solution-design.md |
solution-design (from hungv47/research-skills) |
Business initiatives and constraints from strategy track |
.agents/design/user-flow.md |
user-flow (from hungv47/product-skills) |
User flow diagrams for API endpoint design and feature scoping |
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"):
- What is the product and its core value proposition?
- Who are the primary users? Expected concurrent users at launch and at 12 months?
- What are the 3-5 critical user flows?
- What data needs to be stored and queried?
- Existing tech stack or team skill constraints?
- Specific integrations needed? (payments, email, auth providers, etc.)
- Performance requirements? (real-time updates, complex queries, offline support)
- Security/compliance needs? (SOC2, HIPAA, GDPR, PCI)
All 8 answers are necessary before dispatching agents.
Anti-Patterns
| Anti-Pattern | Problem | INSTEAD |
|---|---|---|
| Premature microservices | Adds operational complexity before product-market fit | Start monolith, extract services at pain points |
| Schema without queries | Tables look clean but critical queries require full scans | Design schema around access patterns via schema-agent |
| Auth as afterthought | Retrofitting permissions breaks existing flows | api-agent defines roles and permissions before endpoint design |
| Missing error states | Happy-path-only architecture crumbles in production | scaling-agent traces failure modes for every critical operation |
| "We'll add monitoring later" | Debugging production without observability is guesswork | infrastructure-agent includes logging and error tracking in v1 |
| Over-engineering for scale | Building for 1M users when you have 100 wastes months | scaling-agent designs for 10x current load, plans for 100x |
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 + Vercelinfrastructure-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 integrationscaling-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
More from hungv47/prod-skills
plan-interviewer
Interviews the user to clarify a vague idea into a concrete spec — asks probing questions, identifies gaps, and produces a structured PRD. Produces `.agents/spec.md`. Not for breaking an existing spec into tasks (use task-breakdown) or designing technical architecture (use system-architecture).
10code-cleanup
Audits and refactors existing code for readability, maintainability, and dead code removal without changing behavior. Produces `.agents/cleanup-report.md` and applies fixes in-place. Not for diagnosing business problems (use problem-analysis) or writing documentation (use technical-writer).
8technical-writer
Generates documentation from a codebase — READMEs, API references, setup guides, runbooks, and architecture docs with consistent structure and terminology. Produces documentation files in the project. Not for specifying what to build (use plan-interviewer) or restructuring code (use code-cleanup).
8task-breakdown
Decomposes a spec or architecture into buildable tasks with acceptance criteria, dependencies, and implementation order for AI agents or engineers. Produces `.agents/tasks.md`. Not for clarifying unclear requirements (use plan-interviewer) or designing architecture (use system-architecture).
7artifact-status
Scan .agents/ — report what exists, what's stale, and the critical path to your next goal. Run at session start or when deciding what to do next.
1skill-router
Analyze a goal, suggest the right skill team, and orchestrate multi-phase workflows. Run with a goal to get a plan, or 'status' to scan artifacts. Not for executing skills (it coordinates, not executes).
1