complexity-factors

name	complexity-factors
description	10-factor weighted scoring methodology for assessing build difficulty. Includes factor definitions, scoring guides, and agent/hybrid adjustments. Use when assessing project complexity.

Complexity Factors

A 10-factor scoring methodology for assessing how hard a product is to build. Use this to produce consistent, defensible complexity assessments.

---

Scoring Scale

Score	Label	Meaning
1-3	Simple	Can be built by one developer using standard tools. Well-understood patterns.
4-5	Moderate	Requires careful planning. Some specialized knowledge needed. 1-2 developers.
6-7	Advanced	Significant complexity. Multiple specialized skills needed. Small team (2-4).
8-10	Very Advanced	Cutting-edge or highly complex. Large team, long timeline, high risk.

---

The 10 Factors (Standard App)

Score each factor 1-10, then calculate the weighted average.

#	Factor	Weight	What It Measures
1	User Roles & Permissions	8%	How many user types, how complex is access control
2	Frontend Complexity	10%	Number of screens, interactivity level, real-time needs
3	Backend Architecture	12%	Number of services, communication patterns, async processing
4	Data Model	10%	Number of entities, relationships, query complexity
5	Integrations	12%	Number of third-party services, API complexity, webhook handling
6	Authentication & Security	10%	Auth requirements, data sensitivity, compliance needs
7	Infrastructure & Deployment	8%	Hosting complexity, scaling needs, CI/CD requirements
8	Real-time Features	10%	WebSocket, SSE, live updates, collaborative editing
9	AI/ML Components	12%	Agent complexity, model selection, fine-tuning needs
10	Regulatory & Compliance	8%	GDPR, HIPAA, PCI-DSS, SOC 2, data residency

Total weight: 100%

---

Factor Scoring Guide

1. User Roles & Permissions (Weight: 8%)

Score	Description
1-2	Single user type, no permissions needed
3-4	2-3 user types with basic role-based access
5-6	Multiple roles with granular permissions per resource
7-8	Multi-tenant with organization-level permissions
9-10	Complex permission trees, delegated admin, cross-org sharing

2. Frontend Complexity (Weight: 10%)

Score	Description
1-2	Simple forms and lists, 3-5 pages
3-4	Moderate UI with 5-15 pages, basic interactivity
5-6	Complex UI with dashboards, charts, drag-and-drop
7-8	Rich interactive UI, real-time updates, complex state
9-10	Collaborative editor, canvas/drawing, complex animations

3. Backend Architecture (Weight: 12%)

Score	Description
1-2	Single API server, CRUD operations
3-4	API server + background jobs, basic business logic
5-6	Multiple services, message queues, event-driven patterns
7-8	Microservices, complex orchestration, distributed transactions
9-10	Event sourcing, CQRS, saga patterns, custom protocols

4. Data Model (Weight: 10%)

Score	Description
1-2	3-5 simple entities, basic relationships
3-4	5-15 entities, standard relationships, basic queries
5-6	15-30 entities, complex relationships, aggregations
7-8	Multi-database strategy, data pipelines, migrations at scale
9-10	Graph relationships, time-series data, complex analytics

5. Integrations (Weight: 12%)

Score	Description
1-2	0-1 integrations, well-documented APIs
3-4	2-4 integrations, standard REST APIs
5-6	5-8 integrations, some with webhooks or OAuth
7-8	8-15 integrations, custom protocols, data sync
9-10	15+ integrations, legacy systems, bidirectional sync

6. Authentication & Security (Weight: 10%)

Score	Description
1-2	Basic email/password login, no sensitive data
3-4	Social login, password reset, basic input validation
5-6	MFA, API keys, rate limiting, encrypted data at rest
7-8	SSO/SAML, audit logging, field-level encryption
9-10	Compliance-driven security (HIPAA, PCI), pen testing required

7. Infrastructure & Deployment (Weight: 8%)

Score	Description
1-2	Single platform deploy (Vercel, Netlify), no scaling needs
3-4	Simple CI/CD, staging environment, basic monitoring
5-6	Multi-service deployment, auto-scaling, infrastructure as code
7-8	Multi-region, custom networking, Kubernetes
9-10	Multi-cloud, disaster recovery, zero-downtime deployments

8. Real-time Features (Weight: 10%)

