create-stackr 0.2.0

package/templates/base/backend/Dockerfile.ejs

@@ -0,0 +1,142 @@
+# Simplified Multi-stage Dockerfile for Node.js/Fastify Backend
+# Clean architecture with explicit service stages
+# Supports npm, yarn, and bun package managers
+
+# =============================================================================
+# Base Stage - Common setup for all services
+# =============================================================================
+<% if (packageManager === 'bun') { %>FROM oven/bun:alpine AS base<% } else { %>FROM node:alpine AS base<% } %>
+
+# Install essential packages
+RUN apk --no-cache add dumb-init ca-certificates
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files and lock file for dependency installation
+COPY package*.json ./
+<% if (packageManager === 'bun') { %>COPY bun.lock* ./<% } else if (packageManager === 'npm') { %>COPY package-lock.json ./<% } else { %>COPY yarn.lock ./<% } %>
+<% if (backend.orm === 'prisma') { %>
+COPY prisma/schema.prisma ./prisma/
+COPY prisma.config.ts ./
+<% } else if (backend.orm === 'drizzle') { %>
+COPY drizzle/schema.ts ./drizzle/
+COPY drizzle.config.ts ./
+<% } %>
+COPY .env ./
+
+# Install dependencies and generate ORM client
+<% if (packageManager === 'bun') { %>RUN bun install && bun run db:generate<% } else if (packageManager === 'npm') { %>RUN npm ci && npm run db:generate<% } else { %>RUN yarn install --frozen-lockfile && yarn db:generate<% } %>
+
+# Copy source code
+COPY . .
+
+# =============================================================================
+# Development Stages - For local development with hot reload
+# =============================================================================
+FROM base AS rest-api-dev
+EXPOSE 8080
+<% if (packageManager === 'bun') { %>CMD ["dumb-init", "bun", "run", "dev:rest-api"]<% } else if (packageManager === 'npm') { %>CMD ["dumb-init", "npm", "run", "dev:rest-api"]<% } else { %>CMD ["dumb-init", "yarn", "dev:rest-api"]<% } %>
+
+FROM base AS event-queue-dev
+<% if (packageManager === 'bun') { %>CMD ["dumb-init", "bun", "run", "dev:event-queue"]<% } else if (packageManager === 'npm') { %>CMD ["dumb-init", "npm", "run", "dev:event-queue"]<% } else { %>CMD ["dumb-init", "yarn", "dev:event-queue"]<% } %>
+
+# =============================================================================
+# Production Stages - Optimized for production deployment
+# =============================================================================
+<% if (packageManager === 'bun') { %>FROM oven/bun:alpine AS rest-api-prod<% } else { %>FROM node:alpine AS rest-api-prod<% } %>
+
+# Install essential packages and create non-root user
+RUN apk --no-cache add dumb-init ca-certificates \
+<% if (packageManager === 'bun') { %>    && addgroup -g 1001 -S bunjs \
+    && adduser -S backend -u 1001 -G bunjs<% } else { %>    && addgroup -g 1001 -S nodejs \
+    && adduser -S backend -u 1001 -G nodejs<% } %>
+
+# Set production environment
+ENV NODE_ENV=production
+WORKDIR /app
+
+# Copy package files and lock file first (for better layer caching)
+COPY package*.json ./
+<% if (packageManager === 'bun') { %>COPY bun.lock* ./<% } else if (packageManager === 'npm') { %>COPY package-lock.json ./<% } else { %>COPY yarn.lock ./<% } %>
+
+# Install production dependencies only (clean install)
+<% if (packageManager === 'bun') { %>RUN bun install --production<% } else if (packageManager === 'npm') { %>RUN npm ci --production<% } else { %>RUN yarn install --production --frozen-lockfile<% } %>
+
+# Copy ORM schema, config, and generate client
+<% if (backend.orm === 'prisma') { %>
+COPY prisma/schema.prisma ./prisma/
+COPY prisma.config.ts ./
+<% } else if (backend.orm === 'drizzle') { %>
+COPY drizzle/schema.ts ./drizzle/
+COPY drizzle.config.ts ./
+<% } %>
+COPY .env ./
+<% if (packageManager === 'bun') { %>RUN bun run db:generate<% } else if (packageManager === 'npm') { %>RUN npm run db:generate<% } else { %>RUN yarn db:generate<% } %>
+
+# Copy source code
+COPY . .
+
+# Build the TypeScript application
+<% if (packageManager === 'bun') { %>RUN bun run build<% } else if (packageManager === 'npm') { %>RUN npm run build<% } else { %>RUN yarn build<% } %>
+
+# Change ownership to non-root user
+<% if (packageManager === 'bun') { %>RUN chown -R backend:bunjs /app<% } else { %>RUN chown -R backend:nodejs /app<% } %>
+
+# Switch to non-root user
+USER backend
+
+# Expose port and add health check
+EXPOSE 8080
+<% if (packageManager === 'bun') { %>HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD bun -e "const res = await fetch('http://localhost:8080/'); process.exit(res.ok ? 0 : 1)"<% } else { %>HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD node -e "fetch('http://localhost:8080/').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"<% } %>
+
+# Start the REST API service
+<% if (packageManager === 'bun') { %>CMD ["dumb-init", "bun", "run", "start:rest-api"]<% } else if (packageManager === 'npm') { %>CMD ["dumb-init", "npm", "run", "start:rest-api"]<% } else { %>CMD ["dumb-init", "yarn", "start:rest-api"]<% } %>
+
+# =============================================================================
+<% if (packageManager === 'bun') { %>FROM oven/bun:alpine AS event-queue-prod<% } else { %>FROM node:alpine AS event-queue-prod<% } %>
+
+# Install essential packages and create non-root user
+RUN apk --no-cache add dumb-init ca-certificates \
+<% if (packageManager === 'bun') { %>    && addgroup -g 1001 -S bunjs \
+    && adduser -S backend -u 1001 -G bunjs<% } else { %>    && addgroup -g 1001 -S nodejs \
+    && adduser -S backend -u 1001 -G nodejs<% } %>
+
+# Set production environment
+ENV NODE_ENV=production
+WORKDIR /app
+
+# Copy package files and lock file first (for better layer caching)
+COPY package*.json ./
+<% if (packageManager === 'bun') { %>COPY bun.lock* ./<% } else if (packageManager === 'npm') { %>COPY package-lock.json ./<% } else { %>COPY yarn.lock ./<% } %>
+
+# Install production dependencies only (clean install)
+<% if (packageManager === 'bun') { %>RUN bun install --production<% } else if (packageManager === 'npm') { %>RUN npm ci --production<% } else { %>RUN yarn install --production --frozen-lockfile<% } %>
+
+# Copy ORM schema, config, and generate client
+<% if (backend.orm === 'prisma') { %>
+COPY prisma/schema.prisma ./prisma/
+COPY prisma.config.ts ./
+<% } else if (backend.orm === 'drizzle') { %>
+COPY drizzle/schema.ts ./drizzle/
+COPY drizzle.config.ts ./
+<% } %>
+COPY .env ./
+<% if (packageManager === 'bun') { %>RUN bun run db:generate<% } else if (packageManager === 'npm') { %>RUN npm run db:generate<% } else { %>RUN yarn db:generate<% } %>
+
+# Copy source code
+COPY . .
+
+# Build the TypeScript application
+<% if (packageManager === 'bun') { %>RUN bun run build<% } else if (packageManager === 'npm') { %>RUN npm run build<% } else { %>RUN yarn build<% } %>
+
+# Change ownership to non-root user
+<% if (packageManager === 'bun') { %>RUN chown -R backend:bunjs /app<% } else { %>RUN chown -R backend:nodejs /app<% } %>
+
+# Switch to non-root user
+USER backend
+
+# Start the event queue service
+<% if (packageManager === 'bun') { %>CMD ["dumb-init", "bun", "run", "start:event-queue"]<% } else if (packageManager === 'npm') { %>CMD ["dumb-init", "npm", "run", "start:event-queue"]<% } else { %>CMD ["dumb-init", "yarn", "start:event-queue"]<% } %>

