GameCraftGameCraft

Quick Start

Get ProductReady running in 10 minutes - from zero to deployed

Quick Start

Welcome to ProductReady! 🚀 This guide will get you from zero to a working app in under 10 minutes.

New to ProductReady? Try Demo Mode first - no database setup required!

What You'll See

First, visit https://productready.dev to see the live demo.

After setup, ProductReady provides several pre-built pages ready to use. Here's what you can explore:

PageRouteDescriptionScreenshot
Landing Page/Marketing homepage with hero section, features, and CTAComing soon
Dashboard/dashboardMain application dashboard with task management and analyticsComing soon
Agent Tasks/agentAI agent task creation and monitoring interfaceComing soon
System Admin/systemadminSystem administration panel (requires admin privileges)Coming soon

Live Demo Available! Access all routes with ?demo=1 parameter (e.g., /dashboard?demo=1) to explore without authentication.

Quick Access Links:

  • 🏠 Landing Page: http://localhost:3000/
  • 📊 Dashboard: http://localhost:3000/dashboard (or /dashboard?demo=1)
  • 🤖 Agent Tasks: http://localhost:3000/agent (or /agent?demo=1)
  • ⚙️ System Admin: http://localhost:3000/systemadmin (or /systemadmin?demo=1)

Note: Screenshots will be added in the next documentation update. For now, start the dev server and explore these routes yourself!

Two Ways to Use ProductReady

ProductReady can help you in two scenarios:

🆕 New Project

Start from ProductReady boilerplate

You're building something new and want:

  • Production-ready foundation
  • Modern architecture out-of-box
  • AI-powered initialization
  • Best practices by default

Time: 5 min + AI setup

Jump to New Project Guide →

🔄 Existing Project

Adopt ProductReady patterns

You have an existing app and want to:

  • Modernize architecture
  • Add type-safe APIs (tRPC)
  • Improve auth (Better Auth)
  • Better database layer (Drizzle)

Time: 30-60 min + AI migration

Jump to Migration Guide →

Just exploring? Try Demo Mode first - no setup, 2 minutes to see everything!

Prerequisites

Before you start, make sure you have:

Using Windows? We recommend using WSL2 for the best experience.

New Project from ProductReady

Use this if you're starting from scratch.

Clone ProductReady

git clone https://github.com/mr-kelly/productready.git my-new-project
cd my-new-project/apps/productready
pnpm install

Use This AI Prompt

Copy and paste to GitHub Copilot, Claude, or Cursor:

Please help me **Initialize a Product Ready project** using the `apps/productready` boilerplate:

