Update docker configuration files

app/backend/Dockerfile

@@ -1,63 +1,99 @@
-# Backend image for FastAPI + LiveKit Agent runtime
-# Supports dev (uvicorn reload) and production (gunicorn) via APP_ENV.
+#
+# BACKEND DOCKERFILE
+#
+# This Dockerfile builds the container for the FastAPI backend application.
+# It uses a multi-stage build to create optimized images for both development
+# and production environments.
+#
+# Stages:
+# - `base`: Installs Python and poetry, the dependency manager.
+# - `builder`: Installs application dependencies into a virtual environment.
+# - `development`: A debug-friendly image with the full project and an
+#                  auto-reloading server.
+# - `production`: A minimal, optimized image for production deployment.
+#
+# For more details, see: ./docs/architecture.md
+#
 
-# Builder: install deps with uv into an isolated venv
-FROM python:3.12-slim AS builder
+# ------------------------------------------------------------------------------
+#   1. Base Stage
+#      - Installs Python and Poetry.
+#      - Sets up a non-root user for security.
+# ------------------------------------------------------------------------------
+FROM python:3.11-slim as base
 
-ENV PYTHONDONTWRITEBYTECODE=1 \
-    PYTHONUNBUFFERED=1 \
-    UV_PROJECT_ENV=/opt/venv
+# Set environment variables to prevent Python from writing .pyc files and to
+# ensure output is sent straight to the terminal without buffering.
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
 
-# System packages needed for common Python builds + uv installer
-RUN apt-get update && \
-    apt-get install -y --no-install-recommends build-essential curl && \
-    rm -rf /var/lib/apt/lists/*
+# Install Poetry, a modern dependency management tool for Python.
+# We use a specific version to ensure reproducible builds.
+RUN pip install "poetry==1.8.2"
 
-# Install uv (fast Python package manager) as the dependency tool
-RUN curl -LsSf https://astral.sh/uv/install.sh | sh
-ENV PATH="/root/.local/bin:${PATH}"
+# Create a non-root user and group to run the application.
+# Running as a non-root user is a security best practice.
+RUN addgroup --system app && adduser --system --group app
 
-# Create virtualenv and prepare workspace
-RUN python -m venv ${UV_PROJECT_ENV}
-ENV PATH="${UV_PROJECT_ENV}/bin:${PATH}"
-WORKDIR /app
-
-# Copy the full source; dependency install is guarded to avoid failures while the app is scaffolded
-COPY . /app
-RUN if [ -f uv.lock ] && [ -f pyproject.toml ]; then \
-        uv sync --frozen --no-dev; \
-    elif ls requirements*.txt >/dev/null 2>&1; then \
-        for req in requirements*.txt; do \
-            uv pip install --no-cache -r "$req"; \
-        done; \
-    elif [ -f pyproject.toml ]; then \
-        uv pip install --no-cache .; \
-    else \
-        echo "No dependency manifest found; skipping install"; \
-    fi && \
-    if [ -f pyproject.toml ]; then \
-        uv pip install --no-cache -e .; \
-    fi
-
-# Runtime: slim image with non-root user and prebuilt venv
-FROM python:3.12-slim AS runtime
-
-ENV PYTHONDONTWRITEBYTECODE=1 \
-    PYTHONUNBUFFERED=1 \
-    PATH="/opt/venv/bin:${PATH}"
-
-# Create unprivileged user
-RUN addgroup --system app && adduser --system --ingroup app app
+# ------------------------------------------------------------------------------
+#   2. Builder Stage
+#      - Copies project files and installs dependencies using Poetry.
+#      - Dependencies are installed into a virtual environment for isolation.
+# ------------------------------------------------------------------------------
+FROM base as builder
 
 WORKDIR /app
 
-# Copy runtime artifacts from builder
-COPY --from=builder /opt/venv /opt/venv
-COPY --from=builder /app /app
-RUN chown -R app:app /app /opt/venv
+# Copy the dependency definition files.
+COPY poetry.lock pyproject.toml ./
 
+# Install dependencies into a virtual environment.
+# `--no-root` tells Poetry not to install the project package itself.
+# `--only main` installs only production dependencies.
+RUN poetry install --no-root --only main
+
+# ------------------------------------------------------------------------------
+#   3. Production Stage
+#      - Creates a minimal image for production.
+#      - Copies the virtual environment from the `builder` stage.
+#      - Copies the application code.
+# ------------------------------------------------------------------------------
+FROM base as production
+
+WORKDIR /app
+
+# Copy the virtual environment with production dependencies from the builder.
+COPY --from=builder /app/.venv /app/.venv
+# Copy the application source code.
+COPY . .
+
+# Activate the virtual environment.
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Switch to the non-root user.
 USER app
+
+# The default command is specified in the docker-compose.yml file, allowing
+# it to be easily overridden (e.g., for running Gunicorn).
 EXPOSE 8000
 
-# Default command switches between uvicorn (dev) and gunicorn (prod) based on APP_ENV
-CMD ["sh", "-c", "if [ \"$APP_ENV\" = \"production\" ]; then exec gunicorn app.main:app -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000 --workers 4 --timeout 120; else exec uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload; fi"]
+# ------------------------------------------------------------------------------
+#   4. Development Stage
+#      - Sets up the environment for local development.
+#      - Installs all dependencies, including development tools.
+# ------------------------------------------------------------------------------
+FROM base as development
+
+WORKDIR /app
+
+# Copy dependency definition files.
+COPY poetry.lock pyproject.toml ./
+
+# Install all dependencies, including development dependencies like pytest.
+RUN poetry install --no-root
+
+# Activate the virtual environment.
+ENV PATH="/app/.venv/bin:$PATH"
+
+# The command is specified in docker-compose.yml to run uvicorn with --reload.
+EXPOSE 8000