#
# 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
#

# ------------------------------------------------------------------------------
#   1. Base Stage
#      - Installs Python and Poetry.
#      - Sets up a non-root user for security.
# ------------------------------------------------------------------------------
FROM python:3.11-slim as base

# 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

# 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"

# 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

# ------------------------------------------------------------------------------
#   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 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

# ------------------------------------------------------------------------------
#   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