From c10e094ed4e98e0aabf1d1c8e99d4f8682a9ce40 Mon Sep 17 00:00:00 2001
From: "yves.gugger" <yves.gugger@gentwo.com>
Date: Mon, 8 Dec 2025 16:56:45 +0100
Subject: [PATCH] docs: Comprehensive startup guide + troubleshooting

README UPDATES:
- Added Quick Start section at the top with 2-command startup
- Documented common console warnings (SES, PostHog, CSS prefixes)
- Explained what errors actually need fixing
- Three startup options: Two terminals, start.sh, PM2
- Step-by-step manual setup with verification
- Application URLs table

IMPORTANT: Backend must be running for CORS errors to disappear!
---
 README.md | 112 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 98 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 8d96f14..663fd21 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,47 @@
 
 A professional full-stack application for monitoring domain name availability with TLD price tracking and intelligence.
 
+---
+
+## ⚡ Quick Start (Local Development)
+
+**Terminal 1 - Backend:**
+```bash
+cd backend
+source venv/bin/activate
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+**Terminal 2 - Frontend:**
+```bash
+cd frontend
+npm run dev
+```
+
+**Access:**
+- Frontend: http://localhost:3000
+- Backend: http://localhost:8000
+- API Docs: http://localhost:8000/docs
+
+### ⚠️ Common Console Warnings (Can be ignored)
+
+| Warning | Explanation |
+|---------|-------------|
+| `SES Removing unpermitted intrinsics` | MetaMask/browser extension - harmless |
+| `PostHog CORS blocked` | Normal on localhost, works in production |
+| `-webkit-text-size-adjust` error | Old CSS prefixes - harmless |
+| `-moz-column-gap` unknown | Old Firefox prefix - harmless |
+| `preloaded font not used` | Next.js optimization - harmless |
+
+### ❌ Actual Errors to Fix
+
+| Error | Solution |
+|-------|----------|
+| `CORS request did not succeed` to localhost:8000 | **Start the backend!** |
+| `500 Internal Server Error` | Check backend logs, run `python scripts/init_db.py` |
+
+---
+
 ## Features
 
 ### Core Functionality
@@ -197,32 +238,61 @@ pounce/
 
 ---
 
-## Quick Start
+## Full Setup Guide
 
 ### Prerequisites
 - Python 3.12+
 - Node.js 18+
 - npm or yarn
 
-### 🚀 One-Command Setup (Recommended)
+### 🚀 One-Command Setup (Fresh Install)
 
 ```bash
 # Clone repository
 git clone https://git.6bit.ch/yvg/pounce.git
 cd pounce
 
-# Run deployment script (sets up everything)
+# Run deployment script (installs everything + initializes database)
 chmod +x deploy.sh
 ./deploy.sh
+```
 
-# Start both services
+### 🏃 Starting the Application
+
+**Option A: Two Terminals (Recommended for Development)**
+
+```bash
+# Terminal 1 - Backend
+cd backend
+source venv/bin/activate
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+
+# Terminal 2 - Frontend
+cd frontend
+npm run dev
+```
+
+**Option B: Single Command (Quick)**
+
+```bash
 chmod +x start.sh
 ./start.sh
 ```
 
-That's it! Open http://localhost:3000
+**Option C: PM2 (Production)**
 
-### Manual Setup
+```bash
+# Backend
+cd backend && source venv/bin/activate
+pm2 start "uvicorn app.main:app --host 0.0.0.0 --port 8000" --name pounce-api
+
+# Frontend
+cd frontend
+npm run build
+pm2 start "npm start" --name pounce-web
+```
+
+### 🔧 Manual Setup (Step by Step)
 
 #### 1. Clone Repository
 
@@ -247,11 +317,11 @@ pip install -r requirements.txt
 # Create environment file
 cp env.example .env
 
-# Generate secret key and add to .env
-python -c "import secrets; print(f'SECRET_KEY={secrets.token_hex(32)}')"
-# Edit .env with your SECRET_KEY
+# Generate secret key
+python -c "import secrets; print(secrets.token_hex(32))"
+# Copy the output and paste into .env as SECRET_KEY=...
 
-# Initialize database
+# Initialize database (creates tables + seeds data)
 python scripts/init_db.py
 ```
 
@@ -275,11 +345,25 @@ echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local
 npm run dev
 ```
 
-#### 4. Access Application
+#### 4. Verify Everything Works
 
-- **Frontend:** http://localhost:3000
-- **Backend API:** http://localhost:8000
-- **API Docs:** http://localhost:8000/docs
+```bash
+# Check backend health
+curl http://localhost:8000/health
+# Should return: {"status":"healthy","service":"DomainWatch","version":"1.0.0"}
+
+# Open frontend
+open http://localhost:3000
+```
+
+### 📍 Application URLs
+
+| Service | URL | Description |
+|---------|-----|-------------|
+| Frontend | http://localhost:3000 | Main application |
+| Backend API | http://localhost:8000 | REST API |
+| API Docs (Swagger) | http://localhost:8000/docs | Interactive API docs |
+| API Docs (ReDoc) | http://localhost:8000/redoc | Alternative docs |
 
 ---