leedstack 3.1.0

package/tools/templates/base/Makefile

@@ -0,0 +1,98 @@
+.PHONY: help install install-fast dev build clean db-up db-down db-reset setup
+
+help: ## Show this help message
+	@echo 'Usage: make [target]'
+	@echo ''
+	@echo 'Available targets:'
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+setup: install db-up ## Complete setup (install + start database)
+	@echo "✅ Setup complete! Run 'make dev' to start"
+
+install-fast: ## Install dependencies in parallel (faster)
+	@echo "📦 Installing dependencies in parallel..."
+	@(cd frontend && npm install) & \
+<% if (backend === 'node-express') { -%>
+	(cd backend && npm install) & \
+<% } else if (backend === 'python-fastapi') { -%>
+	(cd backend && python -m venv venv && . venv/bin/activate && pip install -r requirements.txt) & \
+<% } else if (backend === 'java-spring') { -%>
+	(cd backend && mvn clean install -T 1C) & \
+<% } else if (backend === 'go-echo') { -%>
+	(cd backend && go mod download) & \
+<% } -%>
+	wait
+	@echo "✅ Dependencies installed (parallel)"
+
+install: ## Install all dependencies (sequential)
+	@echo "📦 Installing dependencies..."
+	cd frontend && npm install
+<% if (backend === 'node-express') { -%>
+	cd backend && npm install
+<% } else if (backend === 'python-fastapi') { -%>
+	cd backend && python -m venv venv && . venv/bin/activate && pip install -r requirements.txt
+<% } else if (backend === 'java-spring') { -%>
+	cd backend && mvn clean install
+<% } else if (backend === 'go-echo') { -%>
+	cd backend && go mod download
+<% } -%>
+	@echo "✅ Dependencies installed"
+
+dev: ## Start development servers
+	@echo "🚀 Starting development servers..."
+	@echo "Run 'make db-up' first if database is not running"
+<% if (backend === 'node-express') { -%>
+	npm run dev
+<% } else { -%>
+	@echo "Start backend and frontend in separate terminals:"
+	@echo "  Terminal 1: cd backend && <% if (backend === 'python-fastapi') { %>python -m app.main<% } else if (backend === 'java-spring') { %>mvn spring-boot:run<% } else if (backend === 'go-echo') { %>go run ./cmd/server<% } %>"
+	@echo "  Terminal 2: cd frontend && npm run dev"
+<% } -%>
+
+build: ## Build for production
+	@echo "🏗️  Building for production..."
+	cd frontend && npm run build
+<% if (backend === 'node-express') { -%>
+	cd backend && npm run build
+<% } else if (backend === 'python-fastapi') { -%>
+	@echo "Python: No build step needed"
+<% } else if (backend === 'java-spring') { -%>
+	cd backend && mvn clean package
+<% } else if (backend === 'go-echo') { -%>
+	cd backend && go build -o bin/<%= appSlug %>-backend ./cmd/server
+<% } -%>
+	@echo "✅ Build complete"
+
+db-up: ## Start database container
+	@echo "🐳 Starting database..."
+	docker compose up -d db
+	@echo "⏳ Waiting for database to be ready..."
+	@sleep 5
+	@echo "✅ Database is ready"
+
+db-down: ## Stop database container
+	@echo "🛑 Stopping database..."
+	docker compose down
+
+db-reset: ## Reset database (WARNING: deletes all data)
+	@echo "⚠️  This will delete all database data!"
+	@read -p "Are you sure? [y/N] " -n 1 -r; \
+	if [[ $$REPLY =~ ^[Yy]$$ ]]; then \
+		docker compose down -v; \
+		docker compose up -d db; \
+		echo "✅ Database reset complete"; \
+	fi
+
+clean: ## Clean build artifacts
+	@echo "🧹 Cleaning..."
+	cd frontend && rm -rf node_modules dist build .next
+<% if (backend === 'node-express') { -%>
+	cd backend && rm -rf node_modules dist build
+<% } else if (backend === 'python-fastapi') { -%>
+	cd backend && rm -rf __pycache__ .pytest_cache venv
+<% } else if (backend === 'java-spring') { -%>
+	cd backend && mvn clean
+<% } else if (backend === 'go-echo') { -%>
+	cd backend && rm -rf bin
+<% } -%>
+	@echo "✅ Clean complete"

