create-tigra 2.3.0 → 2.5.0

package/bin/create-tigra.js

@@ -216,7 +216,18 @@ async function main() {
         }
 
         // Create .developer-role file (default: fullstack = no restrictions)
-        await fs.writeFile(path.join(targetDir, '.developer-role'), 'fullstack\n', 'utf-8');
+        const developerRoleContent = [
+          'fullstack',
+          '# Available roles (change the first line to switch):',
+          '#',
+          '#   frontend   - Can edit client/ only. Cannot edit server/ files. Can read everything.',
+          '#   backend    - Can edit server/ only. Cannot edit client/ files. Can read everything.',
+          '#   fullstack  - Can edit everything. No restrictions.',
+          '#',
+          '# You can also switch roles using the /role command in Claude.',
+          '',
+        ].join('\n');
+        await fs.writeFile(path.join(targetDir, '.developer-role'), developerRoleContent, 'utf-8');
 
         spinner.succeed('Project scaffolded successfully!');
       } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-tigra",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "type": "module",
   "description": "Create a production-ready full-stack app with Next.js 16 + Fastify 5 + Prisma + Redis",
   "bin": {

package/template/_claude/hooks/restrict-paths.sh

@@ -14,9 +14,9 @@
 
 ROLE_FILE="$CLAUDE_PROJECT_DIR/.developer-role"
 
-# Read role from file, trim whitespace
+# Read role from first non-comment, non-empty line
 if [ -f "$ROLE_FILE" ]; then
-  ROLE=$(tr -d '[:space:]' < "$ROLE_FILE")
+  ROLE=$(grep -v '^\s*#' "$ROLE_FILE" | grep -v '^\s*$' | head -1 | tr -d '[:space:]')
 else
   ROLE=""
 fi

package/template/_claude/rules/server/project-conventions.md

@@ -215,7 +215,15 @@ const apiClient = axios.create({ ...httpClient.defaults, baseURL: 'https://api.e
 
 ## File Storage
 
-Upload directory structure: `uploads/users/{userId}/<media-type>/`
+### Directory Structure Principles
+
+Upload folders must be **scalable and manageable**. Never dump all files into a single flat directory (e.g., all product images under `/uploads/products/`). Instead, organize by **owner/entity ID** so each entity's files are isolated and easy to find, move, or delete.
+
+**Pattern**: `uploads/<domain>/{entityId}/<media-type>/`
+
+### User Uploads
+
+Structure: `uploads/users/{userId}/<media-type>/`
 
 | Media type | Path | Example |
 |---|---|---|
@@ -225,3 +233,22 @@ Upload directory structure: `uploads/users/{userId}/<media-type>/`
 - On account purge, delete the entire `uploads/users/{userId}/` directory via `deleteUserMedia()`.
 - Public URL pattern: `/uploads/users/{userId}/<media-type>/{filename}`
 - New media types follow the same pattern: add a subfolder under the user directory.
+
+### Domain Entity Uploads (Products, Articles, etc.)
+
+Structure: `uploads/<domain>/{entityId}/<media-type>/`
+
+| Domain | Media type | Path | Example |
+|---|---|---|---|
+| Products | Images | `uploads/products/{productId}/images/` | `uploads/products/prod-456/images/front-view.webp` |
+| Products | Thumbnails | `uploads/products/{productId}/thumbnails/` | `uploads/products/prod-456/thumbnails/front-view-thumb.webp` |
+| Articles | Cover | `uploads/articles/{articleId}/cover/` | `uploads/articles/art-789/cover/hero.webp` |
+| Articles | Content images | `uploads/articles/{articleId}/content/` | `uploads/articles/art-789/content/diagram-1.webp` |
+
+### Rules
+
+1. **Never use flat directories** — `uploads/products/img1.jpg, img2.jpg, ...` is forbidden. Always namespace by entity ID.
+2. **One folder per entity instance** — makes deletion, migration, and backup trivial (`rm -rf uploads/products/{id}/`).
+3. **Separate media types into subfolders** — don't mix avatars, thumbnails, and full-size images in the same folder.
+4. **Entity cleanup** — when an entity is deleted, remove its entire upload directory (e.g., `uploads/products/{productId}/`).
+5. **Consistent naming** — use kebab-case for filenames, domain plural for top-level folders (`products`, `articles`, `users`).

package/template/client/.dockerignore

@@ -0,0 +1,63 @@
+# Dependencies (will be installed fresh in Docker)
+node_modules
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Build output (will be built fresh in Docker)
+.next
+out
+*.tsbuildinfo
+
+# Environment files (use Docker env vars instead)
+.env
+.env.local
+.env.*.local
+.env.development
+.env.test
+
+# Git
+.git
+.gitignore
+.gitattributes
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+coverage
+.nyc_output
+**/__tests__
+**/*.test.ts
+**/*.test.tsx
+**/*.spec.ts
+**/*.spec.tsx
+vitest.config.ts
+jest.config.ts
+
+# Documentation
+docs
+CHANGELOG.md
+LICENSE
+
+# Docker
+Dockerfile
+.dockerignore
+docker-compose.yml
+
+# CI/CD
+.github
+.gitlab-ci.yml
+.circleci
+
+# Misc
+.prettierrc
+.eslintrc
+.eslintignore
+.editorconfig

package/template/client/Dockerfile

@@ -0,0 +1,98 @@
+# ===================================================================
+# Multi-stage Dockerfile for Next.js Production Deployment
+# Optimized for Coolify, Docker Compose, and Kubernetes
+# Requires `output: "standalone"` in next.config.ts
+# ===================================================================
+
+# ===================================================================
+# Stage 1: Dependencies (cached layer)
+# ===================================================================
+FROM node:20-alpine AS dependencies
+
+WORKDIR /app
+
+# Copy package files
+COPY package.json package-lock.json* pnpm-lock.yaml* yarn.lock* ./
+
+# Install dependencies (use the lockfile that exists)
+RUN if [ -f pnpm-lock.yaml ]; then \
+      npm install -g pnpm && pnpm install --frozen-lockfile; \
+    elif [ -f yarn.lock ]; then \
+      yarn install --frozen-lockfile; \
+    else \
+      npm ci; \
+    fi
+
+# ===================================================================
+# Stage 2: Build (compile Next.js)
+# ===================================================================
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Copy dependencies from previous stage
+COPY --from=dependencies /app/node_modules ./node_modules
+
+# Copy source code
+COPY . .
+
+# Build arguments for env vars needed at build time
+# Next.js inlines NEXT_PUBLIC_* values during build, so they must
+# be available here. Pass them via --build-arg in Coolify/Docker.
+ARG NEXT_PUBLIC_API_BASE_URL
+ARG NEXT_PUBLIC_APP_NAME
+
+ENV NEXT_PUBLIC_API_BASE_URL=$NEXT_PUBLIC_API_BASE_URL
+ENV NEXT_PUBLIC_APP_NAME=$NEXT_PUBLIC_APP_NAME
+
+# Disable Next.js telemetry during build
+ENV NEXT_TELEMETRY_DISABLED=1
+
+# Build the application (outputs to .next/standalone)
+RUN npm run build
+
+# ===================================================================
+# Stage 3: Production Runtime
+# ===================================================================
+FROM node:20-alpine AS production
+
+# Install dumb-init for proper signal handling
+RUN apk add --no-cache dumb-init
+
+# Create non-root user for security
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nextjs -u 1001
+
+WORKDIR /app
+
+# Copy the standalone server (includes only required node_modules)
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+
+# Copy static assets (not included in standalone output)
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+# Copy public folder (favicon, images, etc.)
+COPY --from=builder --chown=nextjs:nodejs /app/public ./public
+
+# Switch to non-root user
+USER nextjs
+
+# Disable telemetry at runtime
+ENV NEXT_TELEMETRY_DISABLED=1
+
+# Set hostname to listen on all interfaces (required in containers)
+ENV HOSTNAME="0.0.0.0"
+
+# Default port (override via PORT env var in Coolify)
+ENV PORT=3000
+EXPOSE 3000
+
+# Health check for container orchestration
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD node -e "const p=process.env.PORT||3000;require('http').get('http://localhost:'+p,(r)=>{process.exit(r.statusCode===200?0:1)})"
+
+# Use dumb-init to handle signals properly
+ENTRYPOINT ["dumb-init", "--"]
+
+# Start the standalone Next.js server
+CMD ["node", "server.js"]

package/template/client/next.config.ts

@@ -10,6 +10,7 @@ const apiOrigin = (() => {
 })();
 
 const nextConfig: NextConfig = {
+  output: "standalone",
   async headers() {
     return [
       {

package/template/client/package.json

@@ -34,7 +34,6 @@
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4",
-    "@tanstack/react-query-devtools": "^5.91.3",
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",

package/template/client/src/app/globals.css

@@ -55,83 +55,85 @@
 
 :root {
   --radius: 0.625rem;
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.145 0 0);
+  /* Claude palette: #f4f3ee (cream), #ffffff (white), #b1ada1 (warm gray), #c15f3c (orange) */
+  --background: oklch(0.964 0.007 97.5);
+  --foreground: oklch(0.205 0.015 92);
   --card: oklch(1 0 0);
-  --card-foreground: oklch(0.145 0 0);
+  --card-foreground: oklch(0.205 0.015 92);
   --popover: oklch(1 0 0);
-  --popover-foreground: oklch(0.145 0 0);
-  --primary: oklch(0.45 0.2 260);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.97 0 0);
-  --secondary-foreground: oklch(0.205 0 0);
-  --muted: oklch(0.97 0 0);
-  --muted-foreground: oklch(0.556 0 0);
-  --accent: oklch(0.97 0 0);
-  --accent-foreground: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.205 0.015 92);
+  --primary: oklch(0.597 0.135 39.9);
+  --primary-foreground: oklch(1 0 0);
+  --secondary: oklch(0.935 0.009 97.5);
+  --secondary-foreground: oklch(0.3 0.015 92);
+  --muted: oklch(0.935 0.009 97.5);
+  --muted-foreground: oklch(0.748 0.017 91.6);
+  --accent: oklch(0.935 0.009 97.5);
+  --accent-foreground: oklch(0.3 0.015 92);
   --destructive: oklch(0.577 0.245 27.325);
-  --border: oklch(0.922 0 0);
-  --input: oklch(0.922 0 0);
-  --ring: oklch(0.45 0.2 260);
+  --border: oklch(0.895 0.012 97.5);
+  --input: oklch(0.895 0.012 97.5);
+  --ring: oklch(0.597 0.135 39.9);
   --success: oklch(0.52 0.17 155);
   --success-foreground: oklch(1 0 0);
-  --warning: oklch(0.75 0.18 75);
-  --warning-foreground: oklch(0.2 0 0);
+  --warning: oklch(0.75 0.15 70);
+  --warning-foreground: oklch(0.25 0.015 92);
   --info: oklch(0.55 0.15 240);
   --info-foreground: oklch(1 0 0);
-  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-1: oklch(0.597 0.135 39.9);
   --chart-2: oklch(0.6 0.118 184.704);
   --chart-3: oklch(0.398 0.07 227.392);
-  --chart-4: oklch(0.828 0.189 84.429);
-  --chart-5: oklch(0.769 0.188 70.08);
-  --sidebar: oklch(0.985 0 0);
-  --sidebar-foreground: oklch(0.145 0 0);
-  --sidebar-primary: oklch(0.205 0 0);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.97 0 0);
-  --sidebar-accent-foreground: oklch(0.205 0 0);
-  --sidebar-border: oklch(0.922 0 0);
-  --sidebar-ring: oklch(0.708 0 0);
+  --chart-4: oklch(0.828 0.12 84);
+  --chart-5: oklch(0.748 0.017 91.6);
+  --sidebar: oklch(0.95 0.007 97.5);
+  --sidebar-foreground: oklch(0.205 0.015 92);
+  --sidebar-primary: oklch(0.3 0.015 92);
+  --sidebar-primary-foreground: oklch(0.964 0.007 97.5);
+  --sidebar-accent: oklch(0.935 0.009 97.5);
+  --sidebar-accent-foreground: oklch(0.3 0.015 92);
+  --sidebar-border: oklch(0.895 0.012 97.5);
+  --sidebar-ring: oklch(0.597 0.135 39.9);
 }
 
 .dark {
-  --background: oklch(0.145 0 0);
-  --foreground: oklch(0.985 0 0);
-  --card: oklch(0.205 0 0);
-  --card-foreground: oklch(0.985 0 0);
-  --popover: oklch(0.205 0 0);
-  --popover-foreground: oklch(0.985 0 0);
-  --primary: oklch(0.6 0.2 260);
-  --primary-foreground: oklch(0.145 0 0);
-  --secondary: oklch(0.269 0 0);
-  --secondary-foreground: oklch(0.985 0 0);
-  --muted: oklch(0.269 0 0);
-  --muted-foreground: oklch(0.708 0 0);
-  --accent: oklch(0.269 0 0);
-  --accent-foreground: oklch(0.985 0 0);
+  /* Dark mode: inverted Claude palette with same warm undertone */
+  --background: oklch(0.185 0.012 92);
+  --foreground: oklch(0.93 0.007 97.5);
+  --card: oklch(0.235 0.012 92);
+  --card-foreground: oklch(0.93 0.007 97.5);
+  --popover: oklch(0.235 0.012 92);
+  --popover-foreground: oklch(0.93 0.007 97.5);
+  --primary: oklch(0.66 0.135 39.9);
+  --primary-foreground: oklch(0.185 0.012 92);
+  --secondary: oklch(0.28 0.012 92);
+  --secondary-foreground: oklch(0.93 0.007 97.5);
+  --muted: oklch(0.28 0.012 92);
+  --muted-foreground: oklch(0.65 0.015 91.6);
+  --accent: oklch(0.28 0.012 92);
+  --accent-foreground: oklch(0.93 0.007 97.5);
   --destructive: oklch(0.704 0.191 22.216);
-  --border: oklch(1 0 0 / 10%);
-  --input: oklch(1 0 0 / 15%);
-  --ring: oklch(0.6 0.2 260);
+  --border: oklch(1 0.007 97.5 / 12%);
+  --input: oklch(1 0.007 97.5 / 15%);
+  --ring: oklch(0.66 0.135 39.9);
   --success: oklch(0.6 0.17 155);
   --success-foreground: oklch(1 0 0);
-  --warning: oklch(0.8 0.18 75);
-  --warning-foreground: oklch(0.2 0 0);
+  --warning: oklch(0.8 0.15 70);
+  --warning-foreground: oklch(0.25 0.015 92);
   --info: oklch(0.65 0.15 240);
   --info-foreground: oklch(1 0 0);
-  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-1: oklch(0.66 0.135 39.9);
   --chart-2: oklch(0.696 0.17 162.48);
-  --chart-3: oklch(0.769 0.188 70.08);
-  --chart-4: oklch(0.627 0.265 303.9);
-  --chart-5: oklch(0.645 0.246 16.439);
-  --sidebar: oklch(0.205 0 0);
-  --sidebar-foreground: oklch(0.985 0 0);
-  --sidebar-primary: oklch(0.488 0.243 264.376);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.269 0 0);
-  --sidebar-accent-foreground: oklch(0.985 0 0);
-  --sidebar-border: oklch(1 0 0 / 10%);
-  --sidebar-ring: oklch(0.556 0 0);
+  --chart-3: oklch(0.769 0.12 70);
+  --chart-4: oklch(0.627 0.18 303.9);
+  --chart-5: oklch(0.645 0.17 16.439);
+  --sidebar: oklch(0.235 0.012 92);
+  --sidebar-foreground: oklch(0.93 0.007 97.5);
+  --sidebar-primary: oklch(0.66 0.135 39.9);
+  --sidebar-primary-foreground: oklch(0.93 0.007 97.5);
+  --sidebar-accent: oklch(0.28 0.012 92);
+  --sidebar-accent-foreground: oklch(0.93 0.007 97.5);
+  --sidebar-border: oklch(1 0.007 97.5 / 12%);
+  --sidebar-ring: oklch(0.66 0.135 39.9);
 }
 
 @layer base {

package/template/client/src/app/layout.tsx

@@ -27,7 +27,7 @@ export default function RootLayout({
   children: React.ReactNode;
 }>): React.ReactElement {
   return (
-    <html lang="en" suppressHydrationWarning>
+    <html lang="en" className="dark" suppressHydrationWarning>
       <body className={`${geistSans.variable} ${geistMono.variable} font-sans antialiased`}>
         <Providers>{children}</Providers>
       </body>

package/template/client/src/app/page.tsx

@@ -1,45 +1,76 @@
-'use client';
-
 import type React from 'react';
-import { LogOut } from 'lucide-react';
+import type { Metadata } from 'next';
+
+import Image from 'next/image';
 
-import { Button } from '@/components/ui/button';
-import { Skeleton } from '@/components/ui/skeleton';
-import { useAppSelector } from '@/store/hooks';
-import { useAuth } from '@/features/auth/hooks/useAuth';
 import { APP_NAME } from '@/lib/constants/app.constants';
 
-export default function WelcomePage(): React.ReactElement {
-  const { user } = useAppSelector((state) => state.auth);
-  const { logout, isLoggingOut } = useAuth();
+export const metadata: Metadata = {
+  title: APP_NAME,
+  description: `Welcome to ${APP_NAME} — generated with create-tigra`,
+};
 
+export default function WelcomePage(): React.ReactElement {
   return (
-    <div className="flex min-h-dvh flex-col">
-      <header className="flex items-center justify-between px-6 py-4">
-        <span className="text-lg font-semibold tracking-tight text-foreground">
+    <div className="relative flex min-h-dvh flex-col items-center justify-center overflow-hidden px-6">
+      {/* Ambient glow */}
+      <div
+        aria-hidden="true"
+        className="pointer-events-none absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2"
+      >
+        <div className="motion-safe:animate-pulse h-64 w-64 rounded-full bg-primary/15 blur-3xl md:h-96 md:w-96" />
+      </div>
+
+      {/* Content */}
+      <div className="relative z-10 flex max-w-md flex-col items-center text-center">
+        {/* Logo */}
+        <div className="mb-8">
+          <Image
+            src="/logo.png"
+            alt={`${APP_NAME} logo`}
+            width={160}
+            height={160}
+            priority
+            className="h-32 w-32 md:h-40 md:w-40"
+          />
+        </div>
+
+        <h1 className="text-3xl font-bold tracking-tight text-foreground md:text-4xl">
           {APP_NAME}
-        </span>
-        <Button
-          variant="ghost"
-          size="sm"
-          onClick={logout}
-          disabled={isLoggingOut}
-          className="text-muted-foreground transition-colors duration-150 hover:text-foreground"
-        >
-          <LogOut className="mr-2 h-4 w-4" />
-          Sign out
-        </Button>
-      </header>
-
-      <main className="flex flex-1 items-center justify-center">
-        {user ? (
-          <h1 className="text-3xl font-light tracking-tight text-foreground">
-            Welcome, {user.firstName}
-          </h1>
-        ) : (
-          <Skeleton className="h-9 w-64" />
-        )}
-      </main>
+        </h1>
+
+        <p className="mt-3 text-base text-muted-foreground md:text-lg">
+          Generated with{' '}
+          <span className="font-semibold text-foreground">create-tigra</span>
+        </p>
+
+        <div className="mt-8 flex flex-col gap-3 sm:flex-row sm:gap-4">
+          <a
+            href="https://github.com/BehzodKarimov/create-tigra"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex min-h-11 items-center justify-center rounded-lg bg-primary px-5 py-2.5 text-sm font-medium text-primary-foreground shadow-sm transition-all duration-200 active:scale-[0.97] md:hover:brightness-110"
+          >
+            Documentation
+          </a>
+          <a
+            href="https://github.com/BehzodKarimov/create-tigra/issues"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex min-h-11 items-center justify-center rounded-lg border border-border bg-secondary px-5 py-2.5 text-sm font-medium text-secondary-foreground transition-all duration-200 active:scale-[0.97] md:hover:bg-accent"
+          >
+            Report an issue
+          </a>
+        </div>
+
+        <p className="mt-12 font-mono text-xs text-muted-foreground md:text-sm">
+          Edit{' '}
+          <code className="rounded-md bg-muted px-1.5 py-0.5">
+            src/app/page.tsx
+          </code>{' '}
+          to get started
+        </p>
+      </div>
     </div>
   );
 }

package/template/client/src/app/providers.tsx

@@ -4,7 +4,6 @@ import type React from 'react';
 import { useState } from 'react';
 
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
 import { Provider as ReduxProvider } from 'react-redux';
 import { ThemeProvider } from 'next-themes';
 import { Toaster } from 'sonner';
@@ -30,13 +29,12 @@ export function Providers({ children }: { children: React.ReactNode }): React.Re
   return (
     <ReduxProvider store={store}>
       <QueryClientProvider client={queryClient}>
-        <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
+        <ThemeProvider attribute="class" defaultTheme="dark" disableTransitionOnChange>
           <AuthInitializer>
             {children}
           </AuthInitializer>
           <Toaster position="top-right" richColors />
         </ThemeProvider>
-        {process.env.NODE_ENV === 'development' && <ReactQueryDevtools initialIsOpen={false} />}
       </QueryClientProvider>
     </ReduxProvider>
   );

package/template/client/src/components/common/SafeImage.tsx

@@ -0,0 +1,48 @@
+'use client';
+
+import type React from 'react';
+
+import Image from 'next/image';
+import type { ImageProps } from 'next/image';
+
+/**
+ * Wraps Next.js <Image> to bypass the optimization proxy for localhost URLs.
+ *
+ * Next.js refuses to fetch images from loopback IPs (127.0.0.1, ::1) through
+ * its optimization proxy — even when remotePatterns allows localhost. This is
+ * a security restriction to prevent SSRF attacks.
+ *
+ * SafeImage detects localhost/loopback URLs and sets `unoptimized` so the
+ * image loads directly via a regular <img> tag. In production with a real
+ * domain, images are optimized normally.
+ */
+
+const LOOPBACK_PATTERNS = [
+  'localhost',
+  '127.0.0.1',
+  '0.0.0.0',
+  '[::1]',
+] as const;
+
+function isLoopbackUrl(src: ImageProps['src']): boolean {
+  if (typeof src !== 'string') return false;
+
+  try {
+    const url = new URL(src);
+    return LOOPBACK_PATTERNS.some((pattern) => url.hostname === pattern);
+  } catch {
+    // Relative path or invalid URL — not a loopback issue
+    return false;
+  }
+}
+
+export const SafeImage = (props: ImageProps): React.ReactElement => {
+  const shouldSkipOptimization = isLoopbackUrl(props.src);
+
+  return (
+    <Image
+      {...props}
+      unoptimized={props.unoptimized || shouldSkipOptimization}
+    />
+  );
+};

package/template/client/src/features/auth/components/AuthInitializer.tsx

@@ -10,12 +10,16 @@ import { ROUTES } from '@/lib/constants/routes';
 import { authService } from '../services/auth.service';
 import { setUser, setInitialized } from '../store/authSlice';
 
-const AUTH_PAGES: string[] = [ROUTES.LOGIN, ROUTES.REGISTER];
+const PROTECTED_PATHS: string[] = [ROUTES.DASHBOARD, ROUTES.PROFILE];
 
 interface AuthInitializerProps {
   children: React.ReactNode;
 }
 
+function isProtectedPath(pathname: string): boolean {
+  return PROTECTED_PATHS.some((path) => pathname.startsWith(path));
+}
+
 export const AuthInitializer = ({ children }: AuthInitializerProps): React.ReactElement => {
   const dispatch = useAppDispatch();
   const pathname = usePathname();
@@ -23,10 +27,12 @@ export const AuthInitializer = ({ children }: AuthInitializerProps): React.React
   const { isAuthenticated, isLoggingOut } = useAppSelector((state) => state.auth);
 
   useEffect(() => {
-    if (AUTH_PAGES.includes(pathname)) {
+    // On public pages, skip auth hydration — just mark as initialized
+    if (!isProtectedPath(pathname)) {
       dispatch(setInitialized());
       return;
     }
+
     if (isAuthenticated || isLoggingOut) return;
 
     let cancelled = false;

package/template/client/src/features/auth/hooks/useAuth.ts

@@ -38,7 +38,7 @@ export const useAuth = (): UseAuthReturn => {
       dispatch(setUser(data.user));
       toast.success('Signed in successfully');
       const from = searchParams.get('from');
-      const redirectTo = from && from.startsWith('/') && !from.startsWith('//') ? from : '/';
+      const redirectTo = from && from.startsWith('/') && !from.startsWith('//') ? from : ROUTES.DASHBOARD;
       router.push(redirectTo);
     },
     onError: (error) => {
@@ -51,7 +51,7 @@ export const useAuth = (): UseAuthReturn => {
     onSuccess: (data) => {
       dispatch(setUser(data.user));
       toast.success('Account created successfully');
-      router.push(ROUTES.HOME);
+      router.push(ROUTES.DASHBOARD);
     },
     onError: (error) => {
       toast.error(getErrorMessage(error));

package/template/client/src/lib/api/axios.config.ts

@@ -9,9 +9,6 @@ const apiClient = axios.create({
   baseURL: process.env.NEXT_PUBLIC_API_BASE_URL || 'http://localhost:8000/api/v1',
   timeout: 30000,
   withCredentials: true, // Send cookies with every request
-  headers: {
-    'Content-Type': 'application/json',
-  },
 });
 
 // No request interceptor needed — cookies are sent automatically
@@ -46,8 +43,15 @@ apiClient.interceptors.response.use(
       return Promise.reject(error);
     }
 
-    // Don't retry refresh endpoint itself
-    if (originalRequest.url === API_ENDPOINTS.AUTH.REFRESH) {
+    // Don't retry auth endpoints that don't use tokens —
+    // a 401 here means wrong credentials, not an expired token.
+    const noRetryEndpoints: string[] = [
+      API_ENDPOINTS.AUTH.LOGIN,
+      API_ENDPOINTS.AUTH.REGISTER,
+      API_ENDPOINTS.AUTH.REFRESH,
+      API_ENDPOINTS.AUTH.RESET_PASSWORD,
+    ];
+    if (noRetryEndpoints.includes(originalRequest.url ?? '')) {
       return Promise.reject(error);
     }
 
@@ -57,6 +61,8 @@ apiClient.interceptors.response.use(
       resetRefreshState();
     }
 
+    originalRequest._retry = true;
+
     if (isRefreshing) {
       return new Promise<void>((resolve, reject) => {
         failedQueue.push({ resolve, reject });
@@ -64,8 +70,6 @@ apiClient.interceptors.response.use(
         return apiClient(originalRequest);
       });
     }
-
-    originalRequest._retry = true;
     isRefreshing = true;
     refreshTimestamp = Date.now();
 
@@ -94,6 +98,9 @@ apiClient.interceptors.response.use(
         store.dispatch(logout());
 
         if (typeof window !== 'undefined') {
+          // Clear session indicator so middleware won't let user through
+          // to protected pages — prevents redirect loops
+          document.cookie = 'auth_session=; Max-Age=0; path=/; SameSite=Strict';
           window.location.href = ROUTES.LOGIN;
         }
       }

package/template/client/src/middleware.ts

@@ -2,8 +2,7 @@ import { NextResponse } from 'next/server';
 
 import type { NextRequest } from 'next/server';
 
-const protectedPaths = ['/', '/dashboard', '/profile', '/admin'];
-const authPaths = ['/login', '/register'];
+const protectedPaths = ['/dashboard', '/profile', '/admin'];
 
 function isTokenExpired(token: string): boolean {
   try {
@@ -17,38 +16,33 @@ function isTokenExpired(token: string): boolean {
 
 export function middleware(request: NextRequest): NextResponse {
   const { pathname } = request.nextUrl;
-  const token = request.cookies.get('access_token')?.value;
+  const accessToken = request.cookies.get('access_token')?.value;
+  const authSession = request.cookies.get('auth_session')?.value;
 
-  const isProtectedPath = protectedPaths.some((path) =>
-    path === '/' ? pathname === '/' : pathname.startsWith(path)
-  );
+  const isProtectedPath = protectedPaths.some((path) => pathname.startsWith(path));
 
-  // No token at all — user is not logged in, redirect to login
-  if (isProtectedPath && !token) {
-    const loginUrl = new URL('/login', request.url);
-    loginUrl.searchParams.set('from', pathname);
-    return NextResponse.redirect(loginUrl);
-  }
-
-  // Expired token on protected path — allow through so client-side can attempt refresh.
-  // Delete the stale access_token so AuthInitializer starts fresh: getMe() → 401 → refresh.
-  if (isProtectedPath && token && isTokenExpired(token)) {
-    const response = NextResponse.next();
-    response.cookies.delete('access_token');
-    return response;
-  }
+  if (isProtectedPath) {
+    // No access_token AND no auth_session — truly unauthenticated
+    if (!accessToken && !authSession) {
+      const loginUrl = new URL('/login', request.url);
+      loginUrl.searchParams.set('from', pathname);
+      return NextResponse.redirect(loginUrl);
+    }
 
-  const isAuthPath = authPaths.some((path) => pathname.startsWith(path));
+    // No access_token BUT auth_session exists — session is alive,
+    // let through so client-side can do getMe() → 401 → refresh → retry
+    if (!accessToken && authSession) {
+      return NextResponse.next();
+    }
 
-  if (isAuthPath && token) {
-    if (isTokenExpired(token)) {
-      // Only delete the expired access token — keep the refresh token
-      // so the client-side interceptor can still recover the session
+    // Expired access_token — delete stale cookie, let through for client-side refresh
+    if (accessToken && isTokenExpired(accessToken)) {
       const response = NextResponse.next();
       response.cookies.delete('access_token');
       return response;
     }
-    return NextResponse.redirect(new URL('/', request.url));
+
+    return NextResponse.next();
   }
 
   return NextResponse.next();
@@ -56,11 +50,8 @@ export function middleware(request: NextRequest): NextResponse {
 
 export const config = {
   matcher: [
-    '/',
     '/dashboard/:path*',
     '/profile/:path*',
     '/admin/:path*',
-    '/login',
-    '/register',
   ],
 };

package/template/server/.dockerignore

@@ -63,4 +63,3 @@ postman/
 .eslintrc
 .eslintignore
 .editorconfig
-tsconfig.json

package/template/server/.env.example

@@ -1,8 +1,18 @@
 # ===================================================================
 # APPLICATION CONFIGURATION
 # ===================================================================
+#
+# COOLIFY DEPLOYMENT NOTE:
+# When adding environment variables in Coolify, do NOT check
+# "Available at Buildtime" for any variable unless explicitly noted.
+# The server Dockerfile handles build-time config internally.
+# All variables below are RUNTIME-ONLY unless marked otherwise.
+#
+# ===================================================================
 
 # Environment: development | production | test
+# COOLIFY: Do NOT check "Available at Buildtime" — the Dockerfile
+# sets NODE_ENV=development during build to ensure devDependencies install.
 NODE_ENV=development
 
 # Server port (default: 8000)
@@ -17,6 +27,7 @@ HOST=0.0.0.0
 
 # Database connection string
 # Format: mysql://username:password@host:port/database
+# COOLIFY: Runtime only. Do NOT check "Available at Buildtime".
 DATABASE_URL="mysql://root:rootpassword@localhost:{{MYSQL_PORT}}/{{DATABASE_NAME}}"
 
 # Connection pool settings (for high-traffic production)
@@ -31,6 +42,7 @@ DATABASE_POOL_MAX=10
 
 # Redis connection URL
 # Format: redis://[:password@]host:port[/database]
+# COOLIFY: Runtime only. Do NOT check "Available at Buildtime".
 REDIS_URL="redis://localhost:{{REDIS_PORT}}"
 
 # Max retry attempts for failed Redis operations
@@ -62,6 +74,13 @@ RATE_LIMIT_MULTIPLIER=1
 # Maximum file upload size in MB (default: 10)
 MAX_FILE_SIZE_MB=10
 
+# COOLIFY PERSISTENT STORAGE (required for uploads to survive redeployments):
+# Go to your service in Coolify → Storages → Add Volume Mount:
+#   Name:             uploads (or <project-name>-uploads)
+#   Source Path:      (leave empty — Coolify manages the Docker volume)
+#   Destination Path: /app/uploads
+# Without this, all uploaded files are lost on every redeployment.
+
 # ===================================================================
 # DOCKER PORTS (auto-generated, unique per project)
 # ===================================================================
@@ -79,6 +98,7 @@ REDIS_COMMANDER_PORT={{REDIS_COMMANDER_PORT}}
 # JWT secret key (MUST be at least 32 characters)
 # CRITICAL: Generate a strong random secret for production!
 # Example: openssl rand -base64 48
+# COOLIFY: Runtime only. Do NOT check "Available at Buildtime" — this is a secret!
 JWT_SECRET="{{JWT_SECRET}}"
 
 # Access token expiry (short-lived)
@@ -92,8 +112,18 @@ JWT_REFRESH_EXPIRY="7d"
 # Cookie signing secret (separate from JWT for defense-in-depth)
 # Optional: defaults to JWT_SECRET if not set
 # For production: generate a separate secret: openssl rand -base64 48
+# COOLIFY: Runtime only. Do NOT check "Available at Buildtime" — this is a secret!
 # COOKIE_SECRET="change-this-to-a-different-secret-at-least-32-chars"
 
+# Cookie domain for cross-origin deployments
+# REQUIRED when client and API are on different subdomains:
+#   Client: https://app.example.com  |  API: https://api.example.com
+#   → Set COOKIE_DOMAIN=".example.com" (note the leading dot)
+# NOT needed when client and API share the same hostname (local dev, same-origin prod)
+# Without this, cookies are scoped to the API hostname only and the browser
+# will silently reject them on cross-origin requests (login appears to do nothing).
+# COOKIE_DOMAIN=".example.com"
+
 # ===================================================================
 # CORS (Cross-Origin Resource Sharing)
 # ===================================================================

package/template/server/.env.example.production

@@ -3,12 +3,22 @@
 # ===================================================================
 # This file contains production-optimized settings for high-traffic
 # deployments (10K-100K users/day). Copy to .env and customize.
+#
+# COOLIFY DEPLOYMENT NOTE:
+# When adding environment variables in Coolify, do NOT check
+# "Available at Buildtime" for any variable unless explicitly noted.
+# The server Dockerfile handles build-time config internally.
+# Secrets (DATABASE_URL, JWT_SECRET, COOKIE_SECRET, REDIS_URL) must
+# NEVER be available at buildtime — they get baked into the image layer.
+#
 # ===================================================================
 
 # ===================================================================
 # APPLICATION
 # ===================================================================
 
+# COOLIFY: Do NOT check "Available at Buildtime" — the Dockerfile
+# sets NODE_ENV=development during build to ensure devDependencies install.
 NODE_ENV=production
 PORT=3000
 HOST=0.0.0.0
@@ -19,6 +29,7 @@ HOST=0.0.0.0
 
 # Production database connection
 # CRITICAL: Use secure credentials, SSL/TLS, and private network
+# COOLIFY: Runtime only. Do NOT check "Available at Buildtime".
 DATABASE_URL="mysql://prod_user:SECURE_PASSWORD@db.internal:3306/prod_db?ssl=true"
 
 # Connection pool for high traffic (10K-100K users/day)
@@ -33,6 +44,7 @@ DATABASE_POOL_MAX=50
 
 # Production Redis instance
 # CRITICAL: Use authentication and private network
+# COOLIFY: Runtime only. Do NOT check "Available at Buildtime".
 REDIS_URL="redis://:REDIS_PASSWORD@redis.internal:6379"
 
 # Production retry settings
@@ -60,18 +72,30 @@ RATE_LIMIT_AUTH_REGISTER_MAX=5
 # Maximum file upload size in MB
 MAX_FILE_SIZE_MB=10
 
+# COOLIFY PERSISTENT STORAGE (required for uploads to survive redeployments):
+# Go to your service in Coolify → Storages → Add Volume Mount:
+#   Name:             uploads (or <project-name>-uploads)
+#   Source Path:      (leave empty — Coolify manages the Docker volume)
+#   Destination Path: /app/uploads
+# Without this, all uploaded files are lost on every redeployment.
+
 # ===================================================================
 # JWT AUTHENTICATION
 # ===================================================================
 
 # CRITICAL: Generate a cryptographically secure secret
 # Example: openssl rand -base64 48
+# COOLIFY: Runtime only. Do NOT check "Available at Buildtime" — this is a secret!
 JWT_SECRET="YOUR_PRODUCTION_JWT_SECRET_MUST_BE_AT_LEAST_32_CHARS_LONG"
 
 # Production token expiry (tighter security)
 JWT_ACCESS_EXPIRY="15m"
 JWT_REFRESH_EXPIRY="7d"
 
+# Cookie signing secret (separate from JWT for defense-in-depth)
+# COOLIFY: Runtime only. Do NOT check "Available at Buildtime" — this is a secret!
+COOKIE_SECRET="YOUR_PRODUCTION_COOKIE_SECRET_MUST_BE_AT_LEAST_32_CHARS"
+
 # ===================================================================
 # CORS
 # ===================================================================
@@ -80,6 +104,14 @@ JWT_REFRESH_EXPIRY="7d"
 # Multiple origins separated by commas
 CORS_ORIGIN="https://yourdomain.com,https://app.yourdomain.com"
 
+# Cookie domain for cross-origin deployments
+# REQUIRED when client and API are on different subdomains:
+#   Client: https://app.example.com  |  API: https://api.example.com
+#   → Set COOKIE_DOMAIN=".example.com" (leading dot = all subdomains)
+# This enables cookies to be shared between client and API subdomains.
+# Without it, login will silently fail (server returns 200 but browser drops cookies).
+COOKIE_DOMAIN=".yourdomain.com"
+
 # ===================================================================
 # LOGGING
 # ===================================================================
@@ -102,6 +134,7 @@ SENTRY_DSN="https://YOUR_PUBLIC_KEY@o0.ingest.sentry.io/YOUR_PROJECT_ID"
 # [ ] DATABASE_URL uses secure credentials and SSL
 # [ ] JWT_SECRET is a strong random string (48+ chars)
 # [ ] CORS_ORIGIN is set to your exact frontend URL(s)
+# [ ] COOKIE_DOMAIN is set if client and API are on different subdomains
 # [ ] REDIS_URL uses authentication if Redis is exposed
 # [ ] LOG_LEVEL is set to info or warn
 # [ ] SENTRY_DSN is configured for error tracking
@@ -109,3 +142,5 @@ SENTRY_DSN="https://YOUR_PUBLIC_KEY@o0.ingest.sentry.io/YOUR_PROJECT_ID"
 # [ ] All secrets are stored in environment variables, not in code
 # [ ] SSL/TLS certificates are configured
 # [ ] Firewall rules restrict access to database and Redis
+# [ ] In Coolify: NO secrets have "Available at Buildtime" checked
+# [ ] In Coolify: NODE_ENV does NOT have "Available at Buildtime" checked

package/template/server/Dockerfile

@@ -28,6 +28,11 @@ RUN if [ -f pnpm-lock.yaml ]; then \
 # ===================================================================
 FROM node:20-alpine AS builder
 
+# Override NODE_ENV to ensure devDependencies are installed.
+# Coolify may inject NODE_ENV=production as a build arg, which causes npm ci
+# to skip devDependencies (typescript, @types/node, etc.) and break the build.
+ENV NODE_ENV=development
+
 WORKDIR /app
 
 # Copy package files and install ALL dependencies (including dev)
@@ -77,6 +82,9 @@ COPY --from=builder --chown=nodejs:nodejs /app/package.json ./package.json
 # Copy Prisma files (needed for migrations)
 COPY --from=builder --chown=nodejs:nodejs /app/prisma ./prisma
 
+# Create uploads directory with correct ownership (must be before USER nodejs)
+RUN mkdir -p /app/uploads && chown nodejs:nodejs /app/uploads
+
 # Switch to non-root user
 USER nodejs
 

package/template/server/package.json

@@ -6,7 +6,7 @@
   "main": "dist/server.js",
   "scripts": {
     "dev": "tsx watch src/server.ts",
-    "build": "tsc && tsc-alias",
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
     "start": "node dist/server.js",
     "test": "vitest run",
     "test:watch": "vitest",

package/template/server/src/config/env.ts

@@ -39,6 +39,12 @@ const envSchema = z.object({
   // Separate secret for cookie signing (defaults to JWT_SECRET if not set)
   COOKIE_SECRET: z.string().min(32, 'COOKIE_SECRET must be at least 32 characters').optional(),
 
+  // Cookie domain for cross-origin deployments (client ≠ server hostname)
+  // Required when client and API are on different subdomains (e.g., app.example.com + api.example.com)
+  // Set to the shared parent domain with a leading dot: ".example.com"
+  // Leave empty for same-origin deployments or local development
+  COOKIE_DOMAIN: z.string().optional(),
+
   // --- CORS ---
   // In development: CORS_ORIGIN is optional (allows all origins)
   // In production: REQUIRED for security

package/template/server/src/libs/cookies.ts

@@ -4,6 +4,14 @@ import { parseDurationMs } from '@libs/auth.js';
 
 const isProduction = env.NODE_ENV === 'production';
 
+// Cross-origin deployment: client and API on different subdomains require sameSite 'none'.
+// Same-origin deployment (or local dev): 'strict' is the safest default.
+const isCrossOrigin = Boolean(env.COOKIE_DOMAIN);
+const sameSitePolicy = isProduction && isCrossOrigin ? 'none' as const : 'strict' as const;
+
+// When set, cookies are shared across subdomains (e.g., ".example.com" covers app.example.com + api.example.com)
+const cookieDomain = env.COOKIE_DOMAIN || undefined;
+
 const ACCESS_TOKEN_MAX_AGE_MS = parseDurationMs(env.JWT_ACCESS_EXPIRY, 15 * 60 * 1000);
 const REFRESH_TOKEN_MAX_AGE_MS = parseDurationMs(env.JWT_REFRESH_EXPIRY, 7 * 24 * 60 * 60 * 1000);
 
@@ -15,7 +23,8 @@ export function setAuthCookies(
   reply.setCookie('access_token', accessToken, {
     httpOnly: true,
     secure: isProduction,
-    sameSite: 'strict',
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
     path: '/',
     maxAge: Math.floor(ACCESS_TOKEN_MAX_AGE_MS / 1000), // setCookie expects seconds
   });
@@ -23,24 +32,46 @@ export function setAuthCookies(
   reply.setCookie('refresh_token', refreshToken, {
     httpOnly: true,
     secure: isProduction,
-    sameSite: 'strict',
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
     path: '/api/v1/auth',
     maxAge: Math.floor(REFRESH_TOKEN_MAX_AGE_MS / 1000),
   });
+
+  // Non-sensitive session indicator visible to Next.js middleware and client JS.
+  // Lets middleware distinguish "never logged in" from "access token expired but session alive."
+  reply.setCookie('auth_session', '1', {
+    httpOnly: false,
+    secure: isProduction,
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
+    path: '/',
+    maxAge: Math.floor(REFRESH_TOKEN_MAX_AGE_MS / 1000),
+  });
 }
 
 export function clearAuthCookies(reply: FastifyReply): void {
   reply.clearCookie('access_token', {
     httpOnly: true,
     secure: isProduction,
-    sameSite: 'strict',
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
     path: '/',
   });
 
   reply.clearCookie('refresh_token', {
     httpOnly: true,
     secure: isProduction,
-    sameSite: 'strict',
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
     path: '/api/v1/auth',
   });
+
+  reply.clearCookie('auth_session', {
+    httpOnly: false,
+    secure: isProduction,
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
+    path: '/',
+  });
 }

package/template/server/src/server.ts

@@ -13,7 +13,7 @@ async function start(): Promise<void> {
     if (isShuttingDown) return; // Prevent multiple shutdown attempts
     isShuttingDown = true;
 
-    logger.info(`[SERVER] Received ${signal} — shutting down gracefully`);
+    logger.info(`[SERVER] Received ${signal} - shutting down gracefully`);
     try {
       if (app) {
         await app.close();

package/template/server/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["node_modules", "dist", "src/test", "src/**/*.test.ts", "src/**/*.spec.ts"]
+}

package/template/server/tsconfig.json

@@ -14,6 +14,7 @@
     "outDir": "dist",
     "rootDir": "src",
     "baseUrl": ".",
+    "types": ["node"],
     "paths": {
       "@/*": ["./src/*"],
       "@modules/*": ["./src/modules/*"],

package/template/client/src/app/(auth)/layout.tsx

@@ -1,18 +0,0 @@
-import type React from 'react';
-
-import { APP_NAME } from '@/lib/constants/app.constants';
-
-export default function AuthLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}): React.ReactElement {
-  return (
-    <div className="flex min-h-dvh flex-col items-center justify-center px-4 py-12">
-      <span className="mb-8 text-xl font-semibold tracking-tight text-foreground">
-        {APP_NAME}
-      </span>
-      {children}
-    </div>
-  );
-}

package/template/client/src/app/(auth)/login/page.tsx

@@ -1,13 +0,0 @@
-import type React from 'react';
-
-import { LoginForm } from '@/features/auth/components/LoginForm';
-
-import type { Metadata } from 'next';
-
-export const metadata: Metadata = {
-  title: 'Sign in',
-};
-
-export default function LoginPage(): React.ReactElement {
-  return <LoginForm />;
-}

package/template/client/src/app/(auth)/register/page.tsx

@@ -1,13 +0,0 @@
-import type React from 'react';
-
-import { RegisterForm } from '@/features/auth/components/RegisterForm';
-
-import type { Metadata } from 'next';
-
-export const metadata: Metadata = {
-  title: 'Create account',
-};
-
-export default function RegisterPage(): React.ReactElement {
-  return <RegisterForm />;
-}

package/template/client/src/app/(main)/dashboard/page.tsx

@@ -1,22 +0,0 @@
-import type React from 'react';
-
-import type { Metadata } from 'next';
-
-export const metadata: Metadata = {
-  title: 'Dashboard',
-};
-
-export default function DashboardPage(): React.ReactElement {
-  return (
-    <div className="container mx-auto px-4 py-12 md:px-6 lg:px-8">
-      <div className="space-y-6">
-        <div>
-          <h1 className="text-3xl font-bold tracking-tight">Dashboard</h1>
-          <p className="mt-2 text-muted-foreground">
-            Welcome to your dashboard. This is where you&apos;ll manage everything.
-          </p>
-        </div>
-      </div>
-    </div>
-  );
-}

package/template/client/src/app/(main)/layout.tsx

@@ -1,11 +0,0 @@
-import type React from 'react';
-
-import { MainLayout } from '@/components/layout/MainLayout';
-
-export default function MainGroupLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}): React.ReactElement {
-  return <MainLayout>{children}</MainLayout>;
-}