Tech Stack Evaluation#

Evaluate whether a project's current tech stack is appropriate for its goals, and recommend alternatives when maintainability, performance, or feature expansion is blocked.

When to Use#

• User asks: "is there a better tech stack for this?", "what stack should I use?", "should we rewrite this?"
• User expresses maintainability pain: "hard to extend", "unwieldy", "everything is coupled"
• Pre-planning a new feature that the current stack can't support
• Considering a migration from prototype to production-grade

When NOT to Use#

• The user has a specific bug to fix — use debug-issue instead
• The user wants a new feature built on the current stack — use draft-feature-plan
• The project is trivial (< 20 files) — just read the files and suggest directly

Workflow#

1. Diagnose the real problem#

Before recommending a stack change, understand what the user is actually solving for. Ask (or infer from context):

ConcernSignalTypical FixPerformance"slow on large datasets", "takes forever to load"Optimize data layer (Polars, DuckDB, caching), not necessarily frontend frameworkMaintainability"hard to extend", "everything is coupled", "adding a feature touches 4 files"Structural refactor (split monoliths, consolidate APIs, add type safety)Feature expansion"need real-time updates", "need multi-user", "need mobile app"Add capabilities (WebSocket, DB persistence, React Native)Team growth"onboarding new developers", "need documentation"Add types, tests, component library, not necessarily new frameworkDeployment/hosting"Railway is expensive", "need to scale"Evaluate hosting alternatives, containerization, serverlessModernization"this feels old", "want to use current best practices"Incremental upgrades (TypeScript, testing, CI) rather than rewrite

Critical insight: Most "tech stack" questions are actually maintainability or structural questions. A React rewrite won't fix a 1,400-line monolithic processor. A type system won't help if the API has 51 endpoints where 15 would suffice.

2. Run a maintainability assessment#

Use the codebase-survey skill's maintainability audit to produce evidence:

bash

# File size audit
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.tsx" \) -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/venv/*" | xargs wc -l | sort -rn | head -20

# Method/function count audit
grep -c "def " app/core/allocation.py          # Python methods
grep -c "@router." app/api/routes.py            # FastAPI endpoints
grep -c "function " app/static/js/charts.js     # JS functions

Produce a maintainability grade (A-F) with specific targets.

3. Map the current stack#

LayerCurrentWhat it does wellWhat it blocksBackend frameworkData processingFrontendState managementStylingCharts/visualizationHostingPersistence

4. Recommend options, not a single answer#

Present 2-3 options ordered by effort vs. payoff:

OptionEffortPayoffWhen to chooseMinimal (structural refactor)LowMediumMaintainability is the only concern, stack is otherwise fineIncremental (modernize frontend)MediumHighFrontend is the pain point, backend is solidFull (new stack)HighMaximumMultiple blockers, team growth, or multi-platform needs

For each option, specify:

• What changes
• What stays the same
• Migration path (can it be done incrementally?)
• Risk (data loss, downtime, learning curve)

5. Tie recommendations to the assessment#

Every recommendation must reference the evidence:

• "Split AllocationProcessor (1,402 lines, 36 methods) into 5 focused processors" — not "use a better framework"
• "Consolidate 51 API endpoints into ~15 with a chart registry" — not "add GraphQL"
• "Migrate frontend to React + TypeScript for component isolation and type safety" — not "React is better"

Common Stack-Specific Patterns#

Python FastAPI + Pandas + Vanilla JS Dashboards#

This is a common pattern for data-heavy internal tools. The typical evolution:

StageStackPain PointNext Step1FastAPI + Pandas + Vanilla JSWorks for 1-2 users, 5-10 chartsNone needed2Same stack, files growAdding charts requires 4-file changesSplit processors, consolidate API3Same stack, 30+ charts, multi-userNo persistence, no sharing, frontend is spaghettiAdd React + TypeScript, consider DB4Growth continuesPerformance issues with large datasetsPolars/DuckDB, caching, materialized views

When to keep FastAPI#

Keep FastAPI when:

• Data processing is the core value (Pandas/Polars/NumPy workflows)
• The team knows Python well
• The app is internal/BI, not customer-facing
• Deployment is simple (Railway, Heroku)

When to add React#

Add React when:

• The dashboard has 10+ interactive views
• Multiple developers work on different tabs
• You need reusable components (filters, tables, export buttons)
• Type safety across the API boundary matters

When to add a database#

Add persistence when:

• Multi-user collaboration is needed
• Historical data/query snapshots matter
• Session loss on restart is unacceptable
• You need user accounts, permissions, or audit logs

Anti-patterns to Avoid#

1. Recommending a rewrite when a refactor suffices. If the backend logic is solid but the frontend is messy, don't suggest rewriting the whole stack. Isolate the problem.
2. Recommending new tech without evidence. "Use Next.js" is not a recommendation. "Migrate to Next.js because the current vanilla JS has 45 nearly-identical API loader functions that a React + TanStack Query stack would collapse to 5" is.
3. Ignoring the user's domain expertise. If the user built a complex system in 10 weeks, their velocity is not standard. Recommendations should match their throughput model, not a typical team's.
4. Forgetting deployment constraints. A recommendation that requires Kubernetes when the user uses Railway is not actionable.
5. Not considering the data model. Stateless file-upload apps have different needs than multi-tenant SaaS. Don't suggest Postgres for a project that genuinely doesn't need persistence.

Verification Checklist#

• Real problem diagnosed (performance vs. maintainability vs. features vs. team)
• Maintainability assessment completed with file size/method counts
• Current stack mapped with pros/cons per layer
• 2-3 options presented with effort/payoff/risk
• Every recommendation tied to specific evidence from the assessment
• Migration path is incremental (not all-or-nothing)
• Deployment constraints considered
• User's velocity and expertise factored in