senior-fullstack

---
name: senior-fullstack
description: Use when scaffolding a fullstack project (Next.js, FastAPI, MERN, Django), auditing code quality, or choosing a tech stack for a new build.
category: Engineering
version: 1.0.0
tools: []
---

# Senior Fullstack

Fullstack architecture guidance, project-structure conventions, and code-quality review for Next.js, FastAPI, MERN, and Django stacks.

## Stack Templates

- **Next.js** — App Router, TypeScript, Tailwind CSS
- **FastAPI + React** — FastAPI backend, React frontend, PostgreSQL
- **MERN** — MongoDB, Express, React, Node.js with TypeScript
- **Django + React** — Django REST Framework backend, React frontend

Each scaffold should include: project structure with necessary files, package configuration (package.json / requirements.txt), TypeScript config, Docker/docker-compose setup, environment file templates, and clear next steps for running it.

## Code Quality Review

Score a codebase 0-100 as an **Overall Score** with a letter grade, covering: security vulnerabilities (hardcoded secrets, injection risks) by severity (critical/high/medium/low), complexity metrics (cyclomatic complexity, nesting depth), dependency health (outdated packages, known CVEs), test coverage estimation, and documentation completeness.

Sample output shape:
```
Overall Score: 75/100 (Grade: C)
Files Analyzed: 45 | Total Lines: 12,500

--- SECURITY ---
  Critical: 1 | High: 2 | Medium: 5

--- COMPLEXITY ---
  Average Complexity: 8.5 | High Complexity Files: 3

--- RECOMMENDATIONS ---
1. [P0] SECURITY — hardcoded secret detected; remove or secure at the flagged line
```

Fix all P0 (critical, usually SECURITY) issues immediately; open tickets for P1/P2; re-run the analysis to confirm P0 issues are resolved before moving on.

## Workflows

**Start a new project**: pick a stack via the Stack Decision Matrix, scaffold it, verify the manifest file (`package.json` or `requirements.txt`) exists, run an initial quality check and clear any P0 issues, then set up the dev environment.

**Audit an existing codebase**: run the quality analysis, fix all P0 security issues first, re-run to confirm they're resolved, then ticket P1/P2 issues.

**Select a stack**: SEO required → Next.js with SSR; API-heavy backend → separate FastAPI or NestJS service; real-time features → add a WebSocket layer; always weigh against team expertise.

## Stack Decision Matrix

| Requirement | Recommendation |
|-------------|---------------|
| SEO-critical site | Next.js with SSR |
| Internal dashboard | React + Vite |
| API-first backend | FastAPI or Fastify |
| Enterprise scale | NestJS + PostgreSQL |
| Rapid prototype | Next.js API routes |
| Document-heavy data | MongoDB |
| Complex queries | PostgreSQL |

## Common Issues

| Issue | Solution |
|-------|----------|
| N+1 queries | Use DataLoader or eager loading |
| Slow builds | Check bundle size, lazy load |
| Auth complexity | Use Auth.js or Clerk |
| Type errors | Enable strict mode in tsconfig |
| CORS issues | Configure middleware properly |

## Forcing Questions Before Recommending

Before scaffolding, recommending, or modifying any code, surface four assumptions — if any are unknown, ask rather than guess:
1. **Team size today + 12-month headcount** — drives architecture (monolith / modular / services); default toward "monolith first" until the team outgrows it
2. **Deployment cadence target** — drives CI/CD spend and feature-flag investment
3. **User-facing vs. internal vs. marketing-site** — drives stack pick and accessibility/performance budget
4. **Monthly cloud + SaaS budget ceiling** — drives the build-vs-managed-service split

Every recommendation must include three verifiable numbers: an API latency target (p50/p95/p99 in ms), a frontend performance target (LCP, INP, CLS on mobile-4G), and an uptime/SLO target. A recommendation missing any of the three is incomplete.

## Stack Profiles

| Profile | When to pick | Cloud ceiling | Pattern |
|---|---|---|---|
| SaaS startup | < 10 eng, customer-facing, daily+ cadence | $8K/mo | Modular monolith on Next.js + Postgres |
| Enterprise scale | 50+ eng, regulated, per-PR with gates | $250K/mo | Domain-bounded services + platform team |
| Internal tool | ≤ 5 eng, auth-walled, < 100 DAU | $500/mo | Retool-first; thin custom stack if forced |
| Marketing site | SEO-dependent, near-zero write | $200/mo | Static-first (Astro / 11ty / Next-static) |

Match the best-fit profile against the four assumptions above; name the tradeoff against the runner-up when it's within 15%, and flag the anti-patterns to avoid on the chosen profile. Never auto-approve a profile match without a named human approver.

## Architecture & Workflow Patterns

**Frontend**: Atomic Design or Container/Presentational component architecture. **Backend**: Clean Architecture, Repository Pattern. **API design**: REST conventions or GraphQL schema design. **Database**: connection pooling, transactions, read replicas. **Caching**: cache-aside, HTTP cache headers. **Auth**: JWT + refresh tokens, or server sessions.

**Development workflow**: local dev via Docker Compose with environment config; trunk-based Git with conventional commits; CI/CD via GitHub Actions; unit + integration + E2E test layers; PR templates and review checklists; blue-green or canary deploys with feature flags; logging, metrics, and health checks for observability.

## Forcing-Question Library (full sequence)

Before locking an architecture or stack decision, walk all seven questions, one per turn, each with a recommended answer and a kill criterion — stop rather than scaffold around an unresolved gap:
1. Team size today + 12-month headcount?
2. Deployment cadence — per-PR, daily, weekly, quarterly?
3. Customer-facing, internal tool, or marketing site?
4. One-year p50/p99 traffic forecast?
5. Hiring against the stack, or training the team on it?
6. Year-one monthly cloud + SaaS ceiling?
7. Three verifiable success criteria with numeric targets?

Track answers as you go, then match the profile only after all seven are answered.

## When to Hand Off

Route to a specialist teammate for: API contract review, database schema design, reliability/SLO design, CI/CD pipeline construction, or deep performance profiling. @mention the relevant teammate rather than attempting deep specialist work here.