Update docker configuration files

app/frontend/Dockerfile

@@ -1,44 +1,108 @@
-# Frontend image for Next.js (dev server + standalone production runner)
+#
+# FRONTEND DOCKERFILE
+#
+# This Dockerfile builds the container for the Next.js frontend application.
+# It uses a multi-stage build process to create lean, optimized images for
+# production while providing a flexible environment for development.
+#
+# Stages:
+# - `base`:    Installs Node.js and sets up a non-root user.
+# - `deps`:    Installs npm dependencies.
+# - `builder`: Builds the Next.js application for production.
+# - `runner`:  A minimal production-ready image that serves the built app.
+# - `dev`:     A development-ready image with hot-reloading enabled.
+#
+# For more details, see: ./docs/architecture.md
+#
+
+# ------------------------------------------------------------------------------
+#   1. Base Stage
+#      - Installs Node.js and sets up a non-root user for security.
+# ------------------------------------------------------------------------------
+FROM node:20-slim AS base
+
+# Set environment variables for non-interactive installation.
+ENV NPM_CONFIG_LOGLEVEL=warn
+
+# Create a non-root user and group for running the application.
+# This is a critical security measure to avoid running as root.
+RUN addgroup --system --gid 1001 nextjs
+RUN adduser --system --uid 1001 nextjs
+
+# ------------------------------------------------------------------------------
+#   2. Dependencies Stage
+#      - Installs npm dependencies. This layer is cached to speed up builds
+#        when only source code changes.
+# ------------------------------------------------------------------------------
+FROM base AS deps
 
-# Dependency + build stage for production
-FROM node:22-bookworm-slim AS builder
 WORKDIR /app
-ENV NODE_ENV=production \
-    NEXT_TELEMETRY_DISABLED=1
 
-# Install dependencies first for better Docker layer caching
-COPY package*.json ./
-RUN npm ci --ignore-scripts
+# Copy the package manager files.
+COPY package.json package-lock.json* ./
 
-# Copy full source and build standalone output
+# Install dependencies.
+RUN npm ci
+
+# ------------------------------------------------------------------------------
+#   3. Builder Stage
+#      - Builds the Next.js application for production.
+# ------------------------------------------------------------------------------
+FROM base AS builder
+
+WORKDIR /app
+
+# Copy dependencies from the `deps` stage.
+COPY --from=deps /app/node_modules ./node_modules
+# Copy the application source code.
 COPY . .
+
+# Build the Next.js application. This creates an optimized production build
+# in the .next/ directory.
 RUN npm run build
 
-# Dev image keeps the toolchain for next dev
-FROM node:22-bookworm-slim AS dev
+# ------------------------------------------------------------------------------
+#   4. Runner Stage (Production)
+#      - Creates a minimal, secure image for serving the production application.
+# ------------------------------------------------------------------------------
+FROM base AS runner
+
 WORKDIR /app
-ENV NODE_ENV=development \
-    NEXT_TELEMETRY_DISABLED=1
-COPY package*.json ./
-RUN npm install
-COPY . .
-CMD ["npm", "run", "dev"]
 
-# Production runtime: minimal Node image serving the standalone build
-FROM node:22-slim AS runner
-WORKDIR /app
-ENV NODE_ENV=production \
-    NEXT_TELEMETRY_DISABLED=1 \
-    PORT=3000
+# Set the environment to "production". This tells Next.js to use the
+# optimized build and enables other production-specific behaviors.
+ENV NODE_ENV=production
 
-# Copy only the files required to serve the built app
-COPY --from=builder /app/.next/standalone ./
-COPY --from=builder /app/public ./public
-COPY --from=builder /app/.next/static ./.next/static
+# Switch to the non-root user.
+USER nextjs
 
-# Drop privileges to the bundled node user for safety
-USER node
+# Copy the built application from the `builder` stage.
+# We copy only the necessary files to keep the image small.
+COPY --from=builder --chown=nextjs:nextjs /app/public ./public
+COPY --from=builder --chown=nextjs:nextjs /app/.next ./.next
+COPY --from=builder --chown=nextjs:nextjs /app/node_modules ./node_modules
+COPY --from=builder --chown=nextjs:nextjs /app/package.json ./package.json
+
+# Expose the port the Next.js server will run on.
 EXPOSE 3000
 
-# Next.js standalone exposes server.js at the root of the standalone output
-CMD ["node", "server.js"]
+# The command to start the Next.js server in production mode.
+CMD ["npm", "start"]
+
+# ------------------------------------------------------------------------------
+#   5. Dev Stage (Development)
+#      - Creates an image for local development with hot-reloading.
+# ------------------------------------------------------------------------------
+FROM base AS dev
+
+WORKDIR /app
+
+# Copy dependencies from the `deps` stage.
+COPY --from=deps /app/node_modules ./node_modules
+
+# Expose the development port.
+EXPOSE 3000
+
+# The command to start the Next.js development server.
+# This will be overridden by the docker-compose file for bind mounting.
+CMD ["npm", "run", "dev"]