Score	Description
1-2	No real-time needs, standard request-response
3-4	Simple notifications or status updates (polling or SSE)
5-6	Live chat, real-time dashboards (WebSocket)
7-8	Collaborative editing, presence indicators, live cursors
9-10	Video/audio streaming, multiplayer, conflict resolution (CRDT)

9. AI/ML Components (Weight: 12%)

Score	Description
1-2	No AI, or single API call to an LLM
3-4	Simple agent with 1-2 tools, basic RAG
5-6	Multi-tool agent, vector search, conversation memory
7-8	Multi-agent system, custom fine-tuning, evaluation pipeline
9-10	Custom model training, real-time ML inference, complex orchestration

10. Regulatory & Compliance (Weight: 8%)

Score	Description
1-2	No regulatory requirements, general SaaS terms
3-4	Basic GDPR compliance (privacy policy, data deletion)
5-6	GDPR with right-to-erasure, cookie consent, data processing agreements
7-8	Industry-specific compliance (HIPAA, PCI-DSS), audit requirements
9-10	Multi-jurisdiction compliance, SOC 2, data residency requirements

---

Agent/Hybrid Project Adjustments

For projects with type agent or hybrid, factor 9 (AI/ML Components) gets additional weight. Adjust:

Factor	Standard Weight	Agent/Hybrid Weight
AI/ML Components	12%	20%
Backend Architecture	12%	10%
Frontend Complexity	10%	6%
Real-time Features	10%	8%

All other factors keep their standard weights. Re-normalize to 100%.

---

Calculation

Overall Score = Σ (factor_score × factor_weight) for all 10 factors

Example

Factor	Score	Weight	Weighted
User Roles	3	8%	0.24
Frontend	5	10%	0.50
Backend	4	12%	0.48
Data Model	4	10%	0.40
Integrations	6	12%	0.72
Auth & Security	3	10%	0.30
Infrastructure	2	8%	0.16
Real-time	3	10%	0.30
AI/ML	5	12%	0.60
Compliance	2	8%	0.16
Total		100%	3.86 → 4 (Moderate)

---

Output Format

When presenting a complexity assessment, be comprehensive and thorough:

1. Overall Score (REQUIRED)

Format:

Complexity: X.Y/10 — [Label]

[Label] = Simple (1-3) | Moderate (4-5) | Advanced (6-7) | Very Advanced (8-10)

Show calculation explicitly:

Weighted Overall: (score₁×weight₁ + score₂×weight₂ + ... + score₁₀×weight₁₀) / 100 = X.Y

Example: (3×8 + 5×10 + 4×12 + 4×10 + 6×12 + 3×10 + 2×8 + 3×10 + 5×12 + 2×8) / 100 = 3.86 → 4

2. 10-Factor Breakdown Table (MUST be comprehensive)

Each factor MUST have detailed justification (2-3 sentences minimum):

#	Factor	Weight	Score	Justification
1	User Roles & Permissions	8%	X	Why this score: [Explain the specific roles and permission model]. What makes it this complex: [Reference specific requirements from the architecture]. Impact on build: [How this affects development effort].
...	...	...	...	...

Example of thorough justification:

| 1 | User Roles & Permissions | 8% | 4 | **Why this score:** Three distinct roles (Admin, Member, Viewer) with workspace-scoped permissions. **What makes it this complex:** Requires Row Level Security policies in PostgreSQL for each table, plus UI permission checks. Not multi-tenant, so organization-level complexity is avoided. **Impact on build:** Adds 20-30% to auth setup time compared to single-role app; RLS policies require careful testing. |

DO NOT use one-line justifications like:

• ❌ "Simple CRUD operations" (too vague)
• ❌ "Standard REST API" (not specific)
• ❌ "Uses PostgreSQL" (states obvious)

DO use specific, detailed justifications like:

• ✅ "8 database tables with foreign key relationships and soft deletes. Requires migration strategy for position field (used for Kanban ordering). Indexes needed for workspace_id + created_at queries that power the activity feed."
• ✅ "WebSocket subscriptions for real-time task updates. Optimistic UI updates with conflict resolution when multiple users edit the same task. Requires careful state management to handle stale data on reconnection."

3. Risk Analysis (MANDATORY if any factors score 7+)

