Coded MVP Architecture Templates

Purpose

This recipe scaffolds a production-ready MVP codebase using one of three proven architectures — Next.js + Supabase (recommended for web SaaS), React + Firebase (best for real-time/mobile-first), or Flask + PostgreSQL (best for API-first products). The output is a deployed application with authentication, database, API routes, and CI/CD — ready for feature development within 60 minutes. [src1]

Prerequisites

• Product requirements or feature list — at minimum, a list of core user actions the MVP must support
• Tech stack decision — from MVP Tech Stack Selection Guide or user preference
• Node.js 18+ installed (for Next.js/React paths) — nodejs.org
• Python 3.10+ installed (for Flask path) — python.org
• Git installed and configured with GitHub account
• Package manager — npm 9+ or pnpm 8+ (Node paths), pip + venv (Python path)

Constraints

• Supabase free tier allows 500 MB database and 50,000 MAU — sufficient for MVP validation but plan upgrade path before launch. [src6]
• Firebase Spark plan limits Firestore to 1 GiB storage and 50,000 daily document reads — exceeding this triggers billing on Blaze plan. [src3]
• Next.js App Router (v14+) defaults to server components — client interactivity requires explicit "use client" directives. [src2]
• Flask requires a WSGI server (Gunicorn) for production — never deploy with the built-in development server. [src4]
• All stacks: configure environment variables via .env.local (Next.js) or .env (Flask) — never commit secrets to version control.

Tool Selection Decision

Which stack?
├── Web SaaS with complex queries AND free tier priority
│   └── PATH A: Next.js + Supabase (PostgreSQL, SQL, Row Level Security)
├── Real-time app OR mobile-first AND rapid prototyping priority
│   └── PATH B: React (Vite) + Firebase (Firestore, real-time sync, offline)
├── API-first product OR Python ML/AI integration
│   └── PATH C: Flask + PostgreSQL (REST API, SQLAlchemy ORM, full control)
└── Unsure
    └── DEFAULT: Path A (Next.js + Supabase)

Execution Flow

Step 1: Scaffold the Project

Duration: 5-10 minutes · Tool: CLI

Path A — Next.js + Supabase:

# Create Next.js project with Supabase template
npx create-next-app@latest my-mvp -e with-supabase
cd my-mvp
npm install @supabase/supabase-js @supabase/ssr

Path B — React + Firebase:

npm create vite@latest my-mvp -- --template react-ts
cd my-mvp && npm install
npm install firebase react-router-dom

Path C — Flask + PostgreSQL:

mkdir my-mvp && cd my-mvp
python -m venv venv && source venv/bin/activate
pip install flask flask-sqlalchemy flask-migrate flask-login flask-jwt-extended flask-cors psycopg2-binary gunicorn

Verify: Run npm run dev (Path A/B) or flask run (Path C) and see the default page. · If failed: Check Node.js/Python version. Delete node_modules and reinstall.

Step 2: Configure Authentication

Duration: 10-15 minutes · Tool: Code editor + platform dashboard

Path A: Use @supabase/ssr for cookie-based auth with server components. Enable providers in Supabase Dashboard: Authentication → Providers. [src1]

Path B: Initialize Firebase Auth with modular SDK v9+. Create an AuthContext provider wrapping the app. Enable providers in Firebase Console. [src3]

Path C: Use Flask-Login for session management and Flask-JWT-Extended for API tokens. Hash passwords with Werkzeug. [src4]

Verify: Create a test account, log in, verify session persists on refresh, log out. · If failed: Check environment variables and OAuth redirect URIs.

Step 3: Set Up Database Schema

Duration: 5-10 minutes · Tool: SQL Editor / Console / Flask-Migrate

Path A: Create tables in Supabase SQL Editor. Enable Row Level Security and create per-user access policies. [src1]

Path B: Define TypeScript interfaces for Firestore documents. Deploy security rules via firebase deploy --only firestore:rules.

Path C: Define SQLAlchemy models, run flask db init, flask db migrate, flask db upgrade.