package/templates/base/backend/controllers/event-queue/index.ts

@@ -0,0 +1,20 @@
+import dotenv from "dotenv";
+dotenv.config({ path: ".env" });
+
+import { Redis } from "ioredis";
+import { createUserWorker } from "./workers/user";
+
+const redisConnection = new Redis({
+  host: process.env.REDIS_HOST || "localhost",
+  port: parseInt(process.env.REDIS_PORT || "6379"),
+  password: process.env.REDIS_PASSWORD || "",
+  maxRetriesPerRequest: null,
+});
+
+// Create a account worker
+const userWorker = createUserWorker(redisConnection, {
+  concurrency: 20,
+  autorun: true,
+});
+
+console.log("User worker started");

package/templates/base/backend/controllers/event-queue/workers/user.ts

@@ -0,0 +1,39 @@
+import { Worker, Job } from "bullmq";
+import { Redis, Cluster as RedisCluster } from "ioredis";
+
+/**
+ * User Worker
+ *
+ * Note: User creation/authentication is handled by Better Auth.
+ * This worker handles async user-related tasks like sending welcome emails,
+ * syncing with external services, etc.
+ */
+export const createUserWorker = (
+  connection: Redis | RedisCluster,
+  options: {
+    concurrency?: number;
+    autorun?: boolean;
+  }
+) => {
+  return new Worker(
+    "user",
+    async (job: Job) => {
+      switch (job.name) {
+        case "send_welcome_email":
+          // TODO: Implement welcome email sending
+          console.log(`Sending welcome email to user: ${job.data.userId}`);
+          break;
+        case "sync_user_profile":
+          // TODO: Sync user profile with external services
+          console.log(`Syncing profile for user: ${job.data.userId}`);
+          break;
+        default:
+          console.log(`Unknown job: ${job.name}`);
+      }
+    },
+    {
+      connection,
+      ...options,
+    }
+  );
+};

