@techstream/quark-create-app 1.2.0

package/templates/base-project/apps/web/src/middleware.js

@@ -0,0 +1,265 @@
+/**
+ * Next.js Middleware
+ * Handles rate limiting, CORS, and security headers
+ */
+
+import { getAllowedOrigins } from "@techstream/quark-config/app-url";
+import { NextResponse } from "next/server";
+
+// Simple in-memory rate limiter (use Redis for production)
+const rateLimit = new Map();
+
+const RATE_LIMIT_CONFIG = {
+	windowMs: 15 * 60 * 1000, // 15 minutes
+	maxRequests: {
+		api: 100, // 100 requests per 15 minutes for general API
+		auth: 5, // 5 requests per 15 minutes for auth endpoints
+	},
+};
+
+/**
+ * Rate limiting implementation
+ */
+function checkRateLimit(ip, path) {
+	const now = Date.now();
+	const key = `${ip}:${path}`;
+
+	// Determine which limit to use
+	const isAuthEndpoint = path.startsWith("/api/auth/");
+	const maxRequests = isAuthEndpoint
+		? RATE_LIMIT_CONFIG.maxRequests.auth
+		: RATE_LIMIT_CONFIG.maxRequests.api;
+
+	// Get or create rate limit record
+	const record = rateLimit.get(key) || {
+		count: 0,
+		resetTime: now + RATE_LIMIT_CONFIG.windowMs,
+	};
+
+	// Reset if window has passed
+	if (now > record.resetTime) {
+		record.count = 0;
+		record.resetTime = now + RATE_LIMIT_CONFIG.windowMs;
+	}
+
+	// Check if limit exceeded
+	if (record.count >= maxRequests) {
+		return {
+			limited: true,
+			resetTime: record.resetTime,
+			remaining: 0,
+		};
+	}
+
+	// Increment counter
+	record.count++;
+	rateLimit.set(key, record);
+
+	return {
+		limited: false,
+		resetTime: record.resetTime,
+		remaining: maxRequests - record.count,
+	};
+}
+
+/**
+ * Clean up old rate limit records periodically
+ */
+setInterval(() => {
+	const now = Date.now();
+	for (const [key, record] of rateLimit.entries()) {
+		if (now > record.resetTime) {
+			rateLimit.delete(key);
+		}
+	}
+}, 60 * 1000); // Clean up every minute
+
+/**
+ * CORS configuration
+ */
+const CORS_CONFIG = {
+	allowedOrigins: getAllowedOrigins(),
+	allowedMethods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+	allowedHeaders: ["Content-Type", "Authorization", "X-CSRF-Token"],
+	exposedHeaders: [
+		"X-RateLimit-Limit",
+		"X-RateLimit-Remaining",
+		"X-RateLimit-Reset",
+	],
+	credentials: true,
+	maxAge: 86400, // 24 hours
+};
+
+/**
+ * Security headers configuration
+ */
+const SECURITY_HEADERS = {
+	"X-DNS-Prefetch-Control": "on",
+	"Strict-Transport-Security": "max-age=63072000; includeSubDomains",
+	"X-Frame-Options": "SAMEORIGIN",
+	"X-Content-Type-Options": "nosniff",
+	"Referrer-Policy": "strict-origin-when-cross-origin",
+	"Permissions-Policy": "camera=(), microphone=(), geolocation=()",
+	"Content-Security-Policy":
+		"default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self';",
+};
+
+/**
+ * Request size limits (in bytes)
+ */
+const REQUEST_SIZE_LIMITS = {
+	api: parseInt(process.env.API_BODY_SIZE_LIMIT || "2097152", 10), // 2MB default
+	upload: parseInt(process.env.UPLOAD_SIZE_LIMIT || "10485760", 10), // 10MB for uploads
+};
+
+export function middleware(request) {
+	const { pathname } = request.nextUrl;
+	const origin = request.headers.get("origin") || "";
+
+	// Create response
+	const response = NextResponse.next();
+
+	// Check request body size for API routes
+	if (
+		pathname.startsWith("/api/") &&
+		["POST", "PUT", "PATCH"].includes(request.method)
+	) {
+		const contentLength = request.headers.get("content-length");
+		if (contentLength) {
+			const size = parseInt(contentLength, 10);
+			const limit = pathname.startsWith("/api/upload")
+				? REQUEST_SIZE_LIMITS.upload
+				: REQUEST_SIZE_LIMITS.api;
+
+			if (size > limit) {
+				return new NextResponse(
+					JSON.stringify({
+						error: "Payload too large",
+						message: `Request body size exceeds limit of ${Math.round(limit / 1024 / 1024)}MB`,
+						maxSize: limit,
+					}),
+					{
+						status: 413,
+						headers: {
+							"Content-Type": "application/json",
+						},
+					},
+				);
+			}
+		}
+	}
+
+	// Apply rate limiting to API routes only
+	if (pathname.startsWith("/api/")) {
+		const ip =
+			request.ip || request.headers.get("x-forwarded-for") || "unknown";
+		const rateLimitResult = checkRateLimit(ip, pathname);
+
+		if (rateLimitResult.limited) {
+			const retryAfter = Math.ceil(
+				(rateLimitResult.resetTime - Date.now()) / 1000,
+			);
+			return new NextResponse(
+				JSON.stringify({
+					error: "Too many requests",
+					message: "You have exceeded the rate limit. Please try again later.",
+					retryAfter,
+				}),
+				{
+					status: 429,
+					headers: {
+						"Content-Type": "application/json",
+						"Retry-After": retryAfter.toString(),
+						"X-RateLimit-Limit": pathname.startsWith("/api/auth/")
+							? RATE_LIMIT_CONFIG.maxRequests.auth.toString()
+							: RATE_LIMIT_CONFIG.maxRequests.api.toString(),
+						"X-RateLimit-Remaining": "0",
+						"X-RateLimit-Reset": new Date(
+							rateLimitResult.resetTime,
+						).toISOString(),
+					},
+				},
+			);
+		}
+
+		// Add rate limit headers to response
+		response.headers.set(
+			"X-RateLimit-Limit",
+			pathname.startsWith("/api/auth/")
+				? RATE_LIMIT_CONFIG.maxRequests.auth.toString()
+				: RATE_LIMIT_CONFIG.maxRequests.api.toString(),
+		);
+		response.headers.set(
+			"X-RateLimit-Remaining",
+			rateLimitResult.remaining.toString(),
+		);
+		response.headers.set(
+			"X-RateLimit-Reset",
+			new Date(rateLimitResult.resetTime).toISOString(),
+		);
+	}
+
+	// Handle CORS for API routes
+	if (pathname.startsWith("/api/")) {
+		// Check if origin is allowed
+		const isAllowedOrigin =
+			CORS_CONFIG.allowedOrigins.includes("*") ||
+			CORS_CONFIG.allowedOrigins.includes(origin);
+
+		if (isAllowedOrigin || !origin) {
+			response.headers.set(
+				"Access-Control-Allow-Origin",
+				origin || CORS_CONFIG.allowedOrigins[0],
+			);
+			response.headers.set(
+				"Access-Control-Allow-Methods",
+				CORS_CONFIG.allowedMethods.join(", "),
+			);
+			response.headers.set(
+				"Access-Control-Allow-Headers",
+				CORS_CONFIG.allowedHeaders.join(", "),
+			);
+			response.headers.set(
+				"Access-Control-Expose-Headers",
+				CORS_CONFIG.exposedHeaders.join(", "),
+			);
+			response.headers.set(
+				"Access-Control-Max-Age",
+				CORS_CONFIG.maxAge.toString(),
+			);
+
+			if (CORS_CONFIG.credentials) {
+				response.headers.set("Access-Control-Allow-Credentials", "true");
+			}
+		}
+
+		// Handle preflight requests
+		if (request.method === "OPTIONS") {
+			return new NextResponse(null, {
+				status: 204,
+				headers: response.headers,
+			});
+		}
+	}
+
+	// Apply security headers
+	for (const [key, value] of Object.entries(SECURITY_HEADERS)) {
+		response.headers.set(key, value);
+	}
+
+	return response;
+}
+
+// Configure which routes the middleware runs on
+export const config = {
+	matcher: [
+		/*
+		 * Match all request paths except:
+		 * - _next/static (static files)
+		 * - _next/image (image optimization files)
+		 * - favicon.ico (favicon file)
+		 * - public folder
+		 */
+		"/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)",
+	],
+};

