| 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]