package/templates/base/backend/controllers/rest-api/index.ts

@@ -0,0 +1,48 @@
+import server from "./server";
+
+const start = async () => {
+  try {
+    const host = server.config.API_HOST || '0.0.0.0';
+    const port = parseInt(server.config.API_PORT || '8080');
+    
+    await server.listen({
+      host,
+      port,
+    });
+    
+    console.log(`🚀 Server is running at http://${host}:${port}`);
+    console.log(`📚 API Documentation available at http://${host}:${port}/documentation (if enabled)`);
+    
+  } catch (error) {
+    server.log.error(error);
+    console.error('❌ Failed to start server:', error);
+    process.exit(1);
+  }
+};
+
+// Handle graceful shutdown
+process.on('SIGINT', async () => {
+  console.log('\n🛑 Received SIGINT, gracefully shutting down...');
+  try {
+    await server.close();
+    console.log('✅ Server closed successfully');
+    process.exit(0);
+  } catch (error) {
+    console.error('❌ Error during shutdown:', error);
+    process.exit(1);
+  }
+});
+
+process.on('SIGTERM', async () => {
+  console.log('\n🛑 Received SIGTERM, gracefully shutting down...');
+  try {
+    await server.close();
+    console.log('✅ Server closed successfully');
+    process.exit(0);
+  } catch (error) {
+    console.error('❌ Error during shutdown:', error);
+    process.exit(1);
+  }
+});
+
+start();

package/templates/base/backend/controllers/rest-api/plugins/auth.ts