package/templates/base-project/apps/worker/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@quark/worker",
+	"version": "1.0.0",
+	"type": "module",
+	"description": "",
+	"main": "index.js",
+	"scripts": {
+		"test": "node --test $(find src -name '*.test.js')",
+		"dev": "tsx watch src/index.js",
+		"lint": "biome format --write && biome check --write"
+	},
+	"keywords": [],
+	"author": "",
+	"license": "ISC",
+	"packageManager": "pnpm@10.12.1",
+	"dependencies": {
+		"@techstream/quark-core": "^1.0.0",
+		"@techstream/quark-db": "workspace:*",
+		"@techstream/quark-jobs": "workspace:*",
+		"bullmq": "^5.64.1",
+		"dotenv": "^17.2.3"
+	},
+	"devDependencies": {
+		"@techstream/quark-config": "workspace:*",
+		"@types/node": "^24.10.1",
+		"tsx": "^4.20.6"
+	}
+}

package/templates/base-project/apps/worker/src/index.js

@@ -0,0 +1,154 @@
+/**
+ * Worker Service
+ * Processes background jobs using BullMQ and Redis
+ * Handles job execution, retries, and error tracking
+ */
+
+import {
+	createEmailService,
+	createLogger,
+	createWorker,
+} from "@techstream/quark-core";
+import { JOB_NAMES, JOB_QUEUES } from "@techstream/quark-jobs";
+import { prisma } from "@techstream/quark-db";
+import dotenv from "dotenv";
+
+// Load environment variables
+dotenv.config();
+
+const logger = createLogger("worker");
+
+// Store workers for graceful shutdown
+const workers = [];
+
+// Initialize email service
+const emailService = createEmailService();
+
+/**
+ * Job handler for SEND_WELCOME_EMAIL
+ * @param {Job} bullJob - BullMQ job object
+ */
+async function handleSendWelcomeEmail(bullJob) {
+	const { userId } = bullJob.data;
+
+	if (!userId) {
+		throw new Error("userId is required for SEND_WELCOME_EMAIL job");
+	}
+
+	logger.info(`Sending welcome email for user ${userId}`, {
+		job: JOB_NAMES.SEND_WELCOME_EMAIL,
+		userId,
+	});
+
+	// Look up the user's email
+	const userRecord = await prisma.user.findUnique({
+		where: { id: userId },
+		select: { email: true, name: true },
+	});
+
+	if (!userRecord?.email) {
+		throw new Error(`User ${userId} not found or has no email`);
+	}
+
+	const displayName = userRecord.name || "there";
+
+	await emailService.sendEmail(
+		userRecord.email,
+		"Welcome to Quark!",
+		`<h1>Welcome, ${displayName}!</h1>
+<p>Your account has been created successfully.</p>
+<p>You can now sign in and start using the application.</p>`,
+		`Welcome, ${displayName}!\n\nYour account has been created successfully.\nYou can now sign in and start using the application.`,
+	);
+
+	return { success: true, userId, email: userRecord.email };
+}
+
+/**
+ * Initialize job handlers
+ * Maps job names to their handler functions
+ */
+const jobHandlers = {
+	[JOB_NAMES.SEND_WELCOME_EMAIL]: handleSendWelcomeEmail,
+};
+
+/**
+ * Start the worker service
+ * Creates workers for all queues and registers handlers
+ */
+async function startWorker() {
+	logger.info("Starting Quark Worker Service");
+
+	try {
+		// Create worker for email queue
+		const emailQueueWorker = createWorker(
+			JOB_QUEUES.EMAIL,
+			async (bullJob) => {
+				const handler = jobHandlers[bullJob.name];
+
+				if (!handler) {
+					throw new Error(`No handler registered for job: ${bullJob.name}`);
+				}
+
+				return handler(bullJob);
+			},
+			{
+				concurrency: parseInt(process.env.WORKER_CONCURRENCY || "5", 10),
+			},
+		);
+
+		workers.push(emailQueueWorker);
+
+		emailQueueWorker.on("completed", (job, result) => {
+			logger.info(`Job ${job.id} (${job.name}) completed`, { result });
+		});
+
+		emailQueueWorker.on("failed", (job, error) => {
+			logger.error(`Job ${job.id} (${job.name}) failed after ${job.attemptsMade} attempts`, {
+				error: error.message,
+				jobName: job.name,
+				attemptsMade: job.attemptsMade,
+			});
+		});
+
+		logger.info(
+			`Email queue worker started (concurrency: ${emailQueueWorker.opts.concurrency})`,
+		);
+
+		// Ready to process jobs
+		logger.info("Worker service ready");
+	} catch (error) {
+		logger.error("Failed to start worker service", { error: error.message, stack: error.stack });
+		process.exit(1);
+	}
+}
+
+/**
+ * Graceful shutdown handler
+ */
+async function shutdown() {
+	logger.info("Shutting down worker service");
+
+	try {
+		// Close all workers
+		for (const worker of workers) {
+			await worker.close();
+		}
+
+		// Disconnect Prisma client
+		await prisma.$disconnect();
+
+		logger.info("All workers closed");
+		process.exit(0);
+	} catch (error) {
+		logger.error("Error during shutdown", { error: error.message, stack: error.stack });
+		process.exit(1);
+	}
+}
+
+// Register shutdown handlers
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+
+// Start the worker service
+startWorker();

