Technical Decision Guide

Technical Decision Guide

Purpose

Guide PMs through key technical architecture decisions when building with AI coding assistants. Translates technical trade-offs into product-management terms: speed vs control, cost vs scale, simplicity vs flexibility. Helps you make good enough decisions quickly without needing a deep engineering background.

Domain Context

For PM-builders, "good enough architecture" beats "perfect architecture." The goal is an architecture that: (1) gets to working prototype fast, (2) doesn't create painful technical debt for the first 12 months, (3) can be handed off to engineers without a full rewrite.

This guide uses decision trees — answer simple questions to get a recommendation. Each decision includes a PM-friendly explanation of the trade-offs, what you'll regret if you choose wrong, and what to say to an AI coding assistant to implement the recommendation.

The PM Architecture Principle: Optimize for developer experience at prototype stage, not theoretical scale. The bottleneck for PM-builder projects is almost never the database or hosting choice — it's the speed of iteration. Choose the stack that lets you move fastest while staying on a path engineers can take over.

When to Use

• Use when choosing a database for your prototype
• Use when deciding between hosting options
• Use when picking an auth approach
• Use when deciding how to structure your backend
• Use when an AI coding assistant asks you to make an architectural choice
• Use when you're comparing two options and don't know the meaningful trade-offs

When NOT to Use

• Don't use for enterprise-scale systems (work with a solutions architect)
• Don't use when you already have an engineering team with preferences (ask them instead)
• Don't use when the decision involves compliance requirements (HIPAA, SOC2, GDPR) — consult a security engineer

Instructions

You are helping a PM-builder make a technical decision for $ARGUMENTS.

Before recommending any specific tool or service, check what's already known from the conversation context or $ARGUMENTS. Only ask questions whose answers aren't already clear. If the user has already shared their project description, tools, stack, or preferences (e.g., in a prior /plan-prototype or /vibe-spec session), use that context and skip to the relevant decision.

If key context is missing, ask:

1. "What are you building? Give me a one-sentence description."
2. "Are you already using any tools, services, or platforms for this project? (e.g., a specific database, hosting platform, auth provider)"
3. "Do you have any constraints — budget, team preferences, compliance requirements, or existing infrastructure you need to integrate with?"
4. "How comfortable are you with technical setup? (e.g., prefer managed services with minimal config, comfortable with some setup, experienced with infrastructure)"

Use their answers to tailor recommendations below. If the user already has preferences or existing tools, work with those — only suggest alternatives if there's a clear mismatch with their project needs, and explain the trade-off.

Then ask which decision they need help with, and provide a structured guide:

Decision 1: Database Selection

Decision tree:

1. Does your data have lots of relationships (users → projects → tasks)? → PostgreSQL (Supabase, Neon, Railway)
2. Is your data mostly JSON/documents with varying structure? → MongoDB (Atlas) or Firestore
3. Do you need real-time sync pushed to the frontend without polling? → Firebase Firestore or Supabase (realtime subscriptions)
4. Just need a simple key-value or session store? → Redis (Upstash serverless) or SQLite (for single-server apps)
5. Working with lots of files/images/video? → Use a CDN (Cloudflare R2, AWS S3, Supabase Storage) alongside a relational DB

Detailed options:

How to recommend: Based on the user's answers about their project and comfort level, recommend the option that best fits. If the user is already using a database, work with it unless there's a clear problem. Present trade-offs rather than a single "right answer."

What to tell your AI: Provide the connection details as environment variables. Use the database's official client library rather than raw SQL where available.

Decision 2: Hosting & Deployment

Decision tree:

1. Is your app built with Next.js? → Vercel (first choice, seamless integration)
2. Do you need a full backend server (Node.js, Python, Docker)? → Railway or Render
3. Do you need to run a Docker container? → Fly.io or Railway
4. Is it a quick demo that doesn't need to be always-on? → Replit or Glitch
5. Do you need background jobs or cron? → Railway or Render (not Vercel serverless)

Detailed options:

How to recommend: Match the hosting platform to the user's framework and needs. If they're already deployed somewhere, work with that platform unless there's a clear limitation. Present the trade-offs (cost, cold starts, complexity) and let the user choose.

Cold start warning: Some free-tier hosting platforms spin down after inactivity and take 30+ seconds to wake up. This is fine for a portfolio project; it's unacceptable for sharing with real users. Ask the user about their use case before recommending a free tier.

Decision 3: Authentication

Decision tree:

1. Are you already using Supabase? → Supabase Auth (already included, no extra setup)
2. Do you need social login (Google, GitHub) with a polished UI out of the box? → Clerk
3. Are you using a Next.js app and want full control? → NextAuth.js / Auth.js
4. Are you using Firebase/Firestore? → Firebase Auth
5. Do you need enterprise SSO, SAML, or advanced permissions? → Auth0
6. Never → Roll your own (authentication is security-critical, never DIY for a prototype)

Detailed options:

How to recommend: Never build auth yourself for a prototype — always use an established auth provider. If the user is already using a platform that includes auth (e.g., a backend-as-a-service with built-in auth), use that for lowest friction. If choosing fresh, ask about their needs: Do they need social login? Pre-built UI components? Enterprise SSO? Match the recommendation to those needs.

Decision 4: Monolith vs Microservices

For PM-builders: Always start monolith. No exceptions.

Microservices are an organizational scaling solution designed for teams of 20+ engineers working on the same codebase. For a solo PM-builder or small team, microservices add:

• Deployment complexity (multiple services to manage)
• Network latency (services calling each other over HTTP)
• Debugging difficulty (errors span multiple services)
• Infrastructure cost (multiple servers)

What to build instead: A modular monolith — a single deployment unit with clean internal modules/folders separating concerns (e.g., /lib/auth, /lib/payments, /lib/notifications). This gives you the organizational benefits of microservices without the operational overhead. Engineers can extract services later if actually needed.

Rule of thumb: If you don't have at least 3 full-time engineers dedicated to a single service, that service shouldn't exist as a separate microservice.

Decision 5: API Design — REST vs GraphQL

For PM-builders: Use REST. Almost universally.

REST advantages for PM-builders:

• AI coding assistants generate better REST code (more training data)
• Easier to debug (each endpoint does one thing)
• Every developer understands it
• Better tooling for testing (Postman, curl, browser)
• Simpler caching

GraphQL advantages (only relevant when you have these problems):

• Complex data fetching needs across many related entities
• Mobile clients with strict bandwidth constraints
• Multiple frontend teams with different data needs
• You have backend engineers who know GraphQL

REST best practices for PM-builder projects:

• Use nouns for resources: /api/users, /api/projects (not /api/getUsers)
• Use HTTP verbs: GET (read), POST (create), PUT/PATCH (update), DELETE (delete)
• Return consistent JSON shape: { data: {...}, error: null } or { data: null, error: "message" }
• Version your API from day one: /api/v1/... (makes future changes non-breaking)
• Use plural nouns for collections: /api/users not /api/user
• Return the created/updated object in POST/PUT responses (not just a success message)

Decision 6: Frontend Framework

Decision tree:

1. Do you want the fastest possible start with AI assistance? → Next.js (most AI training data, best ecosystem)
2. Do you need a simple single-page app with no backend? → Vite + React (lighter than Next.js)
3. Is this a landing page only? → Next.js with static export, or even just HTML + Tailwind
4. Is this a mobile app? → React Native (with Expo for easier setup) or Flutter
5. Do you want to avoid JavaScript frameworks entirely? → SvelteKit (simpler mental model)

How to recommend: Next.js with TypeScript has the broadest AI training data, meaning most AI coding assistants produce better code with it. However, if the user already knows or prefers a different framework, work with that — the best framework for a PM-builder is often the one with the least friction, not the theoretically optimal one. Ask about their experience before recommending.

If the user has no preference: Recommend the framework with the strongest AI code-generation support and ecosystem for their project type. Explain why, but make it clear they can change if it doesn't feel right.

Decision 7: Payments

How to recommend: For most PM-builder prototypes, a well-established payment processor with good documentation and AI training data coverage is the safest choice. Ask the user: "Are you handling subscriptions, one-time payments, or usage-based billing? Do you need to handle international tax/VAT?" Match the recommendation to their payment model. Never roll your own payment processing — security and compliance requirements make this dangerous and complex.

What to tell your AI: Use the payment provider's hosted checkout UI rather than building a custom card form. Store the customer ID and subscription status on the user record.

Output Format

Decision recommendations with rationale, trade-offs, and specific tool recommendations tailored to the user's stated needs, preferences, and existing tools. Written for a PM audience. Each decision includes what to say to your AI coding assistant to implement it. When the user is struggling with a recommended tool mid-build, proactively offer alternatives: "It sounds like [tool] isn't working well for your situation. Based on what you need, [alternative] might be a better fit because [reason]. Want to try switching?"