PHASE 1 - CLEANUP:
1. Read README.md and understand the project structure
2. Delete the changelog/ directory entirely (we'll start fresh)
3. Clean up content/docs/:
   - Keep only index.mdx in content/docs/en/ with a simple "# Welcome" placeholder
   - Keep only index.mdx in content/docs/zh-CN/ with "# 欢迎" placeholder
   - Delete all other .mdx files in both language folders
4. Update src/db/seed.ts:
   - Keep the demo user seeding (demo@productready.dev)
   - Remove all example posts seeding
   - Remove agent tasks seeding if not needed
5. Clean up spec/ directory:
   - Keep the directory structure
   - Clear contents of product-design.md, icp-guide.md, marketing-guide.md
   - We'll fill these in next

PHASE 2 - INITIALIZE MY PROJECT:
Project Name: [YOUR_PROJECT_NAME]
Description: [WHAT_YOU'RE_BUILDING]

Core Features:
- [FEATURE_1]
- [FEATURE_2]
- [FEATURE_3]

Target Users: [WHO_IS_THIS_FOR]

PHASE 3 - PLANNING:
After cleanup, create a detailed implementation plan with:
1. Database schema changes needed (modify src/db/schema/)
2. tRPC routers to create/modify (in src/server/routers/)
3. UI pages and components needed
4. Authentication/authorization requirements
5. API integrations needed

Please proceed with Phase 1 cleanup first, then ask me for project details for Phase 2.

Step 3: Iterate with AI

After AI completes the cleanup:

  1. Define your product: Fill in your project details when AI asks
  2. Review the plan: AI will create a todo list - review and adjust
  3. Start building: Work through todos with AI assistance
  4. Test frequently: Use pnpm dev to test changes locally

Example Conversation Flow

You: [paste the AI prompt above]

AI: ✅ Completed Phase 1 cleanup. Now, please tell me about your project:
    - What problem does it solve?
    - Who are your target users?
    - What are the core features?

You: I'm building a customer feedback tool for SaaS companies.
     Target users: Product managers and founders
     Features: Survey creation, response collection, sentiment analysis

AI: Great! I'll now update:
    - spec/product-design.md with your PRD
    - Database schema for surveys, responses, sentiment data
    - tRPC routers for CRUD operations
    - UI components for survey builder
    
    Here's the implementation plan: [detailed todos]
    
    Shall I proceed with the database schema changes?

You: Yes, but add a "tags" field to surveys for categorization

AI: ✅ Updated schema with tags. Here are the changes...

Iterate and Build

Benefits of AI setup:

  • ⚡ 10x faster than manual cleanup
  • 🎯 Smart planning - AI creates structured todos
  • 📝 Documentation - AI updates specs as you build
  • 🔄 Iterative - Refine requirements as you go
  • 🧠 Learning - AI explains what it's doing

Refactor Existing Project

Already have a codebase? Don't start from scratch - migrate to ProductReady's architecture!

When to Refactor vs Start Fresh

✅ Refactor your existing project if:

  • You have working features you want to keep
  • You have real user data in production
  • You want to adopt specific ProductReady patterns (tRPC, Drizzle, Better Auth)
  • You need gradual, low-risk migration
  • Your team is already familiar with the codebase

✅ Start fresh with ProductReady if:

  • You're building a new product from scratch
  • Your current codebase has too much tech debt
  • You want the fastest time-to-market
  • You're prototyping or validating ideas
  • You prefer a clean slate

AI Migration Prompt

Use this prompt to have AI help you migrate your existing project:

I have an existing project at `[YOUR_PROJECT_PATH]`.

Please help me **Make my project Product Ready**!

Read the ProductReady boilerplate at `apps/productready` to understand the architecture, then help me refactor my project:

PHASE 1 - ANALYSIS:
1. Analyze my current project structure and tech stack
2. Compare with ProductReady's architecture (tRPC, Drizzle, Better Auth, VO/DTO)
3. Identify gaps and pain points
4. Create a prioritized migration roadmap

PHASE 2 - ARCHITECTURE ADOPTION:
Help me migrate to:
- ✅ tRPC v11 (replace my REST APIs or upgrade from tRPC v10)
- ✅ Better Auth (replace NextAuth/Auth.js/custom auth)
- ✅ Drizzle ORM (migrate from Prisma/TypeORM/Sequelize)
- ✅ VO/DTO/PO pattern (add type safety at API boundaries)
- ✅ Fumadocs (set up documentation system)
- ✅ Demo mode support (add ?demo=1 for presentations)
- ✅ CSS variables design system (replace hardcoded colors)

PHASE 3 - CODE REORGANIZATION:
Restructure my code to match ProductReady's layout:
- src/app/ - Next.js App Router with route groups
- src/server/routers/ - tRPC routers with VO validation
- src/db/schema/ - Drizzle schemas and migrations
- src/components/ - Organized React components
- src/lib/ - Utilities (auth, trpc, i18n)
- spec/ - Product design and architecture docs
- content/docs/ - User-facing documentation

PHASE 4 - INCREMENTAL MIGRATION PLAN:
Prioritize based on impact and risk:
1. [ ] Database layer - Migrate to Drizzle ORM
2. [ ] Auth system - Switch to Better Auth
3. [ ] API layer - Migrate to tRPC v11 with VO/DTO
4. [ ] Type safety - Add Zod schemas and validation
5. [ ] Design system - Implement CSS variables
6. [ ] Documentation - Set up Fumadocs
7. [ ] Testing - Add Vitest + Playwright

MY CURRENT STACK:
- Framework: [e.g., Next.js 14 App Router]
- Database: [e.g., Prisma + PostgreSQL]
- Auth: [e.g., NextAuth.js]
- API: [e.g., REST endpoints or tRPC v10]
- Styling: [e.g., Tailwind CSS + shadcn/ui]
- State: [e.g., Zustand, Redux]

PAIN POINTS TO ADDRESS:
[Describe your issues - e.g., "No type safety between frontend and backend", "Auth bugs with session handling", "Slow database queries"]

Please start with Phase 1 analysis and create a detailed migration plan with:
- Breaking changes to watch for
- Data migration strategy
- Rollback plan for each phase
- Estimated effort for each step

Example Migration Scenarios

Scenario 1: Prisma → Drizzle

AI will:

  1. Convert Prisma schema to Drizzle
  2. Generate equivalent migrations
  3. Update queries to Drizzle syntax
  4. Add Zod validation from Prisma schema
  5. Test data integrity

Scenario 2: NextAuth → Better Auth

AI will:

  1. Migrate session/user tables
  2. Convert auth providers config
  3. Update login/signup flows
  4. Preserve existing user data
  5. Test authentication end-to-end

Scenario 3: REST → tRPC

AI will:

  1. Convert REST endpoints to tRPC routers
  2. Add input/output Zod validation
  3. Implement VO/DTO patterns
  4. Update frontend to tRPC client
  5. Add end-to-end type safety

Migration Checklist

After AI completes migration phases:

  • All tests pass - No regressions in existing features
  • Database migrated - Data integrity verified
  • Auth works - Users can sign in with existing accounts
  • APIs functional - All endpoints respond correctly
  • Type safety - No any types, full IntelliSense
  • Docs updated - README and specs reflect new architecture
  • Performance OK - No slowdowns from migration
  • Deploy tested - Staging environment works

Benefits of Gradual Migration

  • ✅ Low risk - Migrate one layer at a time
  • ✅ Keep working - Features stay functional during migration
  • ✅ Learn gradually - Understand new patterns as you adopt them
  • ✅ Rollback-friendly - Each phase can be reverted if needed
  • ✅ Team alignment - Everyone learns the new architecture together

Important: Always test each migration phase thoroughly before moving to the next. Use feature flags to toggle between old and new implementations during transition.

Demo Mode

Want to explore ProductReady without any setup? Try demo mode first!

Clone the repository

git clone https://github.com/mr-kelly/productready.git
cd kapps/apps/productready

Install dependencies

pnpm install

This takes 1-2 minutes on first run.

Start the dev server

pnpm dev

Your app is now running at http://localhost:3000

Open demo mode

Visit: http://localhost:3000/dashboard?demo=1

You'll see a working dashboard with:

  • Mock AI agent tasks
  • Sample data
  • All features working (no database needed!)

Perfect for: Exploring features, testing UI, giving demos

Manual Setup

Ready to set up ProductReady the traditional way? Follow these steps.

Clone and install

# Clone the repository
git clone https://github.com/mr-kelly/productready.git
cd kapps/apps/productready

# Install dependencies
pnpm install

Create environment file

# Copy the example environment file
cp .env.example .env

Now open .env in your editor and fill in the required values:

.env
# Database (required)
PG_DATABASE_URL="postgresql://user:password@localhost:5432/productready"

# Auth (required)
BETTER_AUTH_SECRET="your-secret-key-min-32-chars"
BETTER_AUTH_URL="http://localhost:3000"

# OAuth (optional - add later)
GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""

Generate a secret: Run openssl rand -base64 32 to generate a random secret for BETTER_AUTH_SECRET

Set up your database

Option 1: Use Neon (recommended for beginners)

  1. Go to neon.tech and create a free account
  2. Create a new project
  3. Copy the connection string (looks like: postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/neondb)
  4. Paste it into your .env as PG_DATABASE_URL

Option 2: Use Supabase

  1. Go to supabase.com and create a project
  2. Go to Project Settings → Database
  3. Copy the "Connection string" (with pooling enabled)
  4. Paste it into your .env as PG_DATABASE_URL

Option 3: Use Docker Compose (recommended for local development)

ProductReady includes a docker-compose.yml configuration that starts all required database services (PostgreSQL, Redis, Typesense) with one command.

# Run from project root (kapps/)
make db

This will start:

  • PostgreSQL: localhost:5432 (user: bika, password: bikabika, database: bikadev)
  • Redis: localhost:6379
  • Redis Insight: http://localhost:8001 (management UI)
  • Typesense: http://localhost:8108 (API Key: bikabika)

Your .env should be:

PG_DATABASE_URL="postgresql://bika:bikabika@localhost:5432/bikadev"

Tip: Use make db-stop to stop services, make db-logs to view logs. See the Deployment Guide for more commands.

Run database migrations

# Generate migration files (if needed)
pnpm db:generate

# Run migrations to create tables
pnpm db:migrate

You should see output like:

✓ Migrated successfully
✓ Tables created: users, sessions, tasks, posts

Seed the database (optional)

Want some example data to play with?

pnpm db:seed

This creates:

  • Demo user: demo@productready.dev (password: demo123456)
  • Admin user: admin@productready.dev (password shown in seed output or set via SITE_ADMIN_PASSWORD)
  • Sample tasks and posts
  • Test data for all features

Start the dev server

pnpm dev

Open http://localhost:3000 in your browser.

You should see:

  • ✅ Landing page loads
  • ✅ Sign in / Sign up works
  • ✅ Dashboard accessible after login
  • ✅ No console errors

Quick Start Tutorial

Let's explore ProductReady's key features through hands-on examples.

Sign in to the dashboard

  1. Go to http://localhost:3000/dashboard
  2. Sign in with: demo@productready.dev / demo123456 (if you ran db:seed)
  3. Or create a new account

Create your first Post

The dashboard demonstrates a complete CRUD feature (Posts):

  1. Click "New Post" button in the dashboard
  2. Fill in:
    • Title: "My First ProductReady Post"
    • Content: "This is a test post to understand tRPC, Drizzle, and the VO/DTO pattern"
  3. Click "Create"

Your post appears immediately! This demonstrates:

  • ✅ tRPC mutation - Type-safe API call
  • ✅ Drizzle ORM - Database insert with type safety
  • ✅ VO/DTO pattern - Input validation with Zod
  • ✅ React Query - Optimistic updates and cache invalidation

Tip: Open DevTools Network tab to see the tRPC call. Check out src/server/routers/posts.ts to see the backend implementation.

Try the AI Agent Interface (Coming Soon)

ProductReady includes an AI agent interface for autonomous task execution:

  1. Visit http://localhost:3000/agent
  2. The agent page shows the workflow:
    • Task queue management
    • Execution status tracking
    • Result display

Note: The /agent page is a UI mockup demonstrating the agent workflow. Full agent execution functionality is under development. Use this as a reference for building your own AI agent features.

What you can learn:

  • Agent task lifecycle (pending → running → completed)
  • Real-time status updates pattern
  • How to structure agent-human interaction UI

Congratulations! You now have:

  • A working Next.js app with TypeScript
  • Database with Drizzle ORM
  • Authentication with Better Auth
  • Type-safe API with tRPC
  • AI-ready task management system

Next Steps

Now that ProductReady is running, explore these guides:

For Product Managers & Designers

For Developers

Deploy to Production

Troubleshooting

"Database connection failed"

Check your PG_DATABASE_URL in .env:

  • Is the format correct? postgresql://user:pass@host:port/db
  • Can you connect with psql? Test: psql $PG_DATABASE_URL
  • Is your database running? Check with brew services list (macOS)

"Port 3000 already in use"

Kill the process or use a different port:

# Kill process on port 3000
lsof -ti:3000 | xargs kill -9

# Or use different port
pnpm dev -- --port 3001

"Module not found" errors

Clear cache and reinstall:

rm -rf node_modules .next
pnpm install
pnpm dev

Still stuck?

What's Next?

You're all set! Here are some ideas:

  1. Customize the landing page - Edit src/app/(home)/page.tsx
  2. Add a new database table - See Database Guide
  3. Build a new API endpoint - Follow tRPC Guide
  4. Style your app - Use Design System
  5. Deploy to production - Follow Vercel Guide

Ready to ship? Let's go! 🚀

Welcome to ProductReady

Build production-grade, fully-documented, market-ready applications equipped with AI agents - the kind you can actually sell and make money from

Project Structure

Understanding ProductReady's architecture - where everything lives and why

On this page

Quick StartWhat You'll SeeTwo Ways to Use ProductReady🆕 New Project🔄 Existing ProjectPrerequisitesNew Project from ProductReadyAI-Powered Initialization (Recommended)Clone ProductReadyUse This AI PromptStep 3: Iterate with AIExample Conversation FlowIterate and BuildRefactor Existing ProjectWhen to Refactor vs Start FreshAI Migration PromptExample Migration ScenariosMigration ChecklistBenefits of Gradual MigrationDemo ModeClone the repositoryInstall dependenciesStart the dev serverOpen demo modeManual SetupClone and installCreate environment fileSet up your databaseRun database migrationsSeed the database (optional)Start the dev serverQuick Start TutorialSign in to the dashboardCreate your first PostTry the AI Agent Interface (Coming Soon)Next StepsFor Product Managers & DesignersFor DevelopersDeploy to ProductionTroubleshooting"Database connection failed""Port 3000 already in use""Module not found" errorsStill stuck?What's Next?