From kapil-agent-skills
Generate a complete system architecture from a one-line idea. Covers all layers: Frontend, Backend, AI, Agents, Infra, and Security — with every decision justified by functional and non-functional requirements. Use this skill whenever the user describes an app, product, or system they want to build and wants to understand how to architect it. Trigger on phrases like "architect this", "system design for", "how would I build", "design a system that", "I want to build X", "draw the architecture", "what's the tech stack for", or any time someone describes an idea and wants a technical breakdown — even if they don't say "architecture" explicitly. Also use for interview prep: "help me design X for a system design interview."
How this skill is triggered — by the user, by Claude, or both
Slash command
/kapil-agent-skills:idea-to-architectureThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Turns a one-line idea into a complete, justified system architecture across 6 layers.
Turns a one-line idea into a complete, justified system architecture across 6 layers. Every decision traces back to a functional or non-functional requirement.
Before asking anything, read the user's idea and extract:
Use Cases: What are the 3-5 core things this system does?
User Actions: What does a user actually do? (search, upload, stream, checkout...)
Business Capabilities: What must the system deliver? (real-time delivery, recommendations...)
Data Entities: What are the main objects? (User, Post, Order, Video...)
Read vs Write: Is the dominant pattern reads, writes, or real-time events?
Do this silently. Don't show the template — show the extracted output as a clean summary.
After extracting FRs, ask the user exactly these 3 questions in one message:
Before I design the architecture, 3 quick questions:
1. Scale — rough DAU range?
a) < 10k (early / MVP)
b) 10k–1M (growth stage)
c) 1M+ (production scale)
2. Data pattern — what does this system do more of?
a) Read-heavy (feeds, search, content delivery)
b) Write-heavy (transactions, uploads, events)
c) Real-time (chat, live updates, collaborative)
d) Mixed
3. Consistency — does wrong data cost money, or just feel stale?
a) Strong consistency (payments, inventory, bookings)
b) Eventual consistency (social feeds, likes, recommendations)
Wait for answers. Then build the NFR profile:
Based on answers, infer and state the full NFR profile before generating architecture:
| NFR | Inferred Value | Source |
|---|---|---|
| Scale | DAU + RPS estimate | Q1 answer |
| Surface | Web / Mobile / Both | Extracted from idea |
| Latency target | p95 / p99 targets | Scale + data pattern |
| Consistency model | Strong / Eventual | Q3 answer |
| Availability target | 99% / 99.9% / 99.99% | Scale |
| Resilience patterns | Queue / Circuit breaker / Fanout | Data pattern |
| Caching strategy | None / Redis / CDN / Both | Read vs write |
| DB choice | SQL / NoSQL / Hybrid | Q3 + data pattern |
| Async needs | Sync / Kafka / WebSocket | Data pattern + latency |
| Offline support | Not needed / Offline-first | Mobile surface |
| Multi-region | No / Active-Passive / Active-Active | Scale + availability |
| Security level | Basic / OAuth+JWT / mTLS+SSO | Scale + data sensitivity |
| Deployment strategy | Manual / CI/CD canary / Blue-green | Scale + team |
| Observability | Logs / Metrics / Full OpenTelemetry | Scale |
Show this table to the user. Say: "Here's the NFR profile I'm working from — let me know if anything looks off."
Read the relevant reference files before generating each layer:
references/frontend.mdreferences/mobile.mdreferences/backend.mdreferences/database.md (CAP theorem, DB choice, free tiers, scaffolding)references/ai-layer.mdreferences/agent-layer.mdreferences/infra.mdreferences/security.md early; apply to every layer, then summarise in Layer 6plan.md in Phase 3 (Holistic Prototype Blueprint)In this phase, create or update a single end-to-end architecture artifact named plan.md.
Rules:
plan.md in the project root.plan.md already exists, update it in place instead of duplicating sections.frontend.md, mobile.md when needed, backend.md, database.md, ai-layer.md, agent-layer.md, infra.md, security.md, diagram-guide.md).plan.md has been written or updated successfully.plan.md required structure:
# End-to-End Prototype Architecture Plan — <idea name>
## 1) Problem Statement and Product Goal
- <what is being built and why now>
## 2) Functional Requirements
- <core use cases and entities>
## 3) User Inputs and NFR Profile
- Scale: <Q1>
- Data pattern: <Q2>
- Consistency: <Q3>
- <inferred NFR bullets: latency, availability, resilience, security, observability>
## 4) End-to-End Architecture (All Layers)
### Layer 1 — Frontend / Mobile
- <recommendation + why>
### Layer 2 — Backend + Database
- <recommendation + why>
### Layer 3 — AI Layer
- <recommendation + why, or explicit skip>
### Layer 4 — Agent Layer
- <recommendation + why, or explicit skip>
### Layer 5 — Infrastructure
- <recommendation + why>
### Layer 6 — Security
- <top risks + controls>
## 5) Data and Integration Contracts
- <key APIs/events/schemas and ownership>
## 6) Decision Log (NFR-Linked)
- <decision, chosen option, rejected option, NFR driver>
## 7) Prototype Build Plan (Execution Roadmap)
- Phase A: foundation
- Phase B: core flows
- Phase C: intelligence/agents
- Phase D: hardening
- <milestones, acceptance checks, and deliverables per phase>
## 8) Validation and Testing Strategy
- <unit, integration, e2e, load, failure drills>
## 9) Diagram Plan (Excalidraw)
- <system diagram scope + optional user flow/ERD diagrams to create>
## 10) Cost Ballpark and Scaling Triggers
- <small/medium/large monthly ranges + when to upgrade architecture>
## 11) Open Questions and Assumptions
- <explicit unknowns to resolve>
After writing plan.md, provide the full architecture response in chat.
This skill makes concrete recommendations. It does not list options and leave the decision to the user.
Rules:
Anti-pattern to avoid:
❌ "You could use Kafka or SQS depending on your requirements"
✅ "Use SQS. Skip Kafka — at <10k DAU your write volume doesn't justify
Kafka's ops overhead ($200+/mo managed + team ramp-up). SQS handles
this for ~$5/mo. Revisit Kafka if you exceed 10k messages/sec."
For each layer output, use this format:
### Layer Name
**Recommendation:** [Specific tool / pattern / approach]
**Why this, not the alternative:**
→ [Alternative] would be wrong here because [specific reason tied to NFR]
→ NFR driver: [Scale / Latency / Consistency / Cost / Maintainability]
**Skip:** [Technology to avoid] — [one-line reason why it's overkill or wrong fit]
**Tradeoffs you're accepting:**
✅ What this gives you
⚠️ What you give up — and when it becomes a problem
**Upgrade when:** What signal tells you to revisit this decision
First, determine the surface type:
Is this a mobile app (iOS / Android)?
→ YES → Read references/mobile.md → cover mobile architecture
→ Web only → Read references/frontend.md → cover web architecture
→ Both → Cover both, note shared API strategy (BFF pattern)
If web: Cover:
If mobile: Cover:
Cover backend architecture first, then go deep on database:
Backend:
Database (read references/database.md for full guidance):
Cover:
Only include this layer if the idea involves AI. If not, state: "No dedicated AI layer needed — skip to Agents or Infra."
Cover:
Only include if the idea involves autonomous behaviour. If not, state: "No agent layer needed for this architecture."
Cover:
Read references/security.md for threat model, identity, edge, API, data, AI/agent, infra, and detection. Synthesise for this product — do not paste the whole checklist.
Cover across all layers (tailor to NFR and surface):
Output the top risks for this idea and the specific controls you recommend (opinionated, tied to NFR).
After all layers, output a clean decision log:
## Decision Log
| Decision | Chosen | Because | NFR |
|----------|--------|---------|-----|
| Database | PostgreSQL | Payment data needs ACID transactions | Consistency: Strong |
| Messaging | Kafka | Write-heavy, needs durability + replay | Write-heavy + Resilience |
| Caching | Redis | Read-heavy feed, p95 <200ms target | Latency + Read-heavy |
| Deployment | Blue-Green | Zero downtime releases needed at scale | Availability 99.9% |
| Tracing | OpenTelemetry | Multi-service, need E2E visibility | Observability |
After the decision log, draw the architecture using Excalidraw.
Read references/diagram-guide.md for element format, layout rules, and when to add extra diagrams (e.g. user flow, N-tier/system context, ERD / table relationships). Prefer at least one system diagram; add user flow + ERD when they clarify the design.
Layout order (left to right, top to bottom):
[Client / Browser / Mobile]
↓
[CDN] → [Load Balancer / API Gateway]
↓
[Frontend Server / BFF]
↓
[Backend Services] [AI Layer] [Agent Layer]
↓ ↓ ↓
[Message Queue (Kafka)]
↓
[Databases] [Cache (Redis)] [Object Storage]
↓
[Infra: K8s / Serverless]
↓
[Observability: Prometheus + Grafana + Kibana + OpenTelemetry]
## Cost Ballpark (monthly, USD)
| Tier | DAU | Approx Cost | Main drivers |
|------|-----|-------------|--------------|
| 🟢 Small | <10k | $50–$300 | Serverless + managed DB |
| 🟡 Medium | 10k–1M | $500–$5,000 | K8s cluster + Redis + Kafka |
| 🔴 Large | 1M+ | $10,000+ | Multi-region + dedicated infra |
Note: "These are order-of-magnitude estimates. Actual cost depends heavily on data transfer, storage, and AI API usage."
Before finishing, verify:
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub kapilraghuwanshi/skills --plugin kapil-agent-skills