Well Architected

Well-Architected Framework

A structured framework for evaluating architecture quality across six pillars. Inspired by the AWS Well-Architected Framework, adapted for startups and modern product development. Technology-agnostic — applies to any stack.

Use this skill when generating the Well-Architected Review deliverable in /architect:blueprint or when running /architect:well-architected as a standalone evaluation.

The Six Pillars

1. Operational Excellence

Question: Can you deploy, monitor, and improve the system with confidence?

Key questions to ask:

• How do you deploy a change today? How long does it take?
• When something breaks at 2am, how do you find out? How do you fix it?
• Can a new developer deploy to staging on their first day?

2. Security

Question: Is user data protected, and are attack surfaces minimized?

Key questions to ask:

• What happens if an API key leaks? How fast can you rotate it?
• Can a regular user access admin endpoints by guessing the URL?
• Are you storing anything you shouldn't be? (passwords, full card numbers, unnecessary PII)

3. Reliability

Question: Does the system keep working when things go wrong?

Key questions to ask:

• What happens when the database goes down for 5 minutes?
• What happens when a third-party API (Stripe, SendGrid) is slow or down?
• Can the system handle a sudden traffic spike (e.g., HackerNews front page)?

4. Performance Efficiency

Question: Are resources used efficiently, and is the user experience fast?

Key questions to ask:

• What's the slowest user-facing operation? Can it be made async?
• Are you paying for compute that's idle 90% of the time?
• Is there a caching layer, or does every request hit the database?

5. Cost Optimization

Question: Are you spending the minimum needed for the current scale?

Key questions to ask:

• What's your monthly cloud bill? Do you know what each line item is?
• Are you using the cheapest option that meets your requirements?
• When you 10x users, does cost 10x too, or less?

6. Developer Experience

Question: Can developers build, test, and ship features quickly and confidently?

Key questions to ask:

• How long does it take a new developer to submit their first PR?
• Can you run the entire system locally without cloud credentials?
• Is there a style guide or do code reviews catch inconsistencies?

Scoring Methodology

Per-Pillar Scoring

Each pillar is scored 1-5 based on the average of its criteria:

Overall Architecture Rating

Average of all 6 pillar scores:

Stage-Appropriate Expectations

Not every project needs a 5/5 on every pillar. Set expectations by stage:

Output Format

IMPORTANT: Be comprehensive and thorough in all sections.

1. Visual Score Summary (REQUIRED)

Visualize pillar scores as a horizontal bar table:

Operational Excellence  ████░  4/5 — Good
Security               ███░░  3/5 — Adequate
Reliability            ██░░░  2/5 — Needs Work
Performance Efficiency ████░  4/5 — Good
Cost Optimization      █████  5/5 — Excellent
Developer Experience   ███░░  3/5 — Adequate

Overall: 3.5/5 — Solid

Score table (also provide as markdown table):

2. Per-Pillar Detail (MUST be thorough for each pillar)

For each of the 6 pillars, provide comprehensive analysis:

Format:

## [Pillar Name]: X/5 — [Label]

### Score Breakdown

Evaluated against [number] criteria:

| Criteria | Score | Notes |
|----------|:-----:|-------|
| [Criterion 1] | X/5 | [1 sentence why this score] |
| [Criterion 2] | X/5 | [1 sentence why this score] |
| [Criterion 3] | X/5 | [1 sentence why this score] |
| ... | ... | ... |

**Average: X.X/5 → X/5 ([Label])**

### Strengths (minimum 2-4 bullets)