For each high-risk factor (scored 7+), provide comprehensive analysis:

Format:

⚠️ High Risk Factor: [Factor Name] (Score: X/10)

Why it scored high:
[Explain in 3-4 sentences what specific aspects of the requirements pushed this score to 7+. Reference concrete requirements from the architecture manifest.]

Specific risks this introduces:
- Risk 1: [Specific technical risk with probability and impact]
- Risk 2: [Development timeline risk with specific delay estimate]
- Risk 3: [Maintenance or scaling risk with quantified impact]
- Risk 4: [Integration or dependency risk]

Concrete mitigation strategies:
1. [Specific action] — Reduces risk by [X%] or [Y weeks], requires [effort estimate]
2. [Specific action] — [Measurable impact on risk]
3. [Specific action] — [Measurable impact on risk]

Estimated effort to mitigate:
- Total additional development time: [X hours/days/weeks]
- When to implement: [Pre-launch / Month 1 / After MVP]
- Who needs to do it: [Required skill level/role]

Example:

⚠️ High Risk Factor: Real-time Features (Score: 8/10)

Why it scored high:
The app requires WebSocket subscriptions for live Kanban board updates with drag-and-drop position changes. Multiple users can be viewing and editing the same board simultaneously, requiring conflict resolution. The optimistic UI updates must handle stale data when a user reconnects after network interruption. This goes beyond simple notifications into collaborative editing territory.

Specific risks this introduces:
- Race conditions: 60% chance of position conflicts if 3+ users drag tasks simultaneously → users see tasks jump around or disappear
- Stale state risk: 40% chance of showing outdated task status after reconnection → users make decisions on wrong data
- Performance degradation: WebSocket connections at 500+ concurrent users may hit Supabase Realtime limits → $25/mo tier supports ~500, need Team tier ($599/mo) beyond that
- Development delays: First implementation attempt will likely have bugs → add 2-3 weeks for testing and edge case handling

Concrete mitigation strategies:
1. Use battle-tested library (@supabase/realtime-js with built-in reconnection) — Reduces implementation risk by 70%, costs 0 extra (already included), saves 1-2 weeks vs custom WebSocket
2. Implement position debouncing (batch updates every 300ms) — Reduces race conditions by 80%, adds 8 hours development, minimal UX impact
3. Always refetch board state on reconnection — Eliminates stale state risk, adds 4 hours development, costs ~100ms on reconnect (acceptable)
4. Add optimistic update rollback on conflict — Reduces UX confusion by 90%, adds 1-2 days development
5. Load test with 100 simulated concurrent users before launch — Identifies scaling issues early, costs 1 day testing

Estimated effort to mitigate:
- Total additional development time: 1.5-2 weeks on top of base real-time implementation
- When to implement: During sprint 2 (real-time sprint) — don't defer
- Who needs to do it: Developer with WebSocket/real-time experience (senior or mid with guidance)

4. Simpler Alternatives (MANDATORY if overall score > 6)

When complexity is high, suggest 2-3 specific ways to reduce it:

Format for each alternative:

Alternative #X: [Short descriptive name]

What to remove or simplify:
- [Specific feature to cut or simplify]
- [Specific feature to cut or simplify]
- [Specific feature to cut or simplify]

New projected complexity score:
- Before: X.Y/10 ([Label])
- After: Z.W/10 ([Label])
- Reduction: ΔX.Y points

Which factors improve:
| Factor | Before | After | Change |
|--------|--------|-------|--------|
| [Name] | X | Y | -Z |
| [Name] | X | Y | -Z |

Trade-offs (what you lose):
- [Business impact of removing feature 1]
- [Business impact of removing feature 2]
- [User experience impact]
- [Competitive disadvantage, if any]

Effort savings:
- Development time: [X weeks → Y weeks, saves Z weeks]
- Cost savings: $[Amount] (based on [hourly rate assumption])
- Time to market: [X% faster]

Recommendation:
[When this alternative makes sense vs when to stick with original plan]

Example:

Alternative #1: Polling Instead of Real-Time WebSockets

What to remove or simplify:
- Remove WebSocket subscriptions for live board updates
- Replace with 5-second polling for task changes
- Keep immediate optimistic updates (feels real-time to current user)
- Other users see changes within 5 seconds instead of instantly