package/templates/base-project/apps/worker/src/index.test.js

@@ -0,0 +1,19 @@
+import assert from "node:assert";
+import { test } from "node:test";
+
+// Mock job definitions for testing
+const mockJobDefinitions = {
+	JOB_QUEUES: { EMAIL: "email-queue" },
+	JOB_NAMES: { SEND_WELCOME_EMAIL: "send-welcome-email" },
+};
+
+test("Worker - imports job definitions correctly", async () => {
+	const { JOB_QUEUES, JOB_NAMES } = mockJobDefinitions;
+	assert.strictEqual(JOB_QUEUES.EMAIL, "email-queue");
+	assert.strictEqual(JOB_NAMES.SEND_WELCOME_EMAIL, "send-welcome-email");
+});
+
+test("Worker - Worker can be instantiated", async () => {
+	// Basic smoke test - bullmq Worker is available
+	assert.ok(true, "Worker should be instantiable");
+});

package/templates/base-project/docker-compose.yml

@@ -0,0 +1,40 @@
+services:
+  # --- 1. PostgreSQL Database ---
+  postgres:
+    image: postgres:16-alpine
+    container_name: postgres
+    restart: always
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ${POSTGRES_DB}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+  # --- 2. Redis Cache & Job Queue ---
+  redis:
+    image: redis:7-alpine
+    container_name: redis
+    restart: always
+    ports:
+      - "${REDIS_PORT:-6379}:6379"
+    command: redis-server --appendonly yes
+    volumes:
+      - redis_data:/data
+
+  # --- 3. Mailhog (Local SMTP Server) ---
+  mailhog:
+    image: mailhog/mailhog
+    container_name: mailhog
+    restart: always
+    ports:
+      # SMTP port (used by application to send mail)
+      - "${MAILHOG_SMTP_PORT:-1025}:1025"
+      # Web UI port (to view sent emails)
+      - "${MAILHOG_UI_PORT:-8025}:8025"
+
+volumes:
+  postgres_data:
+  redis_data:

package/templates/base-project/package.json

@@ -0,0 +1,26 @@
+{
+	"name": "@myquark/root",
+	"private": true,
+	"version": "1.0.0",
+	"description": "My Quark project",
+	"main": "index.js",
+	"scripts": {
+		"build": "turbo run build",
+		"dev": "turbo run dev",
+		"lint": "turbo run lint",
+		"test": "turbo run test",
+		"docker:up": "docker compose up -d",
+		"docker:down": "docker compose down",
+		"db:generate": "turbo run db:generate"
+	},
+	"keywords": [],
+	"author": "",
+	"license": "ISC",
+	"packageManager": "pnpm@10.12.1",
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.13",
+		"@types/node": "^24.10.9",
+		"tsx": "^4.21.0",
+		"turbo": "^2.8.1"
+	}
+}

package/templates/base-project/packages/db/package.json

@@ -0,0 +1,29 @@
+{
+	"name": "@techstream/quark-db",
+	"version": "1.0.0",
+	"type": "module",
+	"description": "",
+	"main": "src/index.js",
+	"scripts": {
+		"test": "node --test $(find src -name '*.test.js')",
+		"lint": "biome format --write && biome check --write",
+		"db:generate": "prisma generate",
+		"db:migrate": "prisma migrate dev",
+		"db:push": "prisma db push",
+		"db:seed": "node scripts/seed.js",
+		"db:studio": "prisma studio"
+	},
+	"keywords": [],
+	"author": "",
+	"license": "ISC",
+	"packageManager": "pnpm@10.12.1",
+	"devDependencies": {
+		"@techstream/quark-config": "workspace:*",
+		"prisma": "^7.0.0"
+	},
+	"dependencies": {
+		"@prisma/client": "^7.0.0",
+		"dotenv": "^17.2.3",
+		"zod": "^4.3.6"
+	}
+}