✅ **[Specific strength]**
   - What: [Describe what's implemented]
   - Why it matters: [Business/technical impact]
   - Reference: [Cite specific architecture decision from manifest]

✅ **[Specific strength]**
   - What: [Describe what's implemented]
   - Why it matters: [Business/technical impact]
   - Reference: [Cite specific architecture decision from manifest]

[Continue for all major strengths...]

### Gaps (minimum 2-4 bullets if score < 5)

⚠️ **[Specific gap]**
   - What's missing: [Describe the missing capability]
   - Risk if not addressed: [Specific risk with impact estimation]
   - Severity: [Critical/High/Medium/Low]

⚠️ **[Specific gap]**
   - What's missing: [Describe the missing capability]
   - Risk if not addressed: [Specific risk with impact estimation]
   - Severity: [Critical/High/Medium/Low]

[Continue for all significant gaps...]

### Recommendations (minimum 3-5 specific actions)

Each recommendation must be:
- **Actionable**: Specific enough to implement immediately
- **Measured**: Include effort estimate and impact level
- **Prioritized**: Show order of implementation

**Format for each recommendation:**

**Recommendation #X: [Short action-oriented title]** — [Impact: High/Medium/Low] — [Effort: X hours/days/weeks]

What to do:
[2-3 sentences describing specific implementation steps]

Why it matters:
[1-2 sentences on business/technical impact]

Implementation notes:
- Tool/service to use: [Specific recommendation]
- Code location: [Where to implement, if applicable]
- Dependencies: [What must be done first]
- Definition of done: [How to verify it's complete]

Cost impact: $[amount]/month or [one-time cost]
Timeline: [When to implement — Pre-launch / Month 1 / Quarter 1 / Future]

**Example full recommendation:**

**Recommendation #1: Implement rate limiting on all API endpoints** — Impact: High — Effort: 4-6 hours

What to do:
Add rate limiting middleware using Vercel's @upstash/ratelimit package. Set default limit of 100 requests per minute per IP, with stricter limits (10 req/min) on authentication endpoints and looser limits (1000 req/min) for authenticated users. Return 429 status with Retry-After header when limit exceeded.

Why it matters:
Without rate limiting, a single malicious user or misconfigured client can overwhelm the API, causing downtime for all users. This is especially critical for authentication endpoints which are common DDoS targets. Rate limiting is a pre-launch requirement for production deployment.

Implementation notes:
- Tool/service to use: @upstash/ratelimit with Vercel KV (free tier: 10K requests/day)
- Code location: src/middleware/rateLimit.ts, apply in src/app/api/*/route.ts
- Dependencies: Set up Vercel KV store (5 minute setup)
- Definition of done: Rate limiting active on all endpoints, returns 429 when exceeded, logged in monitoring

Cost impact: $0/month (Vercel KV free tier sufficient for 10K users)
Timeline: Pre-launch (P0 — blocks production deployment)

### Stage-Appropriate Assessment

This architecture is at: **[Stage name]** stage

Expected score range for this stage: **X.X - Y.Y**
Actual score: **Z.Z**
Assessment: **[Above/At/Below]** expectations for this stage

[If below expectations:]
Critical gaps for this stage:
- [Gap 1 that's unacceptable for current stage]
- [Gap 2 that's unacceptable for current stage]
Must address before [milestone/launch].

[If at/above expectations:]
Well-positioned for [next stage]. Consider improving [pillar names] before scaling to [user count/revenue level].

3. Improvement Roadmap (minimum 8-12 items)

Provide comprehensive prioritized roadmap with P0-P3 priority levels:

Priority Definitions:

• P0 (Must-have before launch): Blocks production deployment. Critical security, reliability, or operational gaps. Complete in current sprint.
• P1 (Should-have in first month): Important for stability and user trust. Complete within 30 days of launch.
• P2 (Nice-to-have in first quarter): Improves experience and reduces operational burden. Complete within 90 days.
• P3 (Future enhancement): Optimization or nice-to-have. Evaluate after product-market fit.

Cost Summary:

• Pre-launch (P0): $X/month + Y hours labor
• Month 1 (P0+P1): $X/month + Y hours labor
• Quarter 1 (P0+P1+P2): $X/month + Y hours labor
• Full roadmap (All): $X/month + Y hours labor

Timeline Visualization:

Pre-Launch (Week 0):
├─ P0 items (total: X hours)
└─ Must complete before production deployment

Month 1 (Weeks 1-4):
├─ P1 items (total: X hours)
└─ Critical for stability

Quarter 1 (Weeks 5-12):
├─ P2 items (total: X hours)
└─ Improves operational efficiency

Future (Month 4+):
├─ P3 items (total: X hours)
└─ Evaluate based on growth

4. Quick Wins (REQUIRED if any exist)

Identify 3-5 high-impact, low-effort improvements that can be done in <1 day each:

Format:

Quick Win #X: [Short title] — [Pillar Name]

What: [1-2 sentences on what to implement]
Effort: [X hours]
Impact: [High/Medium impact on pillar score]
How: [3-5 step implementation checklist]
Cost: $[amount or $0]

ROI: [Pillar score improvement: X/5 → Y/5, or specific metric improvement]

Example:

Quick Win #1: Add security headers to API responses — Security

What: Configure Next.js security headers (CSP, X-Frame-Options, HSTS, etc.) in next.config.js to protect against common web vulnerabilities.
Effort: 30 minutes
Impact: High (improves Security pillar from 3/5 to 3.5/5)
How:
1. Add headers configuration to next.config.js
2. Test with securityheaders.com
3. Verify CSP doesn't break any functionality
4. Deploy to staging and production

Cost: $0

ROI: Security pillar: 3/5 → 3.5/5, protects against XSS and clickjacking with minimal effort

5. Critical Blockers (REQUIRED if any exist)

If any pillar scores 1/5 or has critical gaps, call them out explicitly:

🚨 CRITICAL BLOCKER: [Issue name]

Pillar: [Name]
Current state: [What's broken or missing]
Risk: [What bad thing will happen]
Probability: [High/Medium/Low chance of occurrence]
Impact: [Severity if it occurs — data loss, security breach, downtime, etc.]

This blocks: [Production launch / Scaling / User trust / Compliance]

Required action: [Specific fix needed]
Effort: [Realistic time estimate]
Must complete by: [Deadline or stage gate]
Owner: [Who should do this — role/skill level]

Example:

🚨 CRITICAL BLOCKER: No database backups configured

Pillar: Reliability
Current state: Supabase project has default backups (daily, 7-day retention) but no tested restore process. No way to recover from accidental data deletion or corruption.
Risk: Single developer mistake (DROP TABLE, bad migration) or Supabase issue could cause permanent data loss for all users.
Probability: Medium (10-15% chance in first year based on industry data)
Impact: Catastrophic — lose all user data, company trust, potential legal liability

This blocks: Production launch with real users

Required action:
1. Enable Supabase point-in-time recovery (PITR) — provides 7-day recovery window
2. Set up daily automated backup export to S3 (in addition to Supabase backups)
3. Document and TEST restore procedure (actually restore a backup to verify it works)
4. Add backup monitoring (alert if backup fails)

Effort: 4-6 hours (2 hours setup + 2 hours testing + 1 hour documentation)
Must complete by: Before production launch (P0)
Owner: Backend developer or DevOps engineer

6. Scoring Transparency (ALWAYS show)

Show how the overall score was calculated:

Well-Architected Score Calculation:

Operational Excellence: X/5
Security: X/5
Reliability: X/5
Performance Efficiency: X/5
Cost Optimization: X/5
Developer Experience: X/5
                      ─────
Total: XX/30
Average: XX/30 ÷ 6 = X.XX → X.X/5

Overall Rating: X.X/5 — [Rating Label]

Interpretation based on stage:

Stage: [MVP / Early Product / Growth / Enterprise]
Expected score range: [X.X - Y.Y]
Actual score: [Z.Z]

Assessment: [Above/At/Below] expectations

[If below]: Priority focus areas: [list pillars scoring below stage expectations]
[If at/above]: Continue improving [lowest scoring pillars] while scaling

When Evaluating Existing Architectures

When used with /architect:well-architected on an existing architecture (not a new blueprint):

1. Ask about current state — Don't assume. Ask what's already in place for each pillar.
2. Be specific — Reference actual services, endpoints, and tools from the architecture.
3. Score honestly — A 3 is not a failure. Most startups are in the 2.5-3.5 range.
4. Prioritize ruthlessly — Don't recommend 20 improvements. Pick the top 5 that give the most value.
5. Match to stage — An MVP doesn't need the same score as an enterprise product.