package/tools/templates/base/README.md.ejs

@@ -0,0 +1,118 @@
+# <%= AppName %>
+
+Generated via `create-stack`.
+
+## Stack
+
+- **Frontend**: <%= frontend %>
+- **Backend**: <%= backend %>
+- **Database**: <%= db %>
+<% if (modules.auth) { -%>
+- **Auth**: <%= auth %>
+<% } -%>
+<% if (modules.payments) { -%>
+- **Payments**: <%= payments %>
+<% } -%>
+
+## Quickstart
+
+```bash
+# Start the database
+docker compose up -d
+
+# Backend
+cd backend
+<% if (backend === 'java-spring') { -%>
+# Java 21 required
+mvn spring-boot:run
+<% } else if (backend === 'node-express') { -%>
+# Node >=20 required
+npm install
+npm run dev
+<% } else if (backend === 'go-echo') { -%>
+# Go >=1.22 required
+go run ./cmd/server
+<% } -%>
+
+# Frontend (in a new terminal)
+cd ../frontend
+cp .env.example .env
+npm install
+npm run dev
+```
+<% if (modules.auth) { -%>
+
+## Auth0 Setup
+
+1. Create a **Single Page Application** in Auth0
+2. Configure settings:
+   - **Allowed Callback URLs**: `http://localhost:5173/callback`
+   - **Allowed Logout URLs**: `http://localhost:5173`
+   - **Allowed Web Origins**: `http://localhost:5173`
+3. Create an **API** in Auth0:
+   - **Identifier**: `https://api.<%= appSlug %>`
+   - Enable **RBAC**
+<% if (modules.admin) { -%>
+   - Add `admin` permission
+<% } -%>
+4. Update `.env` files with Auth0 credentials:
+   - `PUBLIC_AUTH0_DOMAIN`
+   - `PUBLIC_AUTH0_CLIENT_ID`
+   - `PUBLIC_AUTH0_AUDIENCE`
+   - `AUTH0_DOMAIN` (backend)
+   - `AUTH0_AUDIENCE` (backend)
+<% } -%>
+<% if (modules.payments) { -%>
+
+## Stripe Setup
+
+1. Get your Stripe secret key from the [Stripe Dashboard](https://dashboard.stripe.com/test/apikeys)
+2. Set `STRIPE_SECRET_KEY` in backend `.env`
+3. Create a product and price in Stripe, note the price ID
+4. For webhook testing in development:
+   ```bash
+   stripe listen --forward-to localhost:8080/stripe/webhook
+   ```
+5. Set `STRIPE_WEBHOOK_SECRET` from the CLI output
+<% } -%>
+
+## Endpoints
+
+<% if (modules.contact) { -%>
+- `POST /api/contact` - Submit contact message
+<% } -%>
+<% if (modules.admin) { -%>
+- `GET /api/admin/stats` - Get admin statistics (requires `admin` scope)
+<% } -%>
+<% if (modules.payments) { -%>
+- `POST /api/payments/create-checkout-session` - Create Stripe checkout session
+- `POST /stripe/webhook` - Stripe webhook handler (public)
+<% } -%>
+<% if (backend === 'java-spring') { -%>
+- `GET /actuator/health` - Health check
+<% } else { -%>
+- `GET /health` - Health check
+<% } -%>
+
+## Efficiency & Production Notes
+
+**Frontend**:
+- SSR enabled where applicable
+- Code-split routes
+<% if (modules.admin) { -%>
+- Admin module lazy-loaded
+<% } -%>
+- Minimal dependencies
+
+**Backend**:
+- JSON-only API
+- JWT validation via JWKS
+<% if (backend === 'java-spring') { -%>
+- Flyway migrations for schema management
+<% } else if (backend === 'node-express' && db !== 'mongodb') { -%>
+- Prisma migrations for schema management
+<% } -%>
+
+**Docker**:
+- Development uses only DB container
+- For production, use multi-stage builds with minimal base images

package/tools/templates/base/docker-compose.yml.ejs

@@ -0,0 +1,49 @@
+services:
+  db:
+<% if (db === 'postgres') { -%>
+    image: postgres:16
+    container_name: <%= appSlug %>-db
+    environment:
+      POSTGRES_USER: <%= appSlug %>
+      POSTGRES_PASSWORD: password
+      POSTGRES_DB: <%= appSlug %>_dev
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U <%= appSlug %>"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+<% } else if (db === 'mysql') { -%>
+    image: mysql:8
+    container_name: <%= appSlug %>-db
+    environment:
+      MYSQL_ROOT_PASSWORD: password
+      MYSQL_DATABASE: <%= appSlug %>_dev
+      MYSQL_USER: <%= appSlug %>
+      MYSQL_PASSWORD: password
+    ports:
+      - "3306:3306"
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+<% } else { -%>
+    image: mongo:7
+    container_name: <%= appSlug %>-db
+    ports:
+      - "27017:27017"
+    healthcheck:
+      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+<% } -%>
+    volumes:
+      - db_data:/data
+    restart: unless-stopped
+
+volumes:
+  db_data:
+    driver: local

package/tools/templates/base/package.json.ejs

@@ -0,0 +1,30 @@
+{
+  "name": "<%= appSlug %>",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "echo 'Starting development servers...' && npm-run-all --parallel dev:*",
+    "dev:backend": "cd backend && npm run dev",
+    "dev:frontend": "cd frontend && npm run dev",
+    "install:all": "npm-run-all --parallel install:*",
+    "install:backend": "cd backend && npm install",
+    "install:frontend": "cd frontend && npm install",
+    "build": "npm-run-all build:*",
+    "build:backend": "cd backend && npm run build",
+    "build:frontend": "cd frontend && npm run build",
+    "setup": "npm run install:all && echo '✅ All dependencies installed!'",
+    "start": "npm-run-all --parallel start:*",
+    "start:backend": "cd backend && npm start",
+    "start:frontend": "cd frontend && npm start",
+    "clean": "npm-run-all clean:*",
+    "clean:backend": "cd backend && rm -rf node_modules dist build",
+    "clean:frontend": "cd frontend && rm -rf node_modules dist build .next",
+    "reset": "npm run clean && npm run install:all"
+  },
+  "devDependencies": {
+    "npm-run-all": "^4.1.5"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/tools/templates/base/scripts/split-repos.sh

@@ -0,0 +1,189 @@
+#!/bin/bash
+
+# Script to split monorepo into separate frontend and backend repositories
+# Usage: ./scripts/split-repos.sh
+
+set -e
+
+echo "🔀 Splitting monorepo into separate repositories..."
+echo ""
+
+# Get project name from current directory
+PROJECT_NAME=$(basename "$PWD")
+FRONTEND_REPO="${PROJECT_NAME}-frontend"
+BACKEND_REPO="${PROJECT_NAME}-backend"
+
+# Confirm with user
+echo "This will create two new directories:"
+echo "  - ../$FRONTEND_REPO"
+echo "  - ../$BACKEND_REPO"
+echo ""
+read -p "Continue? (y/n) " -n 1 -r
+echo
+if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+    exit 1
+fi
+
+# Create frontend repo
+echo ""
+echo "📦 Creating frontend repository..."
+cd ..
+mkdir -p "$FRONTEND_REPO"
+cd "$PROJECT_NAME"
+
+# Copy frontend files
+cp -r frontend/* "../$FRONTEND_REPO/"
+cp -r frontend/.* "../$FRONTEND_REPO/" 2>/dev/null || true
+
+# Copy shared files
+cp .gitignore "../$FRONTEND_REPO/"
+cp README.md "../$FRONTEND_REPO/README.md.bak"
+
+# Initialize git
+cd "../$FRONTEND_REPO"
+rm -rf .git 2>/dev/null || true
+git init
+git add .
+git commit -m "Initial commit: frontend"
+
+echo "✅ Frontend repository created at ../$FRONTEND_REPO"
+
+# Create backend repo
+echo ""
+echo "📦 Creating backend repository..."
+cd "../$PROJECT_NAME"
+mkdir -p "../$BACKEND_REPO"
+
+# Copy backend files
+cp -r backend/* "../$BACKEND_REPO/"
+cp -r backend/.* "../$BACKEND_REPO/" 2>/dev/null || true
+
+# Copy shared files
+cp .gitignore "../$BACKEND_REPO/"
+cp docker-compose.yml "../$BACKEND_REPO/" 2>/dev/null || true
+cp README.md "../$BACKEND_REPO/README.md.bak"
+
+# Initialize git
+cd "../$BACKEND_REPO"
+rm -rf .git 2>/dev/null || true
+git init
+git add .
+git commit -m "Initial commit: backend"
+
+echo "✅ Backend repository created at ../$BACKEND_REPO"
+
+# Create instructions
+cd "../$PROJECT_NAME"
+cat > SPLIT_INSTRUCTIONS.md << 'EOF'
+# Next Steps After Splitting Repositories
+
+## 1. Create GitHub Repositories
+
+```bash
+# Create repos on GitHub, then:
+
+# Frontend
+cd ../PROJECT_NAME-frontend
+git remote add origin https://github.com/USERNAME/PROJECT_NAME-frontend.git
+git push -u origin main
+
+# Backend
+cd ../PROJECT_NAME-backend
+git remote add origin https://github.com/USERNAME/PROJECT_NAME-backend.git
+git push -u origin main
+```
+
+## 2. Update Environment Variables
+
+### Frontend (.env)
+```env
+# Update API base URL to production backend
+VITE_API_BASE=https://your-backend.fly.dev
+```
+
+### Backend (.env)
+```env
+# Add production frontend URL
+FRONTEND_URL=https://your-app.vercel.app
+```
+
+## 3. Update CORS Configuration
+
+### Backend (src/index.ts)
+Add your production frontend URL to allowed origins:
+```typescript
+const allowedOrigins = [
+  'http://localhost:5173',
+  'http://localhost:3000',
+  'https://your-app.vercel.app',  // Add this
+  process.env.FRONTEND_URL
+].filter(Boolean);
+```
+
+## 4. Set Up CI/CD
+
+Copy the appropriate deployment workflow:
+```bash
+# Frontend
+cp .github/workflows/deploy-separate.yml.example .github/workflows/deploy.yml
+# Edit and keep only frontend section
+
+# Backend
+cp .github/workflows/deploy-separate.yml.example .github/workflows/deploy.yml
+# Edit and keep only backend section
+```
+
+## 5. Deploy
+
+### Frontend (Vercel - FREE)
+```bash
+cd ../PROJECT_NAME-frontend
+npm install -g vercel
+vercel --prod
+```
+
+### Backend (Fly.io - FREE)
+```bash
+cd ../PROJECT_NAME-backend
+curl -L https://fly.io/install.sh | sh
+fly auth login
+fly launch
+fly deploy
+```
+
+### Database (Supabase - FREE)
+1. Create project at https://supabase.com
+2. Get connection string
+3. Set in backend: `fly secrets set DATABASE_URL=postgresql://...`
+
+## 6. Update Frontend with Backend URL
+
+After deploying backend, update frontend env vars:
+```bash
+# Vercel
+vercel env add VITE_API_BASE production
+# Enter: https://your-backend.fly.dev
+```
+
+## Done! 🎉
+
+Your app is now deployed separately:
+- Frontend: https://your-app.vercel.app (FREE)
+- Backend: https://your-backend.fly.dev (FREE)
+- Database: Supabase (FREE)
+
+**Total cost: $0/month**
+
+See DEPLOYMENT_STRATEGIES.md for more details.
+EOF
+
+echo ""
+echo "✅ Split complete!"
+echo ""
+echo "📝 Next steps written to: SPLIT_INSTRUCTIONS.md"
+echo ""
+echo "Your repositories:"
+echo "  Frontend: ../$FRONTEND_REPO"
+echo "  Backend:  ../$BACKEND_REPO"
+echo ""
+echo "Read SPLIT_INSTRUCTIONS.md for deployment steps."

package/tools/templates/db/postgres/backend/java-spring/backend/pom.xml.ejs

@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-parent</artifactId>
+        <version>3.3.4</version>
+        <relativePath/>
+    </parent>
+
+    <groupId>com.app</groupId>
+    <artifactId><%= appSlug %>-backend</artifactId>
+    <version>0.0.1-SNAPSHOT</version>
+    <name><%= appName %> Backend</name>
+
+    <properties>
+        <java.version>21</java.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-data-jpa</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.flywaydb</groupId>
+            <artifactId>flyway-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.flywaydb</groupId>
+            <artifactId>flyway-database-postgresql</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.postgresql</groupId>
+            <artifactId>postgresql</artifactId>
+            <scope>runtime</scope>
+        </dependency>
+<% if (modules.auth) { -%>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-security</artifactId>
+        </dependency>
+<% } -%>
+<% if (modules.payments) { -%>
+        <dependency>
+            <groupId>com.stripe</groupId>
+            <artifactId>stripe-java</artifactId>
+            <version>26.0.0</version>
+        </dependency>
+<% } -%>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-actuator</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+</project>

package/tools/templates/db/postgres/backend/java-spring/backend/src/main/resources/application.yml.ejs

@@ -0,0 +1,39 @@
+server:
+  port: ${APP_PORT:8080}
+
+spring:
+  application:
+    name: <%= appSlug %>-backend
+
+  datasource:
+    url: jdbc:postgresql://${DB_HOST:localhost}:${DB_PORT:5432}/${DB_NAME:<%= appSlug %>_dev}
+    username: ${DB_USER:<%= appSlug %>}
+    password: ${DB_PASSWORD:password}
+
+  jpa:
+    hibernate:
+      ddl-auto: validate
+    properties:
+      hibernate:
+        jdbc:
+          time_zone: UTC
+    show-sql: false
+
+  flyway:
+    enabled: true
+    locations: classpath:db/migration
+<% if (modules.auth) { -%>
+
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          issuer-uri: https://${AUTH0_DOMAIN}/
+          audiences: ${AUTH0_AUDIENCE}
+<% } -%>
+
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health

package/tools/templates/db/postgres/backend/java-spring/backend/src/main/resources/db/migration/V1__init.sql

@@ -0,0 +1,17 @@
+CREATE TABLE IF NOT EXISTS users (
+    id BIGSERIAL PRIMARY KEY,
+    email VARCHAR(255) UNIQUE NOT NULL,
+    name VARCHAR(120),
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS roles (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(30) UNIQUE NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS user_roles (
+    user_id BIGINT REFERENCES users(id) ON DELETE CASCADE,
+    role_id INT REFERENCES roles(id) ON DELETE CASCADE,
+    PRIMARY KEY (user_id, role_id)
+);

package/tools/templates/db/postgres/backend/node-express/backend/.env.example

@@ -0,0 +1,10 @@
+APP_PORT=8080
+DATABASE_URL=postgresql://<%= appSlug %>:password@localhost:5432/<%= appSlug %>_dev
+<% if (modules.auth) { -%>
+AUTH0_DOMAIN=your-tenant.us.auth0.com
+AUTH0_AUDIENCE=https://api.<%= appSlug %>
+<% } -%>
+<% if (modules.payments) { -%>
+STRIPE_SECRET_KEY=sk_test_xxx
+STRIPE_WEBHOOK_SECRET=whsec_xxx
+<% } -%>

package/tools/templates/db/postgres/backend/node-express/backend/package.json.ejs

@@ -0,0 +1,32 @@
+{
+  "name": "<%= appSlug %>-backend",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prisma:generate": "prisma generate",
+    "prisma:migrate": "prisma migrate dev"
+  },
+  "dependencies": {
+    "express": "^5.0.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "@prisma/client": "^6.0.0"<% if (modules.auth) { %>,
+    "jose": "^5.9.6"<% } %><% if (modules.payments) { %>,
+    "stripe": "^16.0.0"<% } %>
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/cors": "^2.8.17",
+    "@types/node": "^22.0.0",
+    "prisma": "^6.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}