@@ -0,0 +1,152 @@
+import type {
+  AuthFastifyRequest,
+  DeviceSessionFastifyRequest,
+  AuthOrDeviceSessionFastifyRequest,
+} from "fastify";
+import { FastifyPluginAsync, FastifyRequest, FastifyReply } from "fastify";
+import fp from "fastify-plugin";
+import { auth, Session } from "../../../lib/auth";
+import { validateDeviceSession, updateDeviceSessionActivity } from "../../../domain/device-session/repository";
+import { DeviceSession } from "../../../domain/device-session/schema";
+import { ErrorFactory, normalizeError } from "../../../utils/errors";
+
+/**
+ * Convert Node.js/Fastify headers to Web API Headers object for BetterAuth
+ */
+function toHeaders(requestHeaders: FastifyRequest["headers"]): Headers {
+  const headers = new Headers();
+  Object.entries(requestHeaders).forEach(([key, value]) => {
+    if (value) headers.set(key, Array.isArray(value) ? value[0] : value);
+  });
+  return headers;
+}
+
+const authPlugin: FastifyPluginAsync = async (server) => {
+  // Authenticated user middleware (using BetterAuth session)
+  // Uses cookie-based authentication for both mobile and web clients
+  server.decorate(
+    "requireAuth",
+    async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {
+      try {
+        // Validate session via BetterAuth (reads cookies from headers)
+        const session = await auth.api.getSession({
+          headers: toHeaders(request.headers),
+        });
+
+        if (!session || !session.user) {
+          throw ErrorFactory.unauthorized();
+        }
+
+        // Attach to request
+        (request as AuthFastifyRequest).user = session.user;
+        (request as AuthFastifyRequest).session = session.session;
+      } catch (error) {
+        const appError = normalizeError(error);
+        const response = appError.toApiResponse(request.id, request.url);
+        return reply.status(appError.statusCode).send(response);
+      }
+    }
+  );
+
+  // Anonymous device session middleware (for device-based sessions before auth)
+  server.decorate(
+    "requireDeviceSession",
+    async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {
+      try {
+        const sessionTokenHeader = request.headers["x-device-session-token"] as string;
+        if (!sessionTokenHeader) {
+          throw ErrorFactory.tokenMissing();
+        }
+
+        const deviceSession = await validateDeviceSession(sessionTokenHeader);
+        if (!deviceSession) {
+          throw ErrorFactory.sessionNotFound();
+        }
+
+        await updateDeviceSessionActivity(sessionTokenHeader);
+
+        (request as DeviceSessionFastifyRequest).deviceSession = deviceSession;
+        (request as DeviceSessionFastifyRequest).sessionToken = sessionTokenHeader;
+      } catch (error) {
+        const appError = normalizeError(error);
+        const response = appError.toApiResponse(request.id, request.url);
+        return reply.status(appError.statusCode).send(response);
+      }
+    }
+  );
+
+  // Flexible auth: accepts either BetterAuth session or device session
+  server.decorate(
+    "requireAuthOrDeviceSession",
+    async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {
+      try {
+        // Try BetterAuth session first (cookie-based)
+        try {
+          const session = await auth.api.getSession({
+            headers: toHeaders(request.headers),
+          });
+
+          if (session && session.user) {
+            (request as AuthOrDeviceSessionFastifyRequest).user = session.user;
+            (request as AuthOrDeviceSessionFastifyRequest).session = session.session;
+            (request as AuthOrDeviceSessionFastifyRequest).authType = "user";
+            return;
+          }
+        } catch {
+          // BetterAuth session not found, try device session
+        }
+
+        // Try device session
+        const sessionTokenHeader = request.headers["x-device-session-token"] as string;
+        if (sessionTokenHeader) {
+          const deviceSession = await validateDeviceSession(sessionTokenHeader);
+          if (deviceSession) {
+            await updateDeviceSessionActivity(sessionTokenHeader);
+            (request as AuthOrDeviceSessionFastifyRequest).deviceSession = deviceSession;
+            (request as AuthOrDeviceSessionFastifyRequest).sessionToken = sessionTokenHeader;
+            (request as AuthOrDeviceSessionFastifyRequest).authType = "device";
+            return;
+          }
+        }
+
+        throw ErrorFactory.unauthorized();
+      } catch (error) {
+        const appError = normalizeError(error);
+        const response = appError.toApiResponse(request.id, request.url);
+        return reply.status(appError.statusCode).send(response);
+      }
+    }
+  );
+};
+
+// Extend Fastify module with auth types and middleware decorators
+declare module "fastify" {
+  // For authenticated users (BetterAuth session)
+  export interface AuthFastifyRequest extends FastifyRequest {
+    user: Session["user"];
+    session: Session["session"];
+  }
+
+  // For device/anonymous sessions (before user authentication)
+  export interface DeviceSessionFastifyRequest extends FastifyRequest {
+    deviceSession: DeviceSession;
+    sessionToken: string;
+  }
+
+  // For endpoints that accept either auth type
+  export interface AuthOrDeviceSessionFastifyRequest extends FastifyRequest {
+    user?: Session["user"];
+    session?: Session["session"];
+    deviceSession?: DeviceSession;
+    sessionToken?: string;
+    authType: "user" | "device";
+  }
+
+  interface FastifyInstance {
+    requireAuth: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    requireDeviceSession: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    requireAuthOrDeviceSession: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  }
+}
+
+export default fp(authPlugin);

package/templates/base/backend/controllers/rest-api/plugins/config.ts

@@ -0,0 +1,64 @@
+import fp from "fastify-plugin";
+import { FastifyPluginAsync } from "fastify";
+import { Static, Type } from "@sinclair/typebox";
+import Ajv from "ajv";
+
+import dotenv from "dotenv";
+dotenv.config();
+
+export enum NodeEnv {
+  development = "development",
+  test = "test",
+  production = "production",
+}
+
+const ConfigSchema = Type.Object({
+  NODE_ENV: Type.Optional(Type.Enum(NodeEnv)),
+  LOG_LEVEL: Type.Optional(Type.String()),
+  API_HOST: Type.Optional(Type.String()),
+  API_PORT: Type.Optional(Type.String()),
+  DATABASE_URL: Type.String(),
+  JWT_SECRET: Type.Optional(Type.String()),
+});
+
+const ajv = new Ajv({
+  allErrors: true,
+  removeAdditional: true,
+  useDefaults: true,
+  coerceTypes: true,
+});
+
+export type Config = Static<typeof ConfigSchema>;
+
+const configPlugin: FastifyPluginAsync = async (server) => {
+  // Set defaults for optional fields
+  const configWithDefaults = {
+    NODE_ENV: process.env.NODE_ENV || 'development',
+    LOG_LEVEL: process.env.LOG_LEVEL || 'info',
+    API_HOST: process.env.API_HOST || '0.0.0.0',
+    API_PORT: process.env.API_PORT || '8080',
+    DATABASE_URL: process.env.DATABASE_URL,
+    JWT_SECRET: process.env.JWT_SECRET || 'your-jwt-secret-here-change-in-production',
+    ...process.env,
+  };
+
+  const validate = ajv.compile(ConfigSchema);
+  const valid = validate(configWithDefaults);
+  
+  if (!valid) {
+    throw new Error(
+      ".env file validation failed - " +
+        JSON.stringify(validate.errors, null, 2)
+    );
+  }
+  
+  server.decorate("config", configWithDefaults as Config);
+};
+
+declare module "fastify" {
+  interface FastifyInstance {
+    config: Config;
+  }
+}
+
+export default fp(configPlugin);