Verify: Insert a test record and query it back. Confirm RLS/security rules block unauthorized access. · If failed: Check RLS is enabled (Supabase) or security rules are deployed (Firebase).

Step 4: Create Core API Routes

Duration: 10-15 minutes · Tool: Code editor

Path A: Create app/api/items/route.ts with GET/POST handlers using Supabase server client. [src2]

Path B: Create Firestore CRUD functions in src/lib/ using the modular Firestore API.

Path C: Create Flask Blueprint routes for CRUD operations with JWT-protected endpoints.

Verify: Test CRUD operations via browser or curl. Confirm auth middleware rejects unauthenticated requests. · If failed: Check client initialization and environment variables.

Step 5: Deploy to Staging

Duration: 5-10 minutes · Tool: CLI + platform dashboard

Path A — Vercel: Push to GitHub, run npx vercel, set environment variables in Vercel dashboard. [src5]

Path B — Firebase: Run firebase init hosting, npm run build, firebase deploy.

Path C — Railway: Run railway login, railway init, railway up. Set environment variables in dashboard.

Verify: Visit staging URL. Test login, create item, refresh, verify data persists. · If failed: Check build logs and environment variables. Add staging domain to auth redirect URLs.

Step 6: Add Error Monitoring

Duration: 5 minutes · Tool: Sentry

Install Sentry SDK: npm install @sentry/nextjs (Path A), npm install @sentry/react (Path B), or pip install sentry-sdk[flask] (Path C). Run the Sentry wizard to configure.

Verify: Trigger a test error and confirm it appears in Sentry within 30 seconds. · If failed: Verify Sentry DSN is correct.

Output Schema

{
  "output_type": "scaffolded_mvp_project",
  "format": "code repository + deployed URL",
  "columns": [
    {"name": "repository_url", "type": "string", "description": "GitHub repository URL", "required": true},
    {"name": "staging_url", "type": "string", "description": "Deployed staging URL", "required": true},
    {"name": "stack", "type": "string", "description": "Tech stack used", "required": true},
    {"name": "auth_providers", "type": "string", "description": "Enabled auth methods", "required": true},
    {"name": "database_tables", "type": "string", "description": "Core tables created", "required": true},
    {"name": "api_endpoints", "type": "string", "description": "Available API routes", "required": true}
  ],
  "expected_row_count": "1",
  "sort_order": "N/A",
  "deduplication_key": "repository_url"
}

Quality Benchmarks

If below minimum: Check for missing environment variables, unoptimized images, or client-side data fetching that should be server-side. Re-run Lighthouse and fix top 3 recommendations.

Error Handling

Cost Breakdown

Anti-Patterns

Wrong: Starting with custom authentication

Building your own auth takes 2-4 weeks and introduces security vulnerabilities. Every hour spent on custom auth is an hour not spent validating your core product hypothesis. [src6]

Correct: Use managed auth from day one

Supabase Auth, Firebase Auth, and Auth0 provide secure, battle-tested authentication in minutes. Migrate to custom auth only if you outgrow the managed service.

Wrong: Choosing Firebase for data-heavy SaaS with complex queries

Firestore requires composite indexes for every query permutation and cannot perform SQL JOINs. A SaaS dashboard with filters and aggregations becomes painful on Firestore by month 3. [src6]

Correct: Match database type to data access patterns

Use PostgreSQL (Supabase) for relational data with complex queries. Use Firestore for real-time sync and offline-first mobile apps. The database choice is the hardest to change later.

Wrong: Skipping Row Level Security or Firestore rules

Deploying without RLS or security rules means any authenticated user can access all data — a critical security vulnerability. [src1]

Correct: Configure access policies before first deploy

Write RLS policies or Firestore rules as part of schema setup, not as a post-launch task.

When This Matters

Use this recipe when a developer needs to go from zero to a deployed, authenticated MVP in under an hour. Requires a tech stack decision already made (or defaults to Next.js + Supabase). This recipe handles scaffolding, auth, database, and deployment — not feature implementation or UI design.