Dev Environment Setup

Install PostgreSQL (choose one):

Option A: Docker (Recommended)

1. Install Docker Desktop: https://www.docker.com/products/docker-desktop/
2. Restart computer
3. Start Docker Desktop
4. From ecommerce-backend/: docker compose up -d

Option B: Local PostgreSQL

1. Download from: https://www.postgresql.org/download/windows/
2. Install with default settings
3. Remember postgres user password
4. Add to PATH: $env:Path += ";D:\Program Files\PostgreSQL\18\bin"
5. Create database:

   psql -U postgres
   CREATE DATABASE ecommerce;
   \q
   

2. Install Flutter Prerequisites

Install Flutter 3.2+:

1. Download Flutter SDK: https://docs.flutter.dev/get-started/install/windows
2. Extract to C:\src\flutter (or preferred location)
3. Add to PATH: $env:Path += ";C:\src\flutter\bin"
4. Run: flutter doctor
5. Follow any recommendations from flutter doctor

Enable Windows Desktop Development:

flutter config --enable-windows-desktop

Install Chrome (for web development):

• Download from: https://www.google.com/chrome/

3. Backend Setup

# Navigate to backend
cd "D:\demo project\ecommerce-backend"

# Install dependencies
go mod download
go mod tidy

# Copy environment file
cp .env.example .env

# Edit .env file (update if needed)
# DATABASE_URL, JWT_SECRET, etc.

# Run migrations (CRITICAL - creates database tables)
make migrate-up
# OR
go run cmd/migrate/main.go up

# Verify tables created
$env:PGPASSWORD = "postgres"
psql -U postgres -d ecommerce -c "\dt"

# Start backend server
make run
# OR
go run cmd/api/main.go

Backend should now run on: http://localhost:8080

Verify backend:

curl http://localhost:8080/health

4. Frontend Setup

# Navigate to frontend
cd "D:\demo project\ecommerce-app"

# Add Flutter to PATH (if not permanent)
$env:Path += ";C:\src\flutter\bin"

# Get dependencies
flutter pub get

# Analyze for issues
flutter analyze

# Run app (ensure backend is running first)
flutter run -d chrome --web-port=3000
# OR
flutter run -d windows

Environment Variables Setup

Backend (.env file in ecommerce-backend/)

# Server
PORT=8080
ENVIRONMENT=development

# Database
DATABASE_URL=postgres://postgres:postgres@localhost:5432/ecommerce?sslmode=disable

# JWT (CHANGE IN PRODUCTION!)
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
JWT_ACCESS_TOKEN_EXPIRATION=30m
JWT_REFRESH_TOKEN_EXPIRATION=168h

# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_RPS=10

# CORS
CORS_ALLOW_ORIGINS=http://localhost:3000,http://localhost:8080

# Future: Stripe keys, email settings, etc.

Frontend (lib/core/constants/api_constants.dart)

static const String baseUrl = 'http://localhost:8080/api/v1';

Persistent PATH Setup (Optional)

To avoid setting PATH every time:

PowerShell Profile:

# Open profile
notepad $PROFILE

# Add these lines:
$env:Path += ";C:\src\flutter\bin"
$env:Path += ";D:\Program Files\PostgreSQL\18\bin"

# Save and reload
. $PROFILE

Or System Environment Variables:

1. Search "Environment Variables" in Windows
2. Edit "Path" under User or System variables
3. Add: C:\src\flutter\bin
4. Add: D:\Program Files\PostgreSQL\18\bin

Development Tools (Optional but Recommended)

Backend Tools:

# Swagger doc generator
go install github.com/swaggo/swag/cmd/swag@latest

# Migration tool (if not using go run)
go install github.com/golang-migrate/migrate/v4/cmd/migrate@latest

# Linter
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Frontend Tools:

# DevTools for debugging
flutter pub global activate devtools

IDE Setup

VS Code Extensions (Recommended):

• Go (golang.go)
• Flutter (Dart-Code.flutter)
• Dart (Dart-Code.dart-code)
• PostgreSQL (ckolkman.vscode-postgres)
• GitLens (eamodio.gitlens)
• Thunder Client or REST Client (for API testing)

Quick Reference Commands

Backend:

cd ecommerce-backend
make run              # Start server
make test             # Run tests
make migrate-up       # Run migrations
make migrate-down     # Rollback migrations
go mod tidy           # Clean dependencies

Frontend:

cd ecommerce-app
flutter pub get       # Get dependencies
flutter run -d chrome # Run on web
flutter analyze       # Check for issues
flutter test          # Run tests
flutter clean         # Clean build cache

Troubleshooting Initial Setup

"go: command not found"

• Go not installed or not in PATH
• Install Go and restart terminal

"psql: command not found"

• PostgreSQL not in PATH
• Add: $env:Path += ";D:\Program Files\PostgreSQL\18\bin"

"flutter: command not found"

• Flutter not in PATH
• Add: $env:Path += ";C:\src\flutter\bin"

Database connection errors

• Ensure PostgreSQL is running
• Check DATABASE_URL in .env
• Verify database exists: psql -U postgres -l

Migration errors

• Always run from ecommerce-backend/ directory
• Ensure database exists
• Check DATABASE_URL is correct

Port conflicts (8080 or 3000 in use)

# Find process
netstat -ano | findstr ":8080"
# Kill if needed
taskkill /PID <PID> /F

Verification Checklist

• Go version 1.22+ installed
• PostgreSQL 15+ running
• Flutter 3.2+ installed
• Backend dependencies installed (go mod download)
• Frontend dependencies installed (flutter pub get)
• Database created (ecommerce)
• Migrations run successfully
• Backend server starts on port 8080
• Backend health check responds
• Flutter app runs on Chrome or Windows
• Flutter app can connect to backend API