New projected complexity score:
- Before: 6.8/10 (Advanced)
- After: 5.2/10 (Moderate)
- Reduction: 1.6 points

Which factors improve:
| Factor | Before | After | Change |
|--------|--------|-------|--------|
| Real-time Features | 8 | 4 | -4 (biggest impact) |
| Backend Architecture | 6 | 5 | -1 (simpler server) |
| Infrastructure | 5 | 4 | -1 (fewer moving parts) |

Trade-offs (what you lose):
- Collaboration UX: Users don't see each other's changes instantly (5s delay vs real-time)
- Server load: Increased HTTP requests (5-10x more than WebSocket), but still manageable at 500 users
- Battery/data: Mobile users consume more data and battery due to polling
- Competitive weakness: Many modern project tools (Linear, Notion) have real-time updates

Effort savings:
- Development time: 12 weeks → 9 weeks (saves 3 weeks on real-time complexity)
- Cost savings: $12,000-18,000 (based on contractor at $100-150/hr)
- Time to market: 25% faster

Recommendation:
Use this alternative if:
- Time to market is critical (need to launch in <3 months)
- Budget is constrained (<$50K total)
- Target users typically work solo or async (5s delay doesn't matter)
- Team lacks real-time/WebSocket expertise

Stick with WebSockets if:
- Real-time collaboration is a core value proposition
- Competing with tools like Linear, Notion, or Monday
- Have budget and timeline for proper implementation
- Planning to scale to 5K+ users (polling becomes expensive)

5. Build Path Recommendation (REQUIRED)

Based on complexity score, provide specific build path options:

Format:

Recommended Build Path: [Primary option]

Score X.Y/10 ([Label]) suggests:

Option A: [Recommended approach] ⭐
- Who: [Developer level/team size]
- Timeline: [Duration range]
- Cost: $[Range]
- Tools: [Specific stack/frameworks]
- Risk: [Low/Medium/High]
- Best for: [When this makes sense]

Option B: [Alternative approach]
- Who: [Developer level/team size]
- Timeline: [Duration range]
- Cost: $[Range]
- Tools: [Specific stack/frameworks]
- Risk: [Low/Medium/High]
- Best for: [When this makes sense]

Option C: [Another alternative]
- Who: [Developer level/team size]
- Timeline: [Duration range]
- Cost: $[Range]
- Tools: [Specific stack/frameworks]
- Risk: [Low/Medium/High]
- Best for: [When this makes sense]

⚠️ NOT Recommended: [Approaches to avoid]
- [Why certain approaches won't work for this complexity level]

Guidelines by complexity score:

Simple (1-3):

Option A: AI Builder Tools ⭐
- Who: Non-technical founder or junior developer
- Timeline: 1-3 weeks
- Cost: $0-5K (mostly tool subscriptions)
- Tools: Cursor AI, v0.dev, Bolt.new, Replit Agent
- Risk: Low — well-trodden path, lots of examples
- Best for: MVPs, internal tools, validating idea quickly

Option B: No-Code Platforms
- Who: Non-technical founder
- Timeline: 1-2 weeks
- Cost: $0-2K (platform fees)
- Tools: Bubble, Webflow, Softr, Glide
- Risk: Very Low — no code to maintain
- Best for: Non-technical teams, tight budget, need to pivot quickly

Option C: Solo Junior Developer
- Who: 1 junior dev with mentorship
- Timeline: 4-8 weeks
- Cost: $8K-25K
- Tools: Next.js + Supabase + shadcn/ui (tutorial-friendly stack)
- Risk: Medium — may need senior code review
- Best for: Learning opportunity, have senior available for review

⚠️ NOT Recommended: Agency ($50K+) — severe overkill for simple project

Moderate (4-5):

Option A: Experienced Solo Developer ⭐
- Who: 1 senior full-stack developer
- Timeline: 8-16 weeks
- Cost: $30K-80K (contractor rates)
- Tools: Modern full-stack framework (Next.js, SvelteKit, etc.) + managed services
- Risk: Medium — single point of failure, but manageable scope
- Best for: Clear requirements, founder can provide quick feedback

Option B: Small Team (2 developers)
- Who: 1 full-stack + 1 specialist (frontend or backend focus)
- Timeline: 6-12 weeks
- Cost: $50K-120K
- Tools: Same as Option A, with better division of labor
- Risk: Low-Medium — knowledge sharing, faster delivery
- Best for: Tight timeline, need specialist skills (design-heavy or complex backend)

Option C: Freelance Agency
- Who: Small agency (2-4 people)
- Timeline: 8-12 weeks
- Cost: $60K-150K
- Tools: Agency's preferred stack
- Risk: Low — experienced team, proven process
- Best for: First-time founders who want managed delivery

⚠️ NOT Recommended:
- AI builders alone — too complex for fully automated build
- Junior-only team — needs senior oversight for quality
- Big agency — $200K+ is overkill for moderate complexity

Advanced (6-7):

Option A: Focused Development Team ⭐
- Who: 2-3 developers (1 senior + 1-2 mid-level)
- Timeline: 12-24 weeks
- Cost: $100K-250K
- Tools: Production-grade stack with observability (Sentry, Datadog)
- Risk: Medium — complex enough to need active management
- Best for: Funded startup, clear product-market fit signal

Option B: Development Agency
- Who: Agency team (3-5 people: dev + design + PM)
- Timeline: 12-20 weeks
- Cost: $150K-350K
- Tools: Agency's battle-tested stack
- Risk: Low-Medium — managed process, design included
- Best for: Non-technical founders, need full-service

Option C: Staged Delivery (MVP → Full)
- Who: Start with 1-2 devs, expand to 3-4 after MVP
- Timeline: 8 weeks MVP + 16 weeks full build
- Cost: $50K MVP + $100K-200K full = $150K-250K total
- Tools: Choose stack that scales (avoid cutting corners)
- Risk: Medium — longer total timeline, but validates before full investment
- Best for: Uncertain product-market fit, want to validate before full build

⚠️ NOT Recommended:
- Solo developer — too much for one person, high burnout risk
- AI builders — not sophisticated enough for advanced features
- Offshore-only team without US PM — coordination overhead kills timeline

Very Advanced (8-10):

Option A: Dedicated Product Team ⭐
- Who: 4-6 developers + 1 PM + 1 designer
- Timeline: 24-40 weeks (6-10 months)
- Cost: $300K-800K
- Tools: Enterprise-grade stack with full observability, staging environments, comprehensive testing
- Risk: Medium-High — manage like a startup, not a project
- Best for: Well-funded startup, proven market, long-term product

Option B: Specialized Agency
- Who: Agency with specific domain expertise (e.g., healthcare, fintech, AI)
- Timeline: 24-36 weeks
- Cost: $400K-1M+
- Tools: Compliance-ready stack for your industry
- Risk: Medium — higher cost but expertise included
- Best for: Regulated industries, need compliance expertise

Option C: Phased Delivery with External + Internal
- Who: Start with agency (12 weeks), transition to internal team (ongoing)
- Timeline: 12 weeks agency MVP + ongoing internal development
- Cost: $200K agency + $500K-1M internal team (first year) = $700K-1.2M
- Tools: Choose stack your internal team can maintain
- Risk: Medium — transition risk, but builds internal capability
- Best for: Series A+ startups building core product team

⚠️ NOT Recommended:
- Small team (<4 people) — will underestimate complexity and miss deadline
- AI builders or no-code — cannot handle this complexity level
- Fixed-price contract — scope will change, use time & materials
- Offshore without strong US-based tech lead — communication overhead is fatal at this complexity

6. Calculation Transparency (ALWAYS show)

Always show the full calculation:

Complexity Calculation:

Factor 1 (User Roles): score × weight = X × 8% = Y
Factor 2 (Frontend): score × weight = X × 10% = Y
Factor 3 (Backend): score × weight = X × 12% = Y
Factor 4 (Data Model): score × weight = X × 10% = Y
Factor 5 (Integrations): score × weight = X × 12% = Y
Factor 6 (Auth & Security): score × weight = X × 10% = Y
Factor 7 (Infrastructure): score × weight = X × 8% = Y
Factor 8 (Real-time): score × weight = X × 10% = Y
Factor 9 (AI/ML): score × weight = X × 12% = Y
Factor 10 (Compliance): score × weight = X × 8% = Y
                                          ─────────
Total weighted score:                     = Z.ZZ

Rounded to one decimal: Z.Z/10 — [Label]