package/templates/base/backend/controllers/rest-api/plugins/error-handler.ts

@@ -0,0 +1,118 @@
+import fp from "fastify-plugin";
+import { FastifyPluginAsync, FastifyError, FastifyRequest, FastifyReply } from "fastify";
+import { AppError, normalizeError, shouldIncludeErrorDetails, ErrorFactory } from "../../../utils/errors";
+
+const errorHandlerPlugin: FastifyPluginAsync = async (server) => {
+  // Global error handler
+  server.setErrorHandler(async (error: FastifyError, request: FastifyRequest, reply: FastifyReply) => {
+    const isDevelopment = process.env.NODE_ENV === 'development';
+    
+    // Log the error for debugging
+    server.log.error({
+      error: {
+        message: error.message,
+        stack: error.stack,
+        statusCode: error.statusCode,
+        validation: error.validation,
+      },
+      request: {
+        id: request.id,
+        method: request.method,
+        url: request.url,
+        headers: request.headers,
+        body: request.body,
+      },
+    }, 'Request error occurred');
+
+    let appError: AppError;
+
+    // Handle different types of errors
+    if (error instanceof AppError) {
+      // Already an AppError, use as-is
+      appError = error;
+    } else if (error.statusCode === 400 && error.validation) {
+      // Fastify validation error
+      appError = ErrorFactory.validationFailed({
+        fields: error.validation,
+        originalMessage: error.message
+      });
+    } else if (error.statusCode === 401) {
+      // Unauthorized error
+      appError = ErrorFactory.tokenInvalid({ originalMessage: error.message });
+    } else if (error.statusCode === 403) {
+      // Forbidden error
+      appError = ErrorFactory.permissionDenied();
+    } else if (error.statusCode === 404) {
+      // Not found error
+      appError = ErrorFactory.resourceNotFound('resource');
+    } else if (error.statusCode && error.statusCode >= 400 && error.statusCode < 500) {
+      // Other client errors
+      appError = ErrorFactory.clientError(
+        error.message || 'Bad request',
+        error.statusCode
+      );
+    } else {
+      // Server errors or unknown errors
+      appError = normalizeError(error);
+    }
+
+    // Determine if we should include error details
+    const includeDetails = shouldIncludeErrorDetails(appError, isDevelopment);
+    
+    // Create the response
+    const response = appError.toApiResponse(request.id, request.url);
+    
+    // Remove details if they shouldn't be included
+    if (!includeDetails) {
+      delete response.error.details;
+    }
+
+    // Add stack trace in development for critical errors
+    if (isDevelopment && appError.severity === 'critical') {
+      response.error.details = {
+        ...response.error.details,
+        stack: error.stack
+      };
+    }
+
+    // Send the error response
+    return reply.status(appError.statusCode).send(response);
+  });
+
+  // Handle 404 errors for routes that don't exist
+  server.setNotFoundHandler(async (request: FastifyRequest, reply: FastifyReply) => {
+    const appError = ErrorFactory.routeNotFound(request.method, request.url);
+    const response = appError.toApiResponse(request.id, request.url);
+    return reply.status(404).send(response);
+  });
+
+  // Add request ID generation for better error tracking
+  server.addHook('onRequest', async (request) => {
+    // Generate a unique request ID if not already present
+    if (!request.id) {
+      request.id = `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+  });
+
+  // Add response time tracking
+  server.addHook('onRequest', async (request) => {
+    (request as any).startTime = Date.now();
+  });
+
+  server.addHook('onResponse', async (request, reply) => {
+    const responseTime = Date.now() - ((request as any).startTime || Date.now());
+    server.log.info({
+      request: {
+        id: request.id,
+        method: request.method,
+        url: request.url,
+      },
+      response: {
+        statusCode: reply.statusCode,
+        responseTime: `${responseTime}ms`
+      }
+    }, 'Request completed');
+  });
+};
+
+export default fp(errorHandlerPlugin);