Sync: Merge pull request #107 from seanpedrick-case/dev

Added option to skip all summarisation. AWS Guardrails now only apply on initial topic extraction (when receiving input responses)

.dockerignore

@@ -0,0 +1,63 @@
+*.pdf
+*.url
+*.jpg
+*.png
+*.ipynb
+*.xls
+*.xlsx
+*.pyc
+*.json.bak.*
+examples/*
+output/*
+tools/__pycache__/*
+build/*
+dist/*
+evals/*
+logs/*
+usage/*
+docs/*
+guide/*
+feedback/*
+test_code/*
+test/tmp/*
+unsloth_compiled_cache/*
+.vscode/*
+llm_topic_modelling.egg-info/*
+input/
+output/
+logs/
+usage/
+feedback/
+config/
+tmp/
+index.qmd
+_quarto.yml
+!config/pi_agent.env.example
+!config/docker_app_config.env.example
+!config/app_config.env.example
+workspace/*
+user_guide/*
+_extensions/*
+cdk/config/*
+cdk/node_modules/*
+!cdk/config/app_config.env.example
+!cdk/config/lambda/
+cdk/config/lambda/*
+!cdk/config/lambda/lambda_function.py
+!cdk/config/headless_s3_seed/
+cdk/config/headless_s3_seed/*
+!cdk/config/headless_s3_seed/input/
+cdk/config/headless_s3_seed/input/*
+!cdk/config/headless_s3_seed/input/config/
+cdk/config/headless_s3_seed/input/config/*
+!cdk/config/headless_s3_seed/input/config/example_headless_env_file.env
+!cdk/config/headless_s3_seed/general-config/
+cdk/config/headless_s3_seed/general-config/*
+!cdk/config/headless_s3_seed/general-config/app_defaults.env
+cdk/cdk.out/*
+cdk/archive/*
+cdk/cdk.json
+cdk/cdk.context.json
+cdk/precheck.context.json
+cdk/package.json
+cdk/package-lock.json

.gitattributes

@@ -0,0 +1,2 @@
+*.xlsx filter=lfs diff=lfs merge=lfs -text
+*.csv filter=lfs diff=lfs merge=lfs -text

.github/workflows/ci.yml

@@ -0,0 +1,215 @@
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  #schedule:
+  # Run tests daily at 2 AM UTC
+  #  - cron: '0 2 * * *'
+
+permissions:
+  contents: read
+  actions: read
+  pull-requests: write
+  issues: write
+
+env:
+  PYTHON_VERSION: "3.11"
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        lfs: true
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install ruff black
+    
+    - name: Run Ruff linter
+      run: ruff check .
+    
+    - name: Run Black formatter check
+      run: black --check .
+
+  test-unit:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.11, 3.12, 3.13]
+    
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        lfs: true
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Cache pip dependencies
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt', '**/pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+    
+    - name: Install Python dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements_lightweight.txt
+        pip install pytest pytest-cov pytest-html pytest-xdist
+    
+    - name: Verify example data files
+      run: |
+        echo "Checking if example data directory exists:"
+        ls -la example_data/ || echo "example_data directory not found"
+        echo "Checking for specific CSV files:"
+        ls -la example_data/*.csv || echo "No CSV files found"
+        # Fail early if Git LFS pointers were not materialized
+        if head -n 1 example_data/combined_case_notes.csv | grep -q 'git-lfs.github.com'; then
+          echo "ERROR: example_data CSVs are still Git LFS pointers. Ensure checkout uses lfs: true."
+          exit 1
+        fi
+    
+    - name: Run CLI and GUI tests
+      run: |
+        cd test
+        python run_tests.py
+    
+    - name: Run tests with pytest
+      run: |
+        pytest test/test.py test/test_gui_only.py -v --tb=short --junitxml=test-results.xml
+    
+    - name: Run tests with coverage
+      run: |
+        pytest test/test.py test/test_gui_only.py --cov=. --cov-report=xml --cov-report=html --cov-report=term
+    
+    - name: Upload test results
+      uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: test-results-python-${{ matrix.python-version }}
+        path: |
+          test-results.xml
+          htmlcov/
+          coverage.xml
+
+  test-integration:
+    runs-on: ubuntu-latest
+    needs: [lint, test-unit]
+    
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        lfs: true
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements_lightweight.txt
+        pip install pytest pytest-cov
+    
+    - name: Verify example data files
+      run: |
+        echo "Checking if example data directory exists:"
+        ls -la example_data/
+        echo "Checking for specific CSV files:"
+        ls -la example_data/*.csv || echo "No CSV files found"
+        if head -n 1 example_data/combined_case_notes.csv | grep -q 'git-lfs.github.com'; then
+          echo "ERROR: example_data CSVs are still Git LFS pointers. Ensure checkout uses lfs: true."
+          exit 1
+        fi
+    
+    - name: Run integration tests (CLI and GUI)
+      run: |
+        cd test
+        python run_tests.py
+    
+    - name: Test CLI help
+      run: |
+        python cli_topics.py --help
+    
+    - name: Test CLI version
+      run: |
+        python -c "import sys; print(f'Python {sys.version}')"
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        lfs: true
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install bandit
+    
+    - name: Run bandit security check
+      run: |
+        bandit -r . -f json -o bandit-report.json || true
+    
+    - name: Upload security report
+      uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: security-report
+        path: bandit-report.json
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, test-unit]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        lfs: true
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+    
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+    
+    - name: Build package
+      run: |
+        python -m build
+    
+    - name: Check package
+      run: |
+        twine check dist/*
+    
+    - name: Upload build artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/
+

.github/workflows/simple-test.yml

@@ -0,0 +1,53 @@
+name: Simple Test Run
+
+on:
+  push:
+    branches: [ dev ]
+  pull_request:
+    branches: [ dev ]
+
+permissions:
+  contents: read
+  actions: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        lfs: true
+    
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.11"
+    
+    - name: Install Python dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements_lightweight.txt
+        pip install pytest pytest-cov
+    
+    - name: Verify example data files
+      run: |
+        echo "Checking if example data directory exists:"
+        ls -la example_data/ || echo "example_data directory not found"
+        echo "Checking for specific CSV files:"
+        ls -la example_data/*.csv || echo "No CSV files found"
+        # Fail early if Git LFS pointers were not materialized
+        if head -n 1 example_data/combined_case_notes.csv | grep -q 'git-lfs.github.com'; then
+          echo "ERROR: example_data CSVs are still Git LFS pointers. Ensure checkout uses lfs: true."
+          exit 1
+        fi
+    
+    - name: Run CLI and GUI tests
+      run: |
+        cd test
+        python run_tests.py
+    
+    - name: Run tests with pytest
+      run: |
+        pytest test/test.py test/test_gui_only.py -v --tb=short
+

.github/workflows/sync_to_hf.yml

@@ -0,0 +1,53 @@
+name: Sync to Hugging Face hub
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  sync-to-hub:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1      # Only get the latest state
+          lfs: true           # Download actual LFS files so they can be pushed
+
+      - name: Install Git LFS
+        run: git lfs install
+
+      - name: Recreate repo history (single-commit force push)
+        run: |
+          # 1. Capture the message BEFORE we delete the .git folder
+          COMMIT_MSG=$(git log -1 --pretty=%B)
+          echo "Syncing commit message: $COMMIT_MSG"
+
+          # 2. DELETE the .git folder. 
+          # This turns the repo into a standard folder of files.
+          rm -rf .git
+
+          # 3. Re-initialize a brand new git repo
+          git init -b main
+          git config --global user.name "$HF_USERNAME"
+          git config --global user.email "$HF_EMAIL"
+          
+          # 4. Re-install LFS (needs to be done after git init)
+          git lfs install
+          
+          # 5. Add the remote
+          git remote add hf https://$HF_USERNAME:$HF_TOKEN@huggingface.co/spaces/$HF_USERNAME/$HF_REPO_ID
+          
+          # 6. Add all files
+          # Since this is a fresh init, Git sees EVERY file as "New"
+          git add .
+          
+          # 7. Commit and Force Push
+          git commit -m "Sync: $COMMIT_MSG"
+          git push --force hf main
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          HF_USERNAME: ${{ secrets.HF_USERNAME }}
+          HF_EMAIL: ${{ secrets.HF_EMAIL }}
+          HF_REPO_ID: ${{ secrets.HF_REPO_ID }}

.gitignore

@@ -0,0 +1,62 @@
+*.pdf
+*.url
+*.jpg
+*.png
+*.ipynb
+*.xls
+*.pyc
+*.json.bak.*
+examples/*
+output/*
+tools/__pycache__/*
+build/*
+dist/*
+logs/*
+docs/*
+guide/*
+evals/*
+usage/*
+feedback/*
+test_code/*
+config/*
+tmp/*
+test/tmp/*
+unsloth_compiled_cache/*
+.vscode/*
+llm_topic_modelling.egg-info/*
+index.qmd
+_quarto.yml
+/.quarto/
+**/*.quarto_ipynb
+config/*
+!config/pi_agent.env.example
+!config/docker_app_config.env.example
+!config/app_config.env.example
+workspace/*
+user_guide/*
+_extensions/*
+cdk/config/*
+cdk/node_modules/*
+!cdk/config/app_config.env.example
+!cdk/config/lambda/
+cdk/config/lambda/*
+!cdk/config/lambda/lambda_function.py
+!cdk/config/headless_s3_seed/
+cdk/config/headless_s3_seed/*
+!cdk/config/headless_s3_seed/input/
+cdk/config/headless_s3_seed/input/*
+!cdk/config/headless_s3_seed/input/config/
+cdk/config/headless_s3_seed/input/config/*
+!cdk/config/headless_s3_seed/input/config/example_headless_env_file.env
+!cdk/config/headless_s3_seed/general-config/
+cdk/config/headless_s3_seed/general-config/*
+!cdk/config/headless_s3_seed/general-config/app_defaults.env
+cdk/cdk.out/*
+cdk/archive/*
+cdk/cdk.out/*
+cdk/cdk.json
+cdk/cdk.context.json
+cdk/precheck.context.json
+cdk/package.json
+cdk/package-lock.json
+

Dockerfile

@@ -0,0 +1,171 @@
+# Stage 1: Build dependencies and download models
+FROM public.ecr.aws/docker/library/python:3.13.16-slim-trixie AS builder
+
+# Install system dependencies.
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    gcc \
+    g++ \
+    cmake \
+    #libopenblas-dev \
+    pkg-config \
+    python3-dev \
+    libffi-dev \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /src
+
+COPY requirements_lightweight.txt .
+
+ARG INSTALL_TORCH=False
+ENV INSTALL_TORCH=${INSTALL_TORCH}
+
+# Local torch install requires CUDA 13.0
+RUN if [ "$INSTALL_TORCH" = "True" ]; then \
+    pip install --no-cache-dir --target=/install torch==2.14.1 --extra-index-url https://download.pytorch.org/whl/cu130; \
+    fi
+
+ARG INSTALL_LLAMA_CPP_PYTHON=False
+ENV INSTALL_LLAMA_CPP_PYTHON=${INSTALL_LLAMA_CPP_PYTHON}
+
+# Llama CPP Python install requires CUDA 13.0
+RUN if [ "$INSTALL_LLAMA_CPP_PYTHON" = "True" ]; then \
+    pip install --no-cache-dir --target=/install https://github.com/abetlen/llama-cpp-python/releases/download/v0.3.35-cu130/llama_cpp_python-0.3.36-py3-none-manylinux_2_35_x86_64.whl; \
+    fi
+
+RUN pip install --no-cache-dir --target=/install -r requirements_lightweight.txt
+
+RUN rm requirements_lightweight.txt
+
+# ===================================================================
+# Stage 2: A common 'base' for both Lambda and Gradio
+# ===================================================================
+FROM public.ecr.aws/docker/library/python:3.13.16-slim-trixie AS base
+
+# Set build-time and runtime environment variable for whether to run in Gradio mode or Lambda mode
+ARG APP_MODE=gradio
+ENV APP_MODE=${APP_MODE}
+
+# Install runtime system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libopenblas0 \
+    openssl \
+    libpcre2-8-0 \
+    && apt-get upgrade -y openssl libpcre2-8-0 \
+    && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+ENV APP_HOME=/home/user
+
+# Set env variables for Gradio & other apps
+# TLDEXTRACT_CACHE: Presidio email validation (read-only ECS root FS cannot use ~/.cache)
+ENV GRADIO_TEMP_DIR=/tmp/gradio_tmp/ \
+    MPLCONFIGDIR=/tmp/matplotlib_cache/ \
+    TLDEXTRACT_CACHE=/tmp/tldextract_cache/ \
+    GRADIO_OUTPUT_FOLDER=$APP_HOME/app/output/ \
+    GRADIO_INPUT_FOLDER=$APP_HOME/app/input/ \
+    FEEDBACK_LOGS_FOLDER=$APP_HOME/app/feedback/ \
+    ACCESS_LOGS_FOLDER=$APP_HOME/app/logs/ \
+    USAGE_LOGS_FOLDER=$APP_HOME/app/usage/ \
+    CONFIG_FOLDER=$APP_HOME/app/config/ \
+    GRADIO_SERVER_NAME=0.0.0.0 \
+    GRADIO_SERVER_PORT=7860 \
+    PATH=$APP_HOME/.local/bin:$PATH \
+    PYTHONPATH=$APP_HOME/app \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    GRADIO_ALLOW_FLAGGING=never \
+    GRADIO_NUM_PORTS=1 \
+    GRADIO_THEME=huggingface \
+    SYSTEM=spaces
+
+# Copy Python packages from the builder stage
+COPY --from=builder /install /usr/local/lib/python3.13/site-packages/
+COPY --from=builder /install/bin /usr/local/bin/
+
+# Small English model for optional Presidio/spaCy PII redaction (emails/phones/numbers)
+RUN python -m spacy download en_core_web_sm
+
+# Copy your application code and entrypoint
+COPY . ${APP_HOME}/app
+COPY entrypoint.sh ${APP_HOME}/app/entrypoint.sh
+# Fix line endings and set execute permissions
+RUN sed -i 's/\r$//' ${APP_HOME}/app/entrypoint.sh \
+    && chmod +x ${APP_HOME}/app/entrypoint.sh
+
+WORKDIR ${APP_HOME}/app
+
+# ===================================================================
+# FINAL Stage 3: The Lambda Image (runs as root for simplicity)
+# ===================================================================
+FROM base AS lambda
+# Set runtime ENV for Lambda mode
+ENV APP_MODE=lambda
+ENTRYPOINT ["/home/user/app/entrypoint.sh"]
+CMD ["lambda_entrypoint.lambda_handler"]
+
+# ===================================================================
+# FINAL Stage 4: The Gradio Image (runs as a secure, non-root user)
+# ===================================================================
+FROM base AS gradio
+# Set runtime ENV for Gradio mode
+ENV APP_MODE=gradio
+
+# Create non-root user
+RUN useradd -m -u 1000 user
+
+# Create the base application directory and set its ownership
+RUN mkdir -p ${APP_HOME}/app && chown user:user ${APP_HOME}/app
+
+# Create required sub-folders within the app directory and set their permissions
+RUN mkdir -p \
+    ${APP_HOME}/app/output \
+    ${APP_HOME}/app/input \
+    ${APP_HOME}/app/logs \
+    ${APP_HOME}/app/usage \
+    ${APP_HOME}/app/feedback \
+    ${APP_HOME}/app/config \
+    && chown user:user \
+    ${APP_HOME}/app/output \
+    ${APP_HOME}/app/input \
+    ${APP_HOME}/app/logs \
+    ${APP_HOME}/app/usage \
+    ${APP_HOME}/app/feedback \
+    ${APP_HOME}/app/config \
+    && chmod 755 \
+    ${APP_HOME}/app/output \
+    ${APP_HOME}/app/input \
+    ${APP_HOME}/app/logs \
+    ${APP_HOME}/app/usage \
+    ${APP_HOME}/app/feedback \
+    ${APP_HOME}/app/config
+
+# Now handle the /tmp directories
+RUN mkdir -p /tmp/gradio_tmp /tmp/matplotlib_cache /tmp/tldextract_cache /tmp /var/tmp \
+    && chown user:user /tmp /var/tmp /tmp/gradio_tmp /tmp/matplotlib_cache /tmp/tldextract_cache \
+    && chmod 1777 /tmp /var/tmp /tmp/gradio_tmp /tmp/matplotlib_cache /tmp/tldextract_cache
+
+# Fix apply user ownership to all files in the home directory
+RUN chown -R user:user /home/user
+
+# Set permissions for Python executable
+RUN chmod 755 /usr/local/bin/python
+
+# Declare volumes
+VOLUME ["/tmp/matplotlib_cache"]
+VOLUME ["/tmp/gradio_tmp"]
+VOLUME ["/home/user/app/output"]
+VOLUME ["/home/user/app/input"]
+VOLUME ["/home/user/app/logs"]
+VOLUME ["/home/user/app/usage"]
+VOLUME ["/home/user/app/feedback"]
+VOLUME ["/home/user/app/config"]
+VOLUME ["/tmp"]
+VOLUME ["/var/tmp"]
+
+USER user
+
+EXPOSE $GRADIO_SERVER_PORT
+
+ENTRYPOINT ["/home/user/app/entrypoint.sh"]
+CMD ["python", "app.py"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 London Borough of Lambeth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,189 @@
+---
+title: Large language model topic modelling
+emoji: 📚
+colorFrom: purple
+colorTo: yellow
+sdk: gradio
+sdk_version: 6.30.0
+app_file: app.py
+pinned: true
+license: mit
+short_description: Extract topics from open text data with LLMs
+---
+
+# Large language model topic modelling
+
+Extract topics and summarise outputs using Large Language Models (LLMs), either local or cloud based (AWS, Azure, Gemini). The app will query the LLM with batches of responses to produce summary tables, which are then compared iteratively to output a table with the general topics, subtopics, topic sentiment, and a topic summary. Instructions on use can be found in the README.md file. You can try out examples by clicking on one of the example datasets on the main app page, which will show you example outputs from a local model run. API keys for cloud services can be entered on the settings page.
+
+NOTE: Large language models are not 100% accurate and may produce biased or harmful outputs. All outputs from this app **absolutely need to be checked by a human** to check for harmful outputs, hallucinations, and accuracy.
+
+Basic use:
+1. On the front page, choose your model for inference. Gemma 3/GPT-OSS will use 'on-device' inference. Calls to Gemini or AWS will require an API key that can be input on the 'LLM and topic extraction' page.
+1. Upload a csv/xlsx/parquet file containing at least one open text column.
+2. Select the relevant open text column from the dropdown.
+3. If you have your own suggested (zero shot) topics, upload this (see examples folder for an example file)
+4. Write a one sentence description of the consultation/context of the open text.
+5. Click 'Extract topics, deduplicate, and summarise'. This will run through the whole analysis process from topic extraction, to topic deduplication, to topic-level and overall summaries.
+6. A summary xlsx file workbook will be created on the front page in the box 'Overall summary xlsx file'. This will combine all the results from the different processes into one workbook.
+
+### Optional: Amazon Bedrock Guardrails (AWS models)
+
+When `RUN_AWS_BEDROCK_MODELS=1`, you can attach an existing Bedrock guardrail to every `Converse` call by setting variables in `config/app_config.env` (see `tools/config.py`):
+
+- `ENABLE_BEDROCK_GUARDRAILS=True`
+- `BEDROCK_GUARDRAIL_IDENTIFIER` — guardrail ID or ARN from the AWS console / CloudFormation output
+- `BEDROCK_GUARDRAIL_VERSION` — published version number (not `DRAFT` in production)
+- `BEDROCK_GUARDRAIL_TRACE` — `disabled`, `enabled`, or `enabled_full`. Defaults to **`enabled`** when `ENABLE_BEDROCK_GUARDRAILS` is true (so the **Guardrails interventions** sheet can list policy categories). Use `disabled` only if you do not want trace data returned from Bedrock.
+
+The guardrail must be created in the **same AWS Region** as Bedrock model invocation (`AWS_REGION`). Content filters, denied topics, and PII actions are defined on that guardrail version in AWS; the app only passes ID and version. For topic modelling, avoid chatbot-style topic denies on citizen open text; prefer PII and harmful-content policies. Optional Presidio redaction (`ENABLE_INPUT_REDACTION`, `REDACTION_ENTITIES`) runs before prompts are built and can be kept aligned with the guardrail’s PII policy when you publish new guardrail versions.
+
+**IAM:** The runtime role needs `bedrock:InvokeModel` (or inference-profile access) plus `bedrock:ApplyGuardrail` on the guardrail ARN. The ECS task role’s `AmazonBedrockLimitedAccess` managed policy may not include `ApplyGuardrail`; add a scoped inline policy via `POLICY_FILE_LOCATIONS` in CDK if Converse returns access denied.
+
+Guardrails apply to **topic extraction and validation** Converse calls (raw response text). They are **not** attached for LLM topic deduplication, per-topic summarisation, or overall summary, which use aggregated topic tables rather than citizen verbatim text.
+
+When a batch is blocked (`stopReason: guardrail_intervened`), topic extraction **continues** with other batches: affected responses get no assignments (they may appear under **Missing responses** in the workbook). If any batch was guardrail-blocked, the combined xlsx includes a **Guardrails interventions** sheet listing batch number, row range, task type, and intervention categories when guardrail tracing is enabled (`BEDROCK_GUARDRAIL_TRACE`).
+
+# Installation guide
+
+Here is a step-by-step guide to clone the repository, create a virtual environment, and install dependencies from the relevant `requirements` file. This guide assumes you have **Git** and **Python 3.11** installed.
+
+-----
+
+### Step 1: Clone the Git Repository
+
+First, you need to copy the project files to your local machine. Navigate to the directory where you want to store the project using the `cd` (change directory) command. Then, use `git clone` with the repository's URL.
+
+1.  **Clone the repo:**
+
+    ```bash
+    git clone https://github.com/seanpedrick-case/llm_topic_modelling.git
+    ```
+
+2.  **Navigate into the new project folder:**
+
+    ```bash
+    cd llm_topic_modelling
+    ```
+-----
+
+### Step 2: Create and Activate a Virtual Environment
+
+A virtual environment is a self-contained directory that holds a specific Python interpreter and its own set of installed packages. This is crucial for isolating your project's dependencies.
+
+NOTE: Alternatively you could also create and activate a Conda environment instead of using venv below.
+
+1.  **Create the virtual environment:** We'll use Python's built-in `venv` module. It's common practice to name the environment folder `.venv`.
+
+    ```bash
+    python -m venv .venv
+    ```
+
+    *This command tells Python to create a new virtual environment in a folder named `.venv`.*
+
+2.  **Activate the environment:** You must "activate" the environment to start using it. The command differs based on your operating system and shell.
+
+      * **On macOS / Linux (bash/zsh):**
+
+        ```bash
+        source .venv/bin/activate
+        ```
+
+      * **On Windows (Command Prompt):**
+
+        ```bash
+        .\.venv\Scripts\activate
+        ```
+
+      * **On Windows (PowerShell):**
+
+        ```powershell
+        .\.venv\Scripts\Activate.ps1
+        ```
+
+    You'll know it's active because your command prompt will be prefixed with `(.venv)`.
+
+-----
+
+### Step 3: Install Dependencies
+
+Now that your virtual environment is active, you can install all the required packages. Here you have two options, install from the pyproject.toml file (recommended), or install from requirements files.
+
+1. **Install from pyproject.toml (recommended)**
+
+You can install the 'lightweight' version of the app to access all available cloud provider or local inference (e.g. llama server, vLLM server) APIs. This version will not allow you to run local models such as Gemma 12b or GPT-OSS-20b 'in-app', i.e. accessible from the GUI interface directly. However, you will have access to AWS, Gemma, or Azure/OpenAI models with appropriate API keys. Use the following command in your environment to install the relevant packages:
+
+```bash
+pip install .
+```
+
+#### Install torch (optional)
+
+If you want to run inference with transformers with full/quantised models, and the associated Unsloth package, you can run the following command for CPU inference. For GPU inference, please refer to the requirements_gpu.txt guide, and the 'Install from a requirements file' section below:
+
+```bash
+pip install .[torch]
+```
+
+#### Install llama-cpp-python (optional)
+
+You can run quantised GGUF models in-app using llama-cpp-python. However, installation of this package is not always straightforward, particularly considering that wheels are not available for the latest version apart from for linux. This package is not being updated regularly, and so support may be removed for this package in future. Long term I would advise instead looking into running GGUF models using llama-server and calling the API from this app using the lightweight version (details here: https://github.com/ggml-org/llama.cpp).
+
+If you do want to install llama-cpp-python in app, first try the following command:
+
+```bash
+pip install .[llamacpp]
+```
+
+This will install the CPU version of llama-cpp-python. If you want GPU support, first I would try using pip install with specific wheels for your system: See files in https://github.com/abetlen/llama-cpp-python/releases . If you are still struggling, see here for more details on installation here: https://llama-cpp-python.readthedocs.io/en/latest
+
+#### Install mcp version of gradio
+
+You can install an mcp-compatible version of gradio for this app with the following command:
+
+```bash
+pip install .[mcp]
+```
+
+2. **Install from a requirements file (not recommended)**
+
+The repo provides several requirements files that are relevant for different situations. To start, I advise installing using the **requirements_lightweight.txt** file, which installs the app with access to all cloud provider or local inference (e.g. llama server, vLLM server) APIs. This approach is much simpler as a first step, and avoids issues with potentially complicated llama-cpp-python installation and GPU management described below.
+
+If you want to run models locally 'in app', then you have two further requirements files to choose from:
+
+- **requirements_cpu.txt**: Used for Python 3.11 CPU-only environments. Uncomment the requirements under 'Windows' for Windows compatibility. Make sure you have [Openblas](https://github.com/OpenMathLib/OpenBLAS) installed!
+- **requirements_gpu.txt**: Used for Python 3.11 GPU-enabled environments. Uncomment the requirements under 'Windows' for Windows compatibility (CUDA 12.4).
+
+Example The below instructions will guide you in how to install the GPU-enabled version of the app for local inference.
+
+**Install packages for local model 'in-app' inference from the requirements file:**
+    ```bash
+    pip install -r requirements_gpu.txt
+    ```
+    *This command reads every package name listed in the file and installs it into your `.venv` environment.*
+
+NOTE: If default llama-cpp-python installation does not work when installing from the above, go into the requirements_gpu.txt file and uncomment the lines to install a wheel for llama-cpp-python 0.3.16 relevant to your system.
+
+### Step 4: Verify CUDA compatibility (if using a GPU environment)
+
+Install the relevant toolkit for CUDA from here: https://developer.nvidia.com/
+
+Restart your computer
+
+Ensure you have the latest drivers for your NVIDIA GPU. Check your current version and memory availability by running nvidia-smi
+
+In command line, CUDA compatibility can be checked by running nvcc --version
+
+
+### Step 5: Ensure you have compatible NVIDIA drivers
+
+Make sure you have the latest NVIDIA drivers installed on your system for your GPU (be careful in particular if using WSL that you have drivers compatible with this). Official drivers can be found here: https://www.nvidia.com/en-us/drivers
+
+Current drivers can be found by running nvidia-smi in command line
+
+### Step 6: Run the app
+
+Go to the app project directory. Run python app.py
+
+### Step 7: (optional) change default configuration
+
+A number of configuration options can be seen the tools/config.py file. You can either pass in these variables as environment variables, or you can create a file in config/app_config.env to read this into the app on initialisation.

cdk/app.py

@@ -0,0 +1,140 @@
+import os
+
+from aws_cdk import App, Environment
+from cdk_application_tags import apply_application_tags_to_app
+from cdk_appregistry import register_llm_topic_application
+from cdk_config import (
+    ALB_NAME,
+    APPLICATION_NAME,
+    APPLICATION_REPOSITORY_URL,
+    APPLICATION_TAG_KEY,
+    APPREGISTRY_APPLICATION_NAME,
+    APPREGISTRY_ATTRIBUTE_GROUP_NAME,
+    APPREGISTRY_DESCRIPTION,
+    APPREGISTRY_REPOSITORY_URL,
+    APPREGISTRY_STACK_NAME,
+    AWS_ACCOUNT_ID,
+    AWS_REGION,
+    CDK_CONTEXT_FILE,
+    CDK_PREFIX,
+    ENABLE_APPREGISTRY,
+    RUN_USEAST_STACK,
+    USE_CLOUDFRONT,
+)
+from cdk_functions import (
+    create_basic_config_env,
+    is_resource_delete_protection_enabled,
+    load_context_from_file,
+    log_aws_credential_context,
+    purge_cdk_lookup_context,
+)
+from cdk_stack import CdkStack, CdkStackCloudfront  # , CdkStackMain
+from check_resources import CONTEXT_FILE, check_and_set_context
+
+# Initialize the CDK app
+app = App()
+
+# Shared application tags on every CDK-managed resource (regional + CloudFront).
+# Preferred over AppRegistry/myApplications for monitoring (AppRegistry new-customer
+# cut-off 30 Jul 2026). Imported resources are not retagged.
+apply_application_tags_to_app(
+    app,
+    tag_key=APPLICATION_TAG_KEY,
+    application_name=APPLICATION_NAME,
+    repository_url=APPLICATION_REPOSITORY_URL,
+)
+
+log_aws_credential_context(
+    expected_account_id=AWS_ACCOUNT_ID,
+    expected_region=AWS_REGION,
+)
+
+# Drop stale CDK lookup cache entries (require bootstrap lookup role in target account).
+purge_cdk_lookup_context(CDK_CONTEXT_FILE)
+
+# --- Pre-check context (boto3) — written to precheck.context.json, NOT cdk.context.json ---
+print(f"Pre-check context file: {CONTEXT_FILE}")
+print(f"CDK lookup cache file: {CDK_CONTEXT_FILE}")
+if os.path.basename(CONTEXT_FILE.replace("\\", "/")) == os.path.basename(
+    CDK_CONTEXT_FILE.replace("\\", "/")
+):
+    raise RuntimeError(
+        f"CONTEXT_FILE and CDK_CONTEXT_FILE must differ (got '{CONTEXT_FILE}' for both). "
+        "Set CONTEXT_FILE=precheck.context.json in config/cdk_config.env."
+    )
+
+print("Running pre-check script to generate application context...")
+try:
+    check_and_set_context()
+    if not os.path.exists(CONTEXT_FILE):
+        raise RuntimeError(
+            f"check_and_set_context() finished, but {CONTEXT_FILE} was not created."
+        )
+    print(f"Context generated successfully at {CONTEXT_FILE}.")
+except Exception as e:
+    raise RuntimeError(f"Failed to generate context via check_and_set_context(): {e}")
+
+# Pre-check must not repopulate CDK lookup keys; purge again if paths were ever shared.
+purge_cdk_lookup_context(CDK_CONTEXT_FILE)
+
+if os.path.exists(CONTEXT_FILE):
+    load_context_from_file(app, CONTEXT_FILE)
+else:
+    raise RuntimeError(f"Could not find {CONTEXT_FILE}.")
+
+create_basic_config_env("config")
+
+aws_env_regional = Environment(account=AWS_ACCOUNT_ID, region=AWS_REGION)
+
+_stack_delete_protection = is_resource_delete_protection_enabled()
+
+regional_stack = CdkStack(
+    app, "SummarisationStack", env=aws_env_regional, cross_region_references=True
+)
+regional_stack.termination_protection = _stack_delete_protection
+
+if ENABLE_APPREGISTRY == "True":
+    # Legacy Service Catalog AppRegistry / myApplications (opt-in).
+    # New AppRegistry customers cannot sign up after 30 Jul 2026; prefer
+    # APPLICATION_* tags + Resource Groups. Keep this path for existing users.
+    # Use pre-check context only — not regional_stack.params (avoids AppRegistry
+    # -> SummarisationStack dependency cycle during synth).
+    _alb_dns_context = app.node.try_get_context(f"dns:{ALB_NAME}")
+    _alb_dns_name = (
+        _alb_dns_context.strip()
+        if isinstance(_alb_dns_context, str) and _alb_dns_context.strip()
+        else None
+    )
+    appregistry_stack = register_llm_topic_application(
+        app,
+        aws_account_id=AWS_ACCOUNT_ID,
+        aws_region=AWS_REGION,
+        application_name=APPREGISTRY_APPLICATION_NAME,
+        application_description=APPREGISTRY_DESCRIPTION,
+        appregistry_stack_name=APPREGISTRY_STACK_NAME,
+        attribute_group_name=APPREGISTRY_ATTRIBUTE_GROUP_NAME,
+        repository_url=APPREGISTRY_REPOSITORY_URL,
+        cdk_prefix=CDK_PREFIX,
+        use_cloudfront=USE_CLOUDFRONT,
+        alb_dns_name=_alb_dns_name,
+    )
+    appregistry_stack.termination_protection = _stack_delete_protection
+
+if USE_CLOUDFRONT == "True" and RUN_USEAST_STACK == "True":
+    aws_env_us_east_1 = Environment(account=AWS_ACCOUNT_ID, region="us-east-1")
+
+    cloudfront_stack = CdkStackCloudfront(
+        app,
+        "SummarisationStackCloudfront",
+        env=aws_env_us_east_1,
+        alb_arn=regional_stack.params["alb_arn_output"],
+        alb_sec_group_id=regional_stack.params["alb_security_group_id"],
+        alb_dns_name=regional_stack.params["alb_dns_name"],
+        cross_region_references=True,
+    )
+    cloudfront_stack.termination_protection = _stack_delete_protection
+
+# CDK CLI invokes this script and expects a cloud assembly in cdk.out.
+# Without app.synth(), Python defines constructs but never writes manifest.json
+# (ENOENT on deploy). See: https://github.com/aws/aws-cdk/issues/11023
+app.synth()

cdk/cdk.json.example

@@ -0,0 +1,7 @@
+{
+  "app": "python app.py",
+  "output": "cdk.out",
+  "context": {
+    "@aws-cdk/aws-ec2:restrictDefaultSecurityGroup": false
+  }
+}

cdk/cdk_application_tags.py

@@ -0,0 +1,95 @@
+"""Application tagging helpers and tag-based AWS Resource Groups."""
+
+from typing import Optional
+
+from aws_cdk import CfnOutput, CfnTag, Tags
+from aws_cdk import aws_resourcegroups as resourcegroups
+from constructs import Construct
+
+
+def apply_application_tags_to_app(
+    app: Construct,
+    *,
+    tag_key: str,
+    application_name: str,
+    repository_url: str,
+) -> None:
+    """
+    Tag all CDK-managed resources under ``app`` with a shared application identity.
+
+    Imported / looked-up resources (existing VPC, buckets, etc.) are not retagged
+    in AWS; only resources created by this CDK app receive the tags.
+    """
+    key = (tag_key or "Application").strip() or "Application"
+    name = (application_name or "").strip()
+    if not name:
+        raise ValueError("application_name is required for application tags.")
+    Tags.of(app).add(key, name)
+    Tags.of(app).add("ManagedBy", "cdk")
+    repo = (repository_url or "").strip()
+    if repo:
+        Tags.of(app).add("Repository", repo)
+
+
+def create_application_resource_group(
+    scope: Construct,
+    logical_id: str,
+    *,
+    group_name: str,
+    tag_key: str,
+    application_name: str,
+    description: Optional[str] = None,
+) -> resourcegroups.CfnGroup:
+    """
+    Create a tag-based Resource Group for inventory/monitoring without AppRegistry.
+
+    Members are all resources in the account/region that carry ``tag_key=application_name``.
+    """
+    key = (tag_key or "Application").strip() or "Application"
+    name = (application_name or "").strip()
+    group = (group_name or "").strip()
+    if not name:
+        raise ValueError("application_name is required for the Resource Group.")
+    if not group:
+        raise ValueError("group_name is required for the Resource Group.")
+
+    cfn_group = resourcegroups.CfnGroup(
+        scope,
+        logical_id,
+        name=group,
+        description=description
+        or (
+            f"Tag-based group for {name} "
+            f"filter {key} {name}. Prefer over AppRegistry after Jul 2026."
+        ),
+        resource_query=resourcegroups.CfnGroup.ResourceQueryProperty(
+            type="TAG_FILTERS_1_0",
+            query=resourcegroups.CfnGroup.QueryProperty(
+                resource_type_filters=["AWS::AllSupported"],
+                tag_filters=[
+                    resourcegroups.CfnGroup.TagFilterProperty(
+                        key=key,
+                        values=[name],
+                    )
+                ],
+            ),
+        ),
+        tags=[
+            CfnTag(key=key, value=name),
+            CfnTag(key="ManagedBy", value="cdk"),
+        ],
+    )
+
+    CfnOutput(
+        scope,
+        f"{logical_id}Name",
+        value=cfn_group.name,
+        description="AWS Resource Groups name for this application's tagged resources",
+    )
+    CfnOutput(
+        scope,
+        f"{logical_id}Arn",
+        value=cfn_group.attr_arn,
+        description="AWS Resource Groups ARN for this application's tagged resources",
+    )
+    return cfn_group

cdk/cdk_appregistry.py

@@ -0,0 +1,79 @@
+"""Legacy AWS Console myApplications (Service Catalog AppRegistry) integration.
+
+Opt-in only (ENABLE_APPREGISTRY=True). Preferred monitoring uses application tags
+and AWS Resource Groups (see cdk_application_tags.py). AppRegistry closes to new
+customers after 30 July 2026.
+"""
+
+from aws_cdk import App, Environment
+from aws_cdk.aws_servicecatalogappregistry_alpha import (
+    ApplicationAssociator,
+    TargetApplication,
+)
+
+
+def register_llm_topic_application(
+    app: App,
+    *,
+    aws_account_id: str,
+    aws_region: str,
+    application_name: str,
+    application_description: str,
+    appregistry_stack_name: str,
+    attribute_group_name: str,
+    repository_url: str,
+    cdk_prefix: str,
+    use_cloudfront: str,
+    alb_dns_name: str | None = None,
+) -> ApplicationAssociator:
+    """
+    Register regional CDK stacks with AWS Console myApplications.
+
+    Only stacks in ``aws_region`` are associated (phase 1). Cross-region stacks
+    such as SummarisationStackCloudfront (us-east-1) are not included.
+
+    ``alb_dns_name`` must be a plain string (e.g. from pre-check context). Do not
+    pass a CloudFormation token from SummarisationStack or synth will fail with a
+    dependency cycle against the associator stack.
+    """
+    associator = ApplicationAssociator(
+        app,
+        "SummarisationAppRegistry",
+        applications=[
+            TargetApplication.create_application_stack(
+                application_name=application_name,
+                application_description=application_description,
+                stack_name=appregistry_stack_name,
+                env=Environment(account=aws_account_id, region=aws_region),
+            )
+        ],
+    )
+
+    attributes = {
+        "repository": repository_url,
+        "cdkPrefix": cdk_prefix,
+        "awsRegion": aws_region,
+        "useCloudFront": use_cloudfront,
+        "cloudFrontInAppRegistry": "false",
+        "cloudFrontNote": (
+            "CloudFront/WAF (SummarisationStackCloudfront) is in us-east-1 and is "
+            "not linked to this myApplications entry in phase 1. View it in "
+            "CloudFormation (us-east-1) or the CloudFront console."
+        ),
+    }
+    if alb_dns_name:
+        attributes["albDnsName"] = alb_dns_name
+
+    associator.app_registry_application.add_attribute_group(
+        "SummarisationAttributeGroup",
+        attribute_group_name=attribute_group_name,
+        description="llm_topic_modeller deployment metadata",
+        attributes=attributes,
+    )
+
+    return associator
+
+
+def register_doc_summarisation_application(*args, **kwargs):
+    """Deprecated alias for register_llm_topic_application."""
+    return register_llm_topic_application(*args, **kwargs)

cdk/cdk_cloudfront_headers.py

@@ -0,0 +1,172 @@
+"""CloudFront response headers policy (CSP and related security headers)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from urllib.parse import urlparse
+
+from aws_cdk import Duration
+from aws_cdk import aws_cloudfront as cloudfront
+from constructs import Construct
+
+# Template exported from AWS; placeholders {APP-URL} and {COGNITO-APP-CLIENT-LOGIN-URL}.
+_CSP_TEMPLATE = (
+    "default-src 'self'; script-src 'self' cdnjs.cloudflare.com 'unsafe-inline'; "
+    "style-src 'self' https://fonts.googleapis.com 'unsafe-inline'; "
+    "img-src 'self' data:; font-src 'self' https://fonts.gstatic.com data:; "
+    "connect-src 'self' wss://{app_hostname} https://cdnjs.cloudflare.com; "
+    "form-action 'self'; frame-ancestors 'none'; object-src 'none'; base-uri 'self'; "
+    "manifest-src 'self' {cognito_login_url}; upgrade-insecure-requests;"
+)
+
+RESPONSE_HEADERS_POLICY_TEMPLATE_PATH = (
+    Path(__file__).resolve().parent / "config" / "response-headers-policy-config.json"
+)
+
+
+def normalize_https_origin(url: str) -> str:
+    """Return a canonical https origin (scheme + host, no path)."""
+    value = (url or "").strip()
+    if not value:
+        return ""
+    if "://" not in value:
+        value = f"https://{value}"
+    parsed = urlparse(value)
+    if not parsed.hostname:
+        return value.rstrip("/")
+    scheme = parsed.scheme or "https"
+    netloc = parsed.netloc or parsed.hostname
+    return f"{scheme}://{netloc}".rstrip("/")
+
+
+def hostname_from_origin(origin: str) -> str:
+    parsed = urlparse(origin if "://" in origin else f"https://{origin}")
+    return parsed.hostname or origin.strip()
+
+
+def cognito_hosted_ui_base_url(domain_prefix: str, region: str) -> str:
+    prefix = (domain_prefix or "").strip()
+    if not prefix:
+        return ""
+    return f"https://{prefix}.auth.{region}.amazoncognito.com"
+
+
+def build_content_security_policy(
+    *,
+    app_origin: str,
+    cognito_login_url: str,
+) -> str:
+    origin = normalize_https_origin(app_origin)
+    hostname = hostname_from_origin(origin)
+    cognito_url = normalize_https_origin(cognito_login_url)
+    return _CSP_TEMPLATE.format(app_hostname=hostname, cognito_login_url=cognito_url)
+
+
+def create_secure_cloudfront_response_headers_policy(
+    scope: Construct,
+    construct_id: str,
+    *,
+    policy_name: str,
+    app_origin: str,
+    cognito_login_url: str,
+    comment: str = "Secure response headers with CSP for llm_topic_modeller",
+) -> cloudfront.ResponseHeadersPolicy:
+    """Response headers policy aligned with config/response-headers-policy-config.json."""
+    cors_origin = normalize_https_origin(app_origin)
+    csp = build_content_security_policy(
+        app_origin=app_origin,
+        cognito_login_url=cognito_login_url,
+    )
+
+    return cloudfront.ResponseHeadersPolicy(
+        scope,
+        construct_id,
+        response_headers_policy_name=policy_name,
+        comment=comment,
+        cors_behavior=cloudfront.ResponseHeadersCorsBehavior(
+            access_control_allow_credentials=False,
+            access_control_allow_headers=["*"],
+            access_control_allow_methods=["ALL"],
+            access_control_allow_origins=[cors_origin],
+            access_control_max_age=Duration.seconds(600),
+            origin_override=True,
+        ),
+        security_headers_behavior=cloudfront.ResponseSecurityHeadersBehavior(
+            content_security_policy=cloudfront.ResponseHeadersContentSecurityPolicy(
+                content_security_policy=csp,
+                override=True,
+            ),
+            content_type_options=cloudfront.ResponseHeadersContentTypeOptions(
+                override=True
+            ),
+            frame_options=cloudfront.ResponseHeadersFrameOptions(
+                frame_option=cloudfront.HeadersFrameOption.SAMEORIGIN,
+                override=True,
+            ),
+            referrer_policy=cloudfront.ResponseHeadersReferrerPolicy(
+                referrer_policy=cloudfront.HeadersReferrerPolicy.STRICT_ORIGIN_WHEN_CROSS_ORIGIN,
+                override=True,
+            ),
+            strict_transport_security=cloudfront.ResponseHeadersStrictTransportSecurity(
+                access_control_max_age=Duration.seconds(31536000),
+                include_subdomains=True,
+                preload=False,
+                override=True,
+            ),
+            xss_protection=cloudfront.ResponseHeadersXSSProtection(
+                protection=True,
+                mode_block=True,
+                override=True,
+            ),
+        ),
+        custom_headers_behavior=cloudfront.ResponseCustomHeadersBehavior(
+            custom_headers=[
+                cloudfront.ResponseCustomHeader(
+                    header="Permissions-Policy",
+                    value=(
+                        "accelerometer=(), autoplay=(), camera=(), "
+                        "cross-origin-isolated=(), display-capture=(), encrypted-media=(), "
+                        "fullscreen=(), geolocation=(), gyroscope=(), keyboard-map=(), "
+                        "magnetometer=(), microphone=(), midi=(), payment=(), "
+                        "picture-in-picture=(), publickey-credentials-get=(), "
+                        "screen-wake-lock=(), sync-xhr=(), usb=(), web-share=(), "
+                        "xr-spatial-tracking=()"
+                    ),
+                    override=True,
+                )
+            ]
+        ),
+        remove_headers=["Server"],
+    )
+
+
+def resolve_cloudfront_csp_urls(
+    *,
+    cognito_redirection_url: str,
+    cloudfront_domain: str,
+    cognito_user_pool_domain_prefix: str,
+    aws_region: str,
+    cognito_user_pool_login_url: str = "",
+    ssl_certificate_domain: str = "",
+) -> tuple[str, str]:
+    """
+    Return (app_origin, cognito_login_url) for CSP/CORS substitution.
+
+    App origin prefers COGNITO_REDIRECTION_URL (canonical browser URL), then
+    https://SSL_CERTIFICATE_DOMAIN, then https://CLOUDFRONT_DOMAIN.
+    Cognito login URL uses COGNITO_USER_POOL_LOGIN_URL when set, else the
+    hosted UI base URL derived from COGNITO_USER_POOL_DOMAIN_PREFIX.
+    """
+    app_origin = normalize_https_origin(cognito_redirection_url)
+    if not app_origin or "placeholder" in app_origin.lower():
+        if ssl_certificate_domain.strip():
+            app_origin = normalize_https_origin(ssl_certificate_domain)
+        elif cloudfront_domain.strip():
+            app_origin = normalize_https_origin(cloudfront_domain)
+
+    login_url = (cognito_user_pool_login_url or "").strip()
+    if not login_url:
+        login_url = cognito_hosted_ui_base_url(
+            cognito_user_pool_domain_prefix, aws_region
+        )
+    return app_origin, normalize_https_origin(login_url)

cdk/cdk_config.py

@@ -0,0 +1,916 @@
+import os
+import tempfile
+from typing import List
+
+from dotenv import load_dotenv
+
+# Set or retrieve configuration variables for CDK llm_topic_modeller deployment
+
+
+def convert_string_to_boolean(value: str) -> bool:
+    """Convert string to boolean, handling various formats."""
+    if isinstance(value, bool):
+        return value
+    elif value in ["True", "1", "true", "TRUE"]:
+        return True
+    elif value in ["False", "0", "false", "FALSE"]:
+        return False
+    else:
+        raise ValueError(f"Invalid boolean value: {value}")
+
+
+def parse_comma_separated_list(value: str) -> List[str]:
+    """Parse a comma-separated env value into a list of non-empty strings."""
+    if not value or not str(value).strip():
+        return []
+    cleaned = str(value).strip().strip("[]")
+    return [
+        part.strip().strip('"').strip("'")
+        for part in cleaned.split(",")
+        if part.strip()
+    ]
+
+
+def get_or_create_env_var(var_name: str, default_value: str, print_val: bool = False):
+    """
+    Get an environmental variable, and set it to a default value if it doesn't exist
+    """
+    # Get the environment variable if it exists
+    value = os.environ.get(var_name)
+
+    # If it doesn't exist, set the environment variable to the default value
+    if value is None:
+        os.environ[var_name] = default_value
+        value = default_value
+
+    if print_val is True:
+        print(f"The value of {var_name} is {value}")
+
+    return value
+
+
+def ensure_folder_exists(output_folder: str):
+    """Checks if the specified folder exists, creates it if not."""
+
+    if not os.path.exists(output_folder):
+        # Create the folder if it doesn't exist
+        os.makedirs(output_folder, exist_ok=True)
+        print(f"Created the {output_folder} folder.")
+    else:
+        print(f"The {output_folder} folder already exists.")
+
+
+def add_folder_to_path(folder_path: str):
+    """
+    Check if a folder exists on your system. If so, get the absolute path and then add it to the system Path variable if it doesn't already exist. Function is only relevant for locally-created executable files based on this app (when using pyinstaller it creates a _internal folder that contains tesseract and poppler. These need to be added to the system path to enable the app to run)
+    """
+
+    if os.path.exists(folder_path) and os.path.isdir(folder_path):
+        print(folder_path, "folder exists.")
+
+        # Resolve relative path to absolute path
+        absolute_path = os.path.abspath(folder_path)
+
+        current_path = os.environ["PATH"]
+        if absolute_path not in current_path.split(os.pathsep):
+            full_path_extension = absolute_path + os.pathsep + current_path
+            os.environ["PATH"] = full_path_extension
+            # print(f"Updated PATH with: ", full_path_extension)
+        else:
+            print(f"Directory {folder_path} already exists in PATH.")
+    else:
+        print(f"Folder not found at {folder_path} - not added to PATH")
+
+
+###
+# LOAD CONFIG FROM ENV FILE
+###
+CONFIG_FOLDER = get_or_create_env_var("CONFIG_FOLDER", "config/")
+
+ensure_folder_exists(CONFIG_FOLDER)
+
+# If you have an aws_config env file in the config folder, you can load in app variables this way, e.g. 'config/cdk_config.env'
+CDK_CONFIG_PATH = get_or_create_env_var(
+    "CDK_CONFIG_PATH", "config/cdk_config.env"
+)  # e.g. config/cdk_config.env
+
+if CDK_CONFIG_PATH:
+    if os.path.exists(CDK_CONFIG_PATH):
+        print(f"Loading CDK variables from config file {CDK_CONFIG_PATH}")
+        # override=True: stale empty defaults from an earlier cdk_config import in the
+        # same shell (e.g. cdk_install wizard calling cdk_functions) must not win.
+        load_dotenv(CDK_CONFIG_PATH, override=True)
+    else:
+        print("CDK config file not found at location:", CDK_CONFIG_PATH)
+
+###
+# AWS OPTIONS
+###
+AWS_REGION = get_or_create_env_var("AWS_REGION", "")
+AWS_ACCOUNT_ID = get_or_create_env_var("AWS_ACCOUNT_ID", "")
+
+###
+# CDK OPTIONS
+###
+CDK_PREFIX = get_or_create_env_var("CDK_PREFIX", "")
+
+# When True (default): CloudFormation stack termination protection, AWS
+# deletion_protection on ALB/DynamoDB/Cognito, RemovalPolicy.RETAIN, and no S3
+# auto-delete on stack-created resources. Set False for dev sandboxes where
+# cdk destroy should remove resources cleanly.
+ENABLE_RESOURCE_DELETE_PROTECTION = get_or_create_env_var(
+    "ENABLE_RESOURCE_DELETE_PROTECTION", "True"
+)
+
+# Application tagging + Resource Groups (preferred monitoring model).
+# AppRegistry / myApplications closes to new customers after 30 Jul 2026;
+# use these tags and a tag-based Resource Group instead.
+APPLICATION_TAG_KEY = get_or_create_env_var("APPLICATION_TAG_KEY", "Application")
+APPLICATION_NAME = get_or_create_env_var(
+    "APPLICATION_NAME", f"{CDK_PREFIX}llm-topic-modeller"
+)
+APPLICATION_REPOSITORY_URL = get_or_create_env_var(
+    "APPLICATION_REPOSITORY_URL",
+    "https://github.com/seanpedrick-case/llm_topic_modelling.git",
+)
+ENABLE_APPLICATION_RESOURCE_GROUP = get_or_create_env_var(
+    "ENABLE_APPLICATION_RESOURCE_GROUP", "True"
+)
+APPLICATION_RESOURCE_GROUP_NAME = get_or_create_env_var(
+    "APPLICATION_RESOURCE_GROUP_NAME", f"{APPLICATION_NAME}-resources"
+)
+
+# Legacy AWS Console myApplications (Service Catalog AppRegistry) — opt-in only.
+# New AppRegistry customers cannot sign up after 30 Jul 2026; existing customers
+# may keep using it. Prefer APPLICATION_* tags + Resource Groups above.
+ENABLE_APPREGISTRY = get_or_create_env_var("ENABLE_APPREGISTRY", "False")
+APPREGISTRY_APPLICATION_NAME = get_or_create_env_var(
+    "APPREGISTRY_APPLICATION_NAME", APPLICATION_NAME
+)
+APPREGISTRY_DESCRIPTION = get_or_create_env_var(
+    "APPREGISTRY_DESCRIPTION",
+    "LLM topic modelling app (ALB, ECS Fargate, Cognito, S3)",
+)
+APPREGISTRY_STACK_NAME = get_or_create_env_var(
+    "APPREGISTRY_STACK_NAME", f"{CDK_PREFIX}AppRegistryStack"
+)
+APPREGISTRY_ATTRIBUTE_GROUP_NAME = get_or_create_env_var(
+    "APPREGISTRY_ATTRIBUTE_GROUP_NAME",
+    f"{APPREGISTRY_APPLICATION_NAME}-metadata",
+)
+APPREGISTRY_REPOSITORY_URL = get_or_create_env_var(
+    "APPREGISTRY_REPOSITORY_URL",
+    APPLICATION_REPOSITORY_URL,
+)
+
+_precheck_context_file = get_or_create_env_var("CONTEXT_FILE", "precheck.context.json")
+# Never write boto3 pre-check output into CDK's lookup cache file (causes stale
+# vpc-provider / load-balancer entries and wrong-account lookup validation errors).
+if os.path.basename(_precheck_context_file.replace("\\", "/")) == "cdk.context.json":
+    print(
+        "WARNING: CONTEXT_FILE must not be 'cdk.context.json' (that file is CDK's "
+        "lookup cache). Using 'precheck.context.json' instead. Update "
+        "config/cdk_config.env and remove CONTEXT_FILE=cdk.context.json if set."
+    )
+    _precheck_context_file = "precheck.context.json"
+CONTEXT_FILE = _precheck_context_file
+CDK_CONTEXT_FILE = get_or_create_env_var("CDK_CONTEXT_FILE", "cdk.context.json")
+CDK_FOLDER = get_or_create_env_var(
+    "CDK_FOLDER", ""
+)  # FULL_PATH_TO_CDK_FOLDER_HERE (with forward slash)
+
+# App runtime config (uploaded to S3 for legacy Fargate; inlined for ECS Express Mode)
+APP_CONFIG_ENV_BASENAME = "app_config.env"
+_app_config_rel = os.path.join(CONFIG_FOLDER, APP_CONFIG_ENV_BASENAME).replace(
+    "\\", "/"
+)
+APP_CONFIG_ENV_FILE = get_or_create_env_var(
+    "APP_CONFIG_ENV_FILE",
+    (
+        os.path.normpath(os.path.join(CDK_FOLDER, _app_config_rel))
+        if CDK_FOLDER
+        else os.path.normpath(_app_config_rel)
+    ),
+)
+RUN_USEAST_STACK = get_or_create_env_var("RUN_USEAST_STACK", "False")
+
+### VPC and connections
+VPC_NAME = get_or_create_env_var("VPC_NAME", "")
+NEW_VPC_DEFAULT_NAME = get_or_create_env_var("NEW_VPC_DEFAULT_NAME", f"{CDK_PREFIX}vpc")
+NEW_VPC_CIDR = get_or_create_env_var("NEW_VPC_CIDR", "")  # "10.0.0.0/24"
+
+
+# Internet Gateway for legacy VPC public subnets (attach + 0.0.0.0/0 routes via CDK when missing).
+EXISTING_IGW_ID = get_or_create_env_var("EXISTING_IGW_ID", "")
+SINGLE_NAT_GATEWAY_ID = get_or_create_env_var("SINGLE_NAT_GATEWAY_ID", "")
+
+### SUBNETS / ROUTE TABLES / NAT GATEWAY
+PUBLIC_SUBNETS_TO_USE = get_or_create_env_var(
+    "PUBLIC_SUBNETS_TO_USE", ""
+)  # e.g. ['PublicSubnet1', 'PublicSubnet2']
+PUBLIC_SUBNET_CIDR_BLOCKS = get_or_create_env_var(
+    "PUBLIC_SUBNET_CIDR_BLOCKS", ""
+)  # e.g. ["10.0.1.0/24", "10.0.2.0/24"]
+PUBLIC_SUBNET_AVAILABILITY_ZONES = get_or_create_env_var(
+    "PUBLIC_SUBNET_AVAILABILITY_ZONES", ""
+)  # e.g. ["eu-east-1b", "eu-east1b"]
+
+PRIVATE_SUBNETS_TO_USE = get_or_create_env_var(
+    "PRIVATE_SUBNETS_TO_USE", ""
+)  # e.g. ['PrivateSubnet1', 'PrivateSubnet2']
+PRIVATE_SUBNET_CIDR_BLOCKS = get_or_create_env_var(
+    "PRIVATE_SUBNET_CIDR_BLOCKS", ""
+)  # e.g. ["10.0.1.0/24", "10.0.2.0/24"]
+PRIVATE_SUBNET_AVAILABILITY_ZONES = get_or_create_env_var(
+    "PRIVATE_SUBNET_AVAILABILITY_ZONES", ""
+)  # e.g. ["eu-east-1b", "eu-east1b"]
+
+ROUTE_TABLE_BASE_NAME = get_or_create_env_var(
+    "ROUTE_TABLE_BASE_NAME", f"{CDK_PREFIX}PrivateRouteTable"
+)
+NAT_GATEWAY_EIP_NAME = get_or_create_env_var(
+    "NAT_GATEWAY_EIP_NAME", f"{CDK_PREFIX}NatGatewayEip"
+)
+NAT_GATEWAY_NAME = get_or_create_env_var("NAT_GATEWAY_NAME", f"{CDK_PREFIX}NatGateway")
+
+# IAM roles — managed policy *names* (AWS managed) and JSON policy *files* (inline statements)
+# Bedrock Guardrails (ENABLE_BEDROCK_GUARDRAILS in app config): task role may need
+# bedrock:ApplyGuardrail on the guardrail ARN in the same Region as Converse; add via
+# POLICY_FILE_LOCATIONS if AmazonBedrockLimitedAccess is insufficient.
+AWS_MANAGED_TASK_ROLES_LIST = get_or_create_env_var(
+    "AWS_MANAGED_TASK_ROLES_LIST",
+    '["AmazonCognitoReadOnly", "service-role/AmazonECSTaskExecutionRolePolicy", "AmazonDynamoDBFullAccess", "service-role/AWSAppSyncPushToCloudWatchLogs", "AmazonBedrockLimitedAccess"]',
+)
+ECS_EXECUTION_ROLE_MANAGED_POLICIES = get_or_create_env_var(
+    "ECS_EXECUTION_ROLE_MANAGED_POLICIES",
+    '["service-role/AmazonECSTaskExecutionRolePolicy"]',
+)
+# JSON IAM policy document paths (relative to CDK_FOLDER or absolute). Task role = app runtime.
+POLICY_FILE_LOCATIONS = get_or_create_env_var(
+    "POLICY_FILE_LOCATIONS",
+    "[]",
+)
+# Optional extra JSON policies for the ECS task *execution* role (image pull / logs / secrets).
+ECS_EXECUTION_ROLE_POLICY_FILES = get_or_create_env_var(
+    "ECS_EXECUTION_ROLE_POLICY_FILES",
+    "",
+)
+# Customer-managed policy ARNs (full ARN per entry), attached in addition to the lists above.
+POLICY_FILE_ARNS = get_or_create_env_var("POLICY_FILE_ARNS", "")
+ECS_EXECUTION_ROLE_POLICY_ARNS = get_or_create_env_var(
+    "ECS_EXECUTION_ROLE_POLICY_ARNS", ""
+)
+
+AWS_MANAGED_TASK_ROLES_LIST = parse_comma_separated_list(AWS_MANAGED_TASK_ROLES_LIST)
+ECS_EXECUTION_ROLE_MANAGED_POLICIES = parse_comma_separated_list(
+    ECS_EXECUTION_ROLE_MANAGED_POLICIES
+)
+POLICY_FILE_LOCATIONS = parse_comma_separated_list(POLICY_FILE_LOCATIONS)
+ECS_EXECUTION_ROLE_POLICY_FILES = parse_comma_separated_list(
+    ECS_EXECUTION_ROLE_POLICY_FILES
+)
+POLICY_FILE_ARNS = parse_comma_separated_list(POLICY_FILE_ARNS)
+ECS_EXECUTION_ROLE_POLICY_ARNS = parse_comma_separated_list(
+    ECS_EXECUTION_ROLE_POLICY_ARNS
+)
+
+# GITHUB REPO
+GITHUB_REPO_USERNAME = get_or_create_env_var("GITHUB_REPO_USERNAME", "seanpedrick-case")
+GITHUB_REPO_NAME = get_or_create_env_var("GITHUB_REPO_NAME", "llm_topic_modeller")
+GITHUB_REPO_BRANCH = get_or_create_env_var("GITHUB_REPO_BRANCH", "main")
+
+### CODEBUILD
+CODEBUILD_ROLE_NAME = get_or_create_env_var(
+    "CODEBUILD_ROLE_NAME", f"{CDK_PREFIX}CodeBuildRole"
+)
+CODEBUILD_PROJECT_NAME = get_or_create_env_var(
+    "CODEBUILD_PROJECT_NAME", f"{CDK_PREFIX}CodeBuildProject"
+)
+
+### ECR
+ECR_REPO_NAME = get_or_create_env_var(
+    "ECR_REPO_NAME", "llm-topic-modeller"
+)  # Beware - cannot have underscores and must be lower case
+ECR_CDK_REPO_NAME = get_or_create_env_var(
+    "ECR_CDK_REPO_NAME", f"{CDK_PREFIX}{ECR_REPO_NAME}".lower()
+)
+
+
+### S3
+def _resolve_s3_bucket_name(env_key: str, suffix: str) -> str:
+    """
+    Bucket name default is ``{CDK_PREFIX}{suffix}`` (lowercase).
+
+    If an earlier import cached a bare ``suffix`` in ``os.environ`` before
+    ``CDK_PREFIX`` was loaded from dotenv, upgrade it to the prefixed name.
+    """
+    prefix = (os.environ.get("CDK_PREFIX") or "").lower()
+    default = f"{prefix}{suffix}"
+    value = get_or_create_env_var(env_key, default)
+    if prefix and value == suffix:
+        os.environ[env_key] = default
+        return default
+    return value
+
+
+S3_LOG_CONFIG_BUCKET_NAME = _resolve_s3_bucket_name(
+    "S3_LOG_CONFIG_BUCKET_NAME", "s3-logs"
+)  # S3 bucket names need to be lower case
+S3_OUTPUT_BUCKET_NAME = _resolve_s3_bucket_name("S3_OUTPUT_BUCKET_NAME", "s3-output")
+
+### VPC endpoints for ECS tasks in private subnets (ECR image pull, logs, secrets)
+ENABLE_ECS_VPC_INTERFACE_ENDPOINTS = get_or_create_env_var(
+    "ENABLE_ECS_VPC_INTERFACE_ENDPOINTS", "True"
+)
+
+### KMS KEYS FOR S3 AND SECRETS MANAGER
+USE_CUSTOM_KMS_KEY = get_or_create_env_var("USE_CUSTOM_KMS_KEY", "1")
+CUSTOM_KMS_KEY_NAME = get_or_create_env_var(
+    "CUSTOM_KMS_KEY_NAME", f"alias/{CDK_PREFIX}kms-key".lower()
+)
+
+### ECS
+FARGATE_TASK_DEFINITION_NAME = get_or_create_env_var(
+    "FARGATE_TASK_DEFINITION_NAME", f"{CDK_PREFIX}FargateTaskDefinition"
+)
+TASK_DEFINITION_FILE_LOCATION = get_or_create_env_var(
+    "TASK_DEFINITION_FILE_LOCATION", CDK_FOLDER + CONFIG_FOLDER + "task_definition.json"
+)
+
+CLUSTER_NAME = get_or_create_env_var("CLUSTER_NAME", f"{CDK_PREFIX}Cluster")
+ECS_SERVICE_NAME = get_or_create_env_var("ECS_SERVICE_NAME", f"{CDK_PREFIX}ECSService")
+# Second Fargate service when ENABLE_PI_AGENT_ECS_SERVICE=True (legacy path only).
+ECS_PI_SERVICE_NAME = get_or_create_env_var(
+    "ECS_PI_SERVICE_NAME", f"{CDK_PREFIX}PiAgentService"
+)
+ECS_TASK_ROLE_NAME = get_or_create_env_var(
+    "ECS_TASK_ROLE_NAME", f"{CDK_PREFIX}TaskRole"
+)
+ECS_TASK_EXECUTION_ROLE_NAME = get_or_create_env_var(
+    "ECS_TASK_EXECUTION_ROLE_NAME", f"{CDK_PREFIX}ExecutionRole"
+)
+ECS_SECURITY_GROUP_NAME = get_or_create_env_var(
+    "ECS_SECURITY_GROUP_NAME", f"{CDK_PREFIX}SecurityGroupECS"
+)
+ECS_LOG_GROUP_NAME = get_or_create_env_var(
+    "ECS_LOG_GROUP_NAME", f"/ecs/{ECS_SERVICE_NAME}-logs".lower()
+)
+
+ECS_TASK_CPU_SIZE = get_or_create_env_var("ECS_TASK_CPU_SIZE", "1024")
+ECS_TASK_MEMORY_SIZE = get_or_create_env_var("ECS_TASK_MEMORY_SIZE", "4096")
+ECS_USE_FARGATE_SPOT = get_or_create_env_var("USE_FARGATE_SPOT", "False")
+ECS_READ_ONLY_FILE_SYSTEM = get_or_create_env_var("ECS_READ_ONLY_FILE_SYSTEM", "True")
+# ECS service AZ rebalancing (AWS defaults new services to ENABLED if omitted).
+ECS_AVAILABILITY_ZONE_REBALANCING = get_or_create_env_var(
+    "ECS_AVAILABILITY_ZONE_REBALANCING", "DISABLED"
+)
+if ECS_AVAILABILITY_ZONE_REBALANCING not in ("ENABLED", "DISABLED"):
+    raise ValueError(
+        "ECS_AVAILABILITY_ZONE_REBALANCING must be ENABLED or DISABLED "
+        f"(got {ECS_AVAILABILITY_ZONE_REBALANCING!r})."
+    )
+
+### Cognito
+COGNITO_USER_POOL_NAME = get_or_create_env_var(
+    "COGNITO_USER_POOL_NAME", f"{CDK_PREFIX}UserPool"
+)
+COGNITO_USER_POOL_CLIENT_NAME = get_or_create_env_var(
+    "COGNITO_USER_POOL_CLIENT_NAME", f"{CDK_PREFIX}UserPoolClient"
+)
+COGNITO_USER_POOL_CLIENT_SECRET_NAME = get_or_create_env_var(
+    "COGNITO_USER_POOL_CLIENT_SECRET_NAME", f"{CDK_PREFIX}ParamCognitoSecret"
+)
+COGNITO_USER_POOL_DOMAIN_PREFIX = get_or_create_env_var(
+    "COGNITO_USER_POOL_DOMAIN_PREFIX", "llm-topic-app-domain"
+)  # Should change this to something unique or you'll probably hit an error
+
+COGNITO_REFRESH_TOKEN_VALIDITY = int(
+    get_or_create_env_var("COGNITO_REFRESH_TOKEN_VALIDITY", "480")
+)  # Minutes
+COGNITO_ID_TOKEN_VALIDITY = int(
+    get_or_create_env_var("COGNITO_ID_TOKEN_VALIDITY", "60")
+)  # Minutes
+COGNITO_ACCESS_TOKEN_VALIDITY = int(
+    get_or_create_env_var("COGNITO_ACCESS_TOKEN_VALIDITY", "60")
+)  # Minutes
+
+# Application load balancer
+ALB_NAME = get_or_create_env_var(
+    "ALB_NAME", f"{CDK_PREFIX}Alb"[-32:]
+)  # Application load balancer name can be max 32 characters, so taking the last 32 characters of the suggested name
+ALB_NAME_SECURITY_GROUP_NAME = get_or_create_env_var(
+    "ALB_SECURITY_GROUP_NAME", f"{CDK_PREFIX}SecurityGroupALB"
+)
+ALB_TARGET_GROUP_NAME = get_or_create_env_var(
+    "ALB_TARGET_GROUP_NAME", f"{CDK_PREFIX}-tg"[-32:]
+)  # Max 32 characters
+EXISTING_LOAD_BALANCER_ARN = get_or_create_env_var("EXISTING_LOAD_BALANCER_ARN", "")
+EXISTING_LOAD_BALANCER_DNS = get_or_create_env_var(
+    "EXISTING_LOAD_BALANCER_DNS", "placeholder_load_balancer_dns.net"
+)
+
+## CLOUDFRONT
+USE_CLOUDFRONT = get_or_create_env_var("USE_CLOUDFRONT", "True")
+CLOUDFRONT_PREFIX_LIST_ID = get_or_create_env_var(
+    "CLOUDFRONT_PREFIX_LIST_ID", "pl-93a247fa"
+)
+CLOUDFRONT_GEO_RESTRICTION = get_or_create_env_var(
+    "CLOUDFRONT_GEO_RESTRICTION", ""
+)  # A country that Cloudfront restricts access to. See here: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/georestrictions.html
+CLOUDFRONT_DISTRIBUTION_NAME = get_or_create_env_var(
+    "CLOUDFRONT_DISTRIBUTION_NAME", f"{CDK_PREFIX}CfDist"
+)
+CLOUDFRONT_DOMAIN = get_or_create_env_var(
+    "CLOUDFRONT_DOMAIN", "cloudfront_placeholder.net"
+)
+# Attach CSP / security response headers to the CDK CloudFront distribution (us-east-1 stack).
+CLOUDFRONT_ENABLE_SECURE_RESPONSE_HEADERS = get_or_create_env_var(
+    "CLOUDFRONT_ENABLE_SECURE_RESPONSE_HEADERS", "True"
+)
+# Optional override for manifest-src (Cognito hosted UI). Default: https://{COGNITO_USER_POOL_DOMAIN_PREFIX}.auth.{AWS_REGION}.amazoncognito.com
+COGNITO_USER_POOL_LOGIN_URL = get_or_create_env_var("COGNITO_USER_POOL_LOGIN_URL", "")
+
+
+# Certificate for Application load balancer (optional, for HTTPS and logins through the ALB)
+ACM_SSL_CERTIFICATE_ARN = get_or_create_env_var("ACM_SSL_CERTIFICATE_ARN", "")
+SSL_CERTIFICATE_DOMAIN = get_or_create_env_var(
+    "SSL_CERTIFICATE_DOMAIN", ""
+)  # e.g. example.com or www.example.com
+
+# ECS Express Mode (opt-in HTTPS ingress without supplying ACM_SSL_CERTIFICATE_ARN).
+# Pilot/dev: Express PrimaryContainer does not support S3 environmentFiles or Fargate mount points.
+USE_ECS_EXPRESS_MODE = get_or_create_env_var("USE_ECS_EXPRESS_MODE", "False")
+ECS_EXPRESS_SERVICE_NAME = get_or_create_env_var(
+    "ECS_EXPRESS_SERVICE_NAME", ECS_SERVICE_NAME
+)
+ECS_EXPRESS_HEALTH_CHECK_PATH = get_or_create_env_var(
+    "ECS_EXPRESS_HEALTH_CHECK_PATH", "/"
+)
+ECS_EXPRESS_INFRASTRUCTURE_ROLE_NAME = get_or_create_env_var(
+    "ECS_EXPRESS_INFRASTRUCTURE_ROLE_NAME", f"{CDK_PREFIX}ExpressInfraRole"
+)
+# After first deploy, set to ExpressServiceEndpoint output (https://...) if not using CloudFront.
+# The installer updates Cognito callback URLs via API (no second CDK deploy).
+ECS_EXPRESS_COGNITO_REDIRECT_BASE = get_or_create_env_var(
+    "ECS_EXPRESS_COGNITO_REDIRECT_BASE", ""
+)
+# Express networkConfiguration.subnets drives both tasks and the managed ALB.
+# Public subnets (IGW route) → internet-facing ALB; private → internal ALB only.
+ECS_EXPRESS_USE_PUBLIC_SUBNETS = get_or_create_env_var(
+    "ECS_EXPRESS_USE_PUBLIC_SUBNETS", "True"
+)
+
+if USE_ECS_EXPRESS_MODE == "True" and ACM_SSL_CERTIFICATE_ARN:
+    raise ValueError(
+        "USE_ECS_EXPRESS_MODE=True cannot be used with ACM_SSL_CERTIFICATE_ARN set. "
+        "Clear ACM_SSL_CERTIFICATE_ARN or set USE_ECS_EXPRESS_MODE=False."
+    )
+
+# ECS Service Connect (legacy Fargate only): VPC service-to-service HTTP to Gradio/FastAPI.
+ENABLE_ECS_SERVICE_CONNECT = get_or_create_env_var(
+    "ENABLE_ECS_SERVICE_CONNECT", "False"
+)
+ECS_SERVICE_CONNECT_NAMESPACE = get_or_create_env_var(
+    "ECS_SERVICE_CONNECT_NAMESPACE",
+    (f"{CDK_PREFIX}local".lower().replace("_", "-").strip("-") or "llm-topic-local"),
+)
+ECS_SERVICE_CONNECT_DISCOVERY_NAME = get_or_create_env_var(
+    "ECS_SERVICE_CONNECT_DISCOVERY_NAME", "llm-topic"
+)
+# Optional friendly DNS label; defaults to discovery name when empty.
+ECS_SERVICE_CONNECT_DNS_NAME = get_or_create_env_var("ECS_SERVICE_CONNECT_DNS_NAME", "")
+# Client task security groups (at least one of IDs, names, or CDK prefixes required when SC on).
+ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_IDS = get_or_create_env_var(
+    "ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_IDS", ""
+)
+ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_IDS_LIST = parse_comma_separated_list(
+    ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_IDS
+)
+ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_NAMES = get_or_create_env_var(
+    "ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_NAMES", ""
+)
+ECS_SERVICE_CONNECT_CLIENT_CDK_PREFIXES = get_or_create_env_var(
+    "ECS_SERVICE_CONNECT_CLIENT_CDK_PREFIXES", ""
+)
+
+
+def normalize_https_redirect_url(url: str) -> str:
+    """Ensure Cognito/OAuth redirect bases use an explicit https:// scheme."""
+    raw = (url or "").strip()
+    if not raw:
+        return ""
+    if raw.startswith("https://"):
+        return raw.rstrip("/")
+    if raw.startswith("http://"):
+        return ("https://" + raw[len("http://") :]).rstrip("/")
+    return ("https://" + raw.lstrip("/")).rstrip("/")
+
+
+# This should be the CloudFront domain, the domain linked to your ACM certificate, or the DNS of your application load balancer in console afterwards
+if USE_CLOUDFRONT == "True":
+    COGNITO_REDIRECTION_URL = get_or_create_env_var(
+        "COGNITO_REDIRECTION_URL", "https://" + CLOUDFRONT_DOMAIN
+    )
+elif SSL_CERTIFICATE_DOMAIN:
+    COGNITO_REDIRECTION_URL = get_or_create_env_var(
+        "COGNITO_REDIRECTION_URL", "https://" + SSL_CERTIFICATE_DOMAIN
+    )
+elif USE_ECS_EXPRESS_MODE == "True":
+    _express_redirect_default = ECS_EXPRESS_COGNITO_REDIRECT_BASE or (
+        "https://" + EXISTING_LOAD_BALANCER_DNS
+    )
+    COGNITO_REDIRECTION_URL = get_or_create_env_var(
+        "COGNITO_REDIRECTION_URL", _express_redirect_default
+    )
+else:
+    COGNITO_REDIRECTION_URL = get_or_create_env_var(
+        "COGNITO_REDIRECTION_URL", "https://" + EXISTING_LOAD_BALANCER_DNS
+    )
+
+COGNITO_REDIRECTION_URL = normalize_https_redirect_url(COGNITO_REDIRECTION_URL)
+if ECS_EXPRESS_COGNITO_REDIRECT_BASE:
+    ECS_EXPRESS_COGNITO_REDIRECT_BASE = normalize_https_redirect_url(
+        ECS_EXPRESS_COGNITO_REDIRECT_BASE
+    )
+
+# Custom headers e.g. if routing traffic through Cloudfront
+CUSTOM_HEADER = get_or_create_env_var(
+    "CUSTOM_HEADER", ""
+)  # Retrieving or setting CUSTOM_HEADER
+CUSTOM_HEADER_VALUE = get_or_create_env_var(
+    "CUSTOM_HEADER_VALUE", ""
+)  # Retrieving or setting CUSTOM_HEADER_VALUE
+
+# Firewall on top of load balancer
+LOAD_BALANCER_WEB_ACL_NAME = get_or_create_env_var(
+    "LOAD_BALANCER_WEB_ACL_NAME", f"{CDK_PREFIX}alb-web-acl"
+)
+
+# Firewall on top of CloudFront
+WEB_ACL_NAME = get_or_create_env_var("WEB_ACL_NAME", f"{CDK_PREFIX}cloudfront-web-acl")
+
+###
+# File I/O options
+###
+
+OUTPUT_FOLDER = get_or_create_env_var("GRADIO_OUTPUT_FOLDER", "output/")  # 'output/'
+INPUT_FOLDER = get_or_create_env_var("GRADIO_INPUT_FOLDER", "input/")  # 'input/'
+
+# Allow for files to be saved in a temporary folder for increased security in some instances
+if OUTPUT_FOLDER == "TEMP" or INPUT_FOLDER == "TEMP":
+    # Create a temporary directory
+    with tempfile.TemporaryDirectory() as temp_dir:
+        print(f"Temporary directory created at: {temp_dir}")
+
+        if OUTPUT_FOLDER == "TEMP":
+            OUTPUT_FOLDER = temp_dir + "/"
+        if INPUT_FOLDER == "TEMP":
+            INPUT_FOLDER = temp_dir + "/"
+
+###
+# LOGGING OPTIONS
+###
+
+SAVE_LOGS_TO_CSV = get_or_create_env_var("SAVE_LOGS_TO_CSV", "True")
+
+### DYNAMODB logs. Whether to save to DynamoDB, and the headers of the table
+SAVE_LOGS_TO_DYNAMODB = get_or_create_env_var("SAVE_LOGS_TO_DYNAMODB", "True")
+ACCESS_LOG_DYNAMODB_TABLE_NAME = get_or_create_env_var(
+    "ACCESS_LOG_DYNAMODB_TABLE_NAME", f"{CDK_PREFIX}dynamodb-access-logs".lower()
+)
+FEEDBACK_LOG_DYNAMODB_TABLE_NAME = get_or_create_env_var(
+    "FEEDBACK_LOG_DYNAMODB_TABLE_NAME", f"{CDK_PREFIX}dynamodb-feedback-logs".lower()
+)
+USAGE_LOG_DYNAMODB_TABLE_NAME = get_or_create_env_var(
+    "USAGE_LOG_DYNAMODB_TABLE_NAME", f"{CDK_PREFIX}dynamodb-usage-logs".lower()
+)
+
+# Optional scheduled export of usage-log DynamoDB table to CSV in S3 (EventBridge -> Lambda).
+ENABLE_DYNAMODB_USAGE_LOG_EXPORT = get_or_create_env_var(
+    "ENABLE_DYNAMODB_USAGE_LOG_EXPORT", "False"
+)
+DYNAMODB_USAGE_LOG_EXPORT_LAMBDA_NAME = get_or_create_env_var(
+    "DYNAMODB_USAGE_LOG_EXPORT_LAMBDA_NAME",
+    f"{CDK_PREFIX}DynamoUsageLogExport".lower().replace("_", "-"),
+)
+DYNAMODB_USAGE_LOG_EXPORT_SCHEDULE = get_or_create_env_var(
+    "DYNAMODB_USAGE_LOG_EXPORT_SCHEDULE", "cron(0 6 ? * * *)"
+)
+DYNAMODB_USAGE_LOG_EXPORT_S3_KEY = get_or_create_env_var(
+    "DYNAMODB_USAGE_LOG_EXPORT_S3_KEY",
+    "reports/dynamodb-usage/dynamodb_logs_export.csv",
+)
+DYNAMODB_USAGE_LOG_EXPORT_DATE_ATTRIBUTE = get_or_create_env_var(
+    "DYNAMODB_USAGE_LOG_EXPORT_DATE_ATTRIBUTE", "timestamp"
+)
+DYNAMODB_USAGE_LOG_EXPORT_OUTPUT_FILENAME = get_or_create_env_var(
+    "DYNAMODB_USAGE_LOG_EXPORT_OUTPUT_FILENAME", "dynamodb_logs_export.csv"
+)
+
+if ENABLE_DYNAMODB_USAGE_LOG_EXPORT == "True":
+    if SAVE_LOGS_TO_DYNAMODB != "True":
+        raise ValueError(
+            "ENABLE_DYNAMODB_USAGE_LOG_EXPORT=True requires SAVE_LOGS_TO_DYNAMODB=True."
+        )
+    schedule = (DYNAMODB_USAGE_LOG_EXPORT_SCHEDULE or "").strip()
+    if not schedule.startswith("cron(") and not schedule.startswith("rate("):
+        raise ValueError(
+            "DYNAMODB_USAGE_LOG_EXPORT_SCHEDULE must be an EventBridge cron(...) or "
+            f"rate(...) expression; got {schedule!r}."
+        )
+    if not (DYNAMODB_USAGE_LOG_EXPORT_S3_KEY or "").strip():
+        raise ValueError(
+            "DYNAMODB_USAGE_LOG_EXPORT_S3_KEY is required when "
+            "ENABLE_DYNAMODB_USAGE_LOG_EXPORT=True."
+        )
+
+###
+# APP OPTIONS
+###
+
+# Get some environment variables and Launch the Gradio app
+COGNITO_AUTH = get_or_create_env_var("COGNITO_AUTH", "False")
+
+GRADIO_SERVER_PORT = int(get_or_create_env_var("GRADIO_SERVER_PORT", "7860"))
+
+# Must match the named port mapping on the Fargate container (see cdk_stack.py).
+ECS_SERVICE_CONNECT_PORT_MAPPING_NAME = get_or_create_env_var(
+    "ECS_SERVICE_CONNECT_PORT_MAPPING_NAME", f"port-{GRADIO_SERVER_PORT}"
+)
+
+# Suffix used with ECS_SERVICE_CONNECT_CLIENT_CDK_PREFIXES (matches this stack's ECS SG name).
+if ECS_SECURITY_GROUP_NAME.startswith(CDK_PREFIX):
+    _default_sc_client_sg_suffix = ECS_SECURITY_GROUP_NAME[len(CDK_PREFIX) :]
+else:
+    _default_sc_client_sg_suffix = "SecurityGroupECS"
+ECS_SERVICE_CONNECT_CLIENT_SG_NAME_SUFFIX = get_or_create_env_var(
+    "ECS_SERVICE_CONNECT_CLIENT_SG_NAME_SUFFIX", _default_sc_client_sg_suffix
+)
+
+ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_NAMES_LIST = parse_comma_separated_list(
+    ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_NAMES
+)
+ECS_SERVICE_CONNECT_CLIENT_CDK_PREFIXES_LIST = parse_comma_separated_list(
+    ECS_SERVICE_CONNECT_CLIENT_CDK_PREFIXES
+)
+
+
+def build_service_connect_client_security_group_names() -> List[str]:
+    """Explicit SG names plus {prefix}{suffix} for each client CDK_PREFIX."""
+    names: List[str] = list(ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_NAMES_LIST)
+    for prefix in ECS_SERVICE_CONNECT_CLIENT_CDK_PREFIXES_LIST:
+        names.append(f"{prefix}{ECS_SERVICE_CONNECT_CLIENT_SG_NAME_SUFFIX}")
+    deduped: List[str] = []
+    seen = set()
+    for name in names:
+        if name and name not in seen:
+            seen.add(name)
+            deduped.append(name)
+    return deduped
+
+
+ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_NAMES_TO_LOOKUP = (
+    build_service_connect_client_security_group_names()
+)
+
+if ENABLE_ECS_SERVICE_CONNECT == "True" and USE_ECS_EXPRESS_MODE == "True":
+    raise ValueError(
+        "ENABLE_ECS_SERVICE_CONNECT=True is only supported on the legacy Fargate "
+        "service path. Set USE_ECS_EXPRESS_MODE=False or disable Service Connect."
+    )
+
+# Headless deployment: S3 job .env -> Lambda -> one-shot ECS Fargate (RUN_DIRECT_MODE).
+# No ALB, CloudFront, or always-on ECS service.
+ENABLE_HEADLESS_DEPLOYMENT = get_or_create_env_var(
+    "ENABLE_HEADLESS_DEPLOYMENT", "False"
+)
+
+# S3-uploaded job .env files trigger one-shot ECS Fargate tasks (direct mode / cli_redact).
+ENABLE_S3_BATCH_ECS_TRIGGER = get_or_create_env_var(
+    "ENABLE_S3_BATCH_ECS_TRIGGER", "False"
+)
+S3_BATCH_ENV_PREFIX = get_or_create_env_var("S3_BATCH_ENV_PREFIX", "input/config/")
+S3_BATCH_ENV_SUFFIX = get_or_create_env_var("S3_BATCH_ENV_SUFFIX", ".env")
+S3_BATCH_INPUT_PREFIX = get_or_create_env_var("S3_BATCH_INPUT_PREFIX", "input/")
+S3_BATCH_CONFIG_PREFIX = get_or_create_env_var("S3_BATCH_CONFIG_PREFIX", "")
+# Durable batch defaults live on the log/config bucket (S3_LOG_CONFIG_BUCKET_NAME),
+# not the output bucket, which has an object-expiration lifecycle rule.
+S3_BATCH_GENERAL_ENV_PREFIX = get_or_create_env_var(
+    "S3_BATCH_GENERAL_ENV_PREFIX", "general-config/"
+)
+S3_BATCH_DEFAULT_PARAMS_KEY = get_or_create_env_var(
+    "S3_BATCH_DEFAULT_PARAMS_KEY", "general-config/app_defaults.env"
+)
+S3_BATCH_LAMBDA_FUNCTION_NAME = get_or_create_env_var(
+    "S3_BATCH_LAMBDA_FUNCTION_NAME", f"{CDK_PREFIX}S3BatchEcsTrigger"
+)
+
+if ENABLE_S3_BATCH_ECS_TRIGGER == "True" and USE_ECS_EXPRESS_MODE == "True":
+    raise ValueError(
+        "ENABLE_S3_BATCH_ECS_TRIGGER=True requires the legacy Fargate task definition "
+        "for ecs.run_task. Set USE_ECS_EXPRESS_MODE=False or disable the batch trigger."
+    )
+
+if ENABLE_HEADLESS_DEPLOYMENT == "True":
+    if ENABLE_S3_BATCH_ECS_TRIGGER != "True":
+        raise ValueError(
+            "ENABLE_HEADLESS_DEPLOYMENT=True requires ENABLE_S3_BATCH_ECS_TRIGGER=True."
+        )
+    if USE_ECS_EXPRESS_MODE == "True":
+        raise ValueError(
+            "ENABLE_HEADLESS_DEPLOYMENT=True requires USE_ECS_EXPRESS_MODE=False."
+        )
+    if USE_CLOUDFRONT == "True":
+        raise ValueError(
+            "ENABLE_HEADLESS_DEPLOYMENT=True is incompatible with USE_CLOUDFRONT=True."
+        )
+
+# Account-level Bedrock model invocation logging (S3 + CloudWatch) for this Region.
+# Uses a CDK custom resource (no CloudFormation L1 for PutModelInvocationLoggingConfiguration).
+ENABLE_BEDROCK_MODEL_INVOCATION_LOGGING = get_or_create_env_var(
+    "ENABLE_BEDROCK_MODEL_INVOCATION_LOGGING", "False"
+)
+BEDROCK_MODEL_INVOCATION_S3_PREFIX = get_or_create_env_var(
+    "BEDROCK_MODEL_INVOCATION_S3_PREFIX", "bedrock-logs"
+)
+BEDROCK_MODEL_INVOCATION_LOG_GROUP_NAME = get_or_create_env_var(
+    "BEDROCK_MODEL_INVOCATION_LOG_GROUP_NAME",
+    f"/aws/bedrock/{CDK_PREFIX}model-invocations".rstrip("/"),
+)
+BEDROCK_MODEL_INVOCATION_LOG_RETENTION_DAYS = get_or_create_env_var(
+    "BEDROCK_MODEL_INVOCATION_LOG_RETENTION_DAYS", "90"
+)
+BEDROCK_MODEL_INVOCATION_TEXT_ENABLED = get_or_create_env_var(
+    "BEDROCK_MODEL_INVOCATION_TEXT_ENABLED", "True"
+)
+BEDROCK_MODEL_INVOCATION_IMAGE_ENABLED = get_or_create_env_var(
+    "BEDROCK_MODEL_INVOCATION_IMAGE_ENABLED", "True"
+)
+BEDROCK_MODEL_INVOCATION_EMBEDDING_ENABLED = get_or_create_env_var(
+    "BEDROCK_MODEL_INVOCATION_EMBEDDING_ENABLED", "True"
+)
+BEDROCK_MODEL_INVOCATION_VIDEO_ENABLED = get_or_create_env_var(
+    "BEDROCK_MODEL_INVOCATION_VIDEO_ENABLED", "True"
+)
+
+# Optional Bedrock Guardrails on Converse (app + headless batch defaults; set via cdk_install).
+ENABLE_BEDROCK_GUARDRAILS = get_or_create_env_var("ENABLE_BEDROCK_GUARDRAILS", "False")
+BEDROCK_GUARDRAIL_IDENTIFIER = get_or_create_env_var(
+    "BEDROCK_GUARDRAIL_IDENTIFIER", ""
+).strip()
+BEDROCK_GUARDRAIL_VERSION = get_or_create_env_var(
+    "BEDROCK_GUARDRAIL_VERSION", ""
+).strip()
+BEDROCK_GUARDRAIL_TRACE = (
+    get_or_create_env_var("BEDROCK_GUARDRAIL_TRACE", "disabled").strip().lower()
+)
+
+# Optional headless follow-on: S3 output PutRequests alarm -> SNS email + IAM user for downloads.
+ENABLE_HEADLESS_OUTPUT_NOTIFICATIONS = get_or_create_env_var(
+    "ENABLE_HEADLESS_OUTPUT_NOTIFICATIONS", "False"
+)
+HEADLESS_OUTPUT_NOTIFY_EMAIL = get_or_create_env_var("HEADLESS_OUTPUT_NOTIFY_EMAIL", "")
+HEADLESS_OUTPUT_IAM_USER_NAME = get_or_create_env_var(
+    "HEADLESS_OUTPUT_IAM_USER_NAME", f"{CDK_PREFIX}s3-output-reader"
+)
+HEADLESS_OUTPUT_S3_METRIC_FILTER_ID = get_or_create_env_var(
+    "HEADLESS_OUTPUT_S3_METRIC_FILTER_ID",
+    f"{CDK_PREFIX}s3-output-put".lower().replace("_", "-"),
+)
+HEADLESS_OUTPUT_SNS_TOPIC_NAME = get_or_create_env_var(
+    "HEADLESS_OUTPUT_SNS_TOPIC_NAME",
+    f"{CDK_PREFIX}llm-topic-s3-save-sns".lower().replace("_", "-"),
+)
+HEADLESS_OUTPUT_ALARM_NAME = get_or_create_env_var(
+    "HEADLESS_OUTPUT_ALARM_NAME",
+    f"{CDK_PREFIX}cloudwatch-alarm-new-output-s3".lower().replace("_", "-"),
+)
+HEADLESS_OUTPUT_S3_PREFIX = get_or_create_env_var(
+    "HEADLESS_OUTPUT_S3_PREFIX", "output/"
+)
+HEADLESS_OUTPUT_IAM_SECRET_NAME = get_or_create_env_var(
+    "HEADLESS_OUTPUT_IAM_SECRET_NAME",
+    f"{CDK_PREFIX}headless-output-reader-key",
+)
+
+if ENABLE_HEADLESS_OUTPUT_NOTIFICATIONS == "True":
+    if ENABLE_HEADLESS_DEPLOYMENT != "True":
+        raise ValueError(
+            "ENABLE_HEADLESS_OUTPUT_NOTIFICATIONS=True requires "
+            "ENABLE_HEADLESS_DEPLOYMENT=True."
+        )
+    if not (HEADLESS_OUTPUT_NOTIFY_EMAIL or "").strip():
+        raise ValueError(
+            "HEADLESS_OUTPUT_NOTIFY_EMAIL is required when "
+            "ENABLE_HEADLESS_OUTPUT_NOTIFICATIONS=True."
+        )
+
+# Pi agent Gradio UI (second Fargate service; shared legacy ALB + Service Connect to main app).
+ENABLE_PI_AGENT_ECS_SERVICE = get_or_create_env_var(
+    "ENABLE_PI_AGENT_ECS_SERVICE", "False"
+)
+ECR_PI_REPO_NAME = get_or_create_env_var(
+    "ECR_PI_REPO_NAME", f"{CDK_PREFIX}pi-agent".lower()
+)
+CODEBUILD_PI_PROJECT_NAME = get_or_create_env_var(
+    "CODEBUILD_PI_PROJECT_NAME", f"{CDK_PREFIX}CodeBuildPiAgent"
+)
+ECS_PI_TASK_DEFINITION_NAME = get_or_create_env_var(
+    "ECS_PI_TASK_DEFINITION_NAME", f"{CDK_PREFIX}PiAgentTaskDefinition"
+)
+ECS_PI_SECURITY_GROUP_NAME = get_or_create_env_var(
+    "ECS_PI_SECURITY_GROUP_NAME", f"{CDK_PREFIX}SecurityGroupPiAgent"
+)
+ECS_PI_LOG_GROUP_NAME = get_or_create_env_var(
+    "ECS_PI_LOG_GROUP_NAME", f"/ecs/{ECS_PI_SERVICE_NAME}-logs".lower()
+)
+ECS_PI_TASK_CPU_SIZE = get_or_create_env_var("ECS_PI_TASK_CPU_SIZE", "1024")
+ECS_PI_TASK_MEMORY_SIZE = get_or_create_env_var("ECS_PI_TASK_MEMORY_SIZE", "2048")
+PI_GRADIO_PORT = get_or_create_env_var("PI_GRADIO_PORT", "7862")
+# Pi ALB routing: path (default /pi on shared host e.g. CloudFront), host, or both.
+PI_ALB_ROUTING = get_or_create_env_var("PI_ALB_ROUTING", "path").strip().lower()
+PI_ALB_PATH_PREFIX = get_or_create_env_var("PI_ALB_PATH_PREFIX", "/pi")
+PI_ALB_HOST_HEADER = get_or_create_env_var("PI_ALB_HOST_HEADER", "")
+PI_ALB_TARGET_GROUP_NAME = get_or_create_env_var(
+    "PI_ALB_TARGET_GROUP_NAME", f"{CDK_PREFIX}PiAgentTG"[-32:]
+)
+PI_ALB_LISTENER_RULE_PRIORITY = int(
+    get_or_create_env_var("PI_ALB_LISTENER_RULE_PRIORITY", "3")
+)
+PI_AGENT_ENV_S3_KEY = get_or_create_env_var("PI_AGENT_ENV_S3_KEY", "pi_agent.env")
+
+
+def _normalize_pi_alb_path_prefix(raw: str) -> str:
+    segment = (raw or "pi").strip().strip("/")
+    return f"/{segment}" if segment else "/pi"
+
+
+PI_ALB_PATH_PREFIX_NORMALIZED = _normalize_pi_alb_path_prefix(PI_ALB_PATH_PREFIX)
+_PI_ALB_ROUTING_MODES = frozenset({"path", "host", "both"})
+
+
+def _validate_pi_alb_routing_for_enabled_pi() -> None:
+    if PI_ALB_ROUTING not in _PI_ALB_ROUTING_MODES:
+        raise ValueError(
+            f"PI_ALB_ROUTING must be one of {sorted(_PI_ALB_ROUTING_MODES)}; got '{PI_ALB_ROUTING}'."
+        )
+    if PI_ALB_ROUTING in ("host", "both") and not PI_ALB_HOST_HEADER.strip():
+        raise ValueError(
+            "PI_ALB_HOST_HEADER is required when PI_ALB_ROUTING is 'host' or 'both' "
+            "(dedicated hostname on the shared ALB)."
+        )
+    if PI_ALB_ROUTING in ("path", "both") and not PI_ALB_PATH_PREFIX_NORMALIZED:
+        raise ValueError("PI_ALB_PATH_PREFIX must resolve to a non-empty path segment.")
+
+
+# Pi on ECS Express Mode (second Express service on shared ALB; SC via ecs:UpdateService).
+ENABLE_PI_AGENT_EXPRESS_SERVICE = get_or_create_env_var(
+    "ENABLE_PI_AGENT_EXPRESS_SERVICE", "False"
+)
+ECS_PI_EXPRESS_SERVICE_NAME = get_or_create_env_var(
+    "ECS_PI_EXPRESS_SERVICE_NAME", f"{CDK_PREFIX}PiExpressService"
+)
+ECS_PI_EXPRESS_HEALTH_CHECK_PATH = get_or_create_env_var(
+    "ECS_PI_EXPRESS_HEALTH_CHECK_PATH", "/health"
+)
+ECS_PI_EXPRESS_SECURITY_GROUP_NAME = get_or_create_env_var(
+    "ECS_PI_EXPRESS_SECURITY_GROUP_NAME", f"{CDK_PREFIX}SecurityGroupPiExpress"
+)
+# Service Connect port names for Express services (applied in post_cdk_build_quickstart.py).
+ECS_EXPRESS_SC_PORT_NAME = get_or_create_env_var(
+    "ECS_EXPRESS_SC_PORT_NAME", ECS_SERVICE_CONNECT_PORT_MAPPING_NAME
+)
+ECS_PI_EXPRESS_SC_PORT_NAME = get_or_create_env_var(
+    "ECS_PI_EXPRESS_SC_PORT_NAME", f"port-{PI_GRADIO_PORT}"
+)
+
+if ENABLE_PI_AGENT_ECS_SERVICE == "True" and ENABLE_PI_AGENT_EXPRESS_SERVICE == "True":
+    raise ValueError(
+        "Enable at most one Pi deployment mode: ENABLE_PI_AGENT_ECS_SERVICE (legacy Fargate) "
+        "or ENABLE_PI_AGENT_EXPRESS_SERVICE (Express), not both."
+    )
+if ENABLE_PI_AGENT_EXPRESS_SERVICE == "True" and USE_ECS_EXPRESS_MODE != "True":
+    raise ValueError(
+        "ENABLE_PI_AGENT_EXPRESS_SERVICE=True requires USE_ECS_EXPRESS_MODE=True "
+        "(no ACM_SSL_CERTIFICATE_ARN)."
+    )
+if ENABLE_PI_AGENT_ECS_SERVICE == "True" and USE_ECS_EXPRESS_MODE == "True":
+    raise ValueError(
+        "ENABLE_PI_AGENT_ECS_SERVICE=True requires legacy Fargate (USE_ECS_EXPRESS_MODE=False). "
+        "For Pi on Express, use ENABLE_PI_AGENT_EXPRESS_SERVICE=True instead."
+    )
+if ENABLE_PI_AGENT_ECS_SERVICE == "True" and ENABLE_ECS_SERVICE_CONNECT != "True":
+    raise ValueError(
+        "ENABLE_PI_AGENT_ECS_SERVICE=True requires ENABLE_ECS_SERVICE_CONNECT=True "
+        "so the Pi task can reach the main app at http://<discovery>:7860."
+    )
+if ENABLE_PI_AGENT_ECS_SERVICE == "True":
+    _validate_pi_alb_routing_for_enabled_pi()
+
+###
+# WHOLE DOCUMENT API OPTIONS
+###
+
+DAYS_TO_DISPLAY_WHOLE_DOCUMENT_JOBS = get_or_create_env_var(
+    "DAYS_TO_DISPLAY_WHOLE_DOCUMENT_JOBS", "7"
+)  # How many days into the past should whole document Textract jobs be displayed? After that, the data is not deleted from the Textract jobs csv, but it is just filtered out. Included to align with S3 buckets where the file outputs will be automatically deleted after X days.

cdk/cdk_post_deploy.py

@@ -0,0 +1,1492 @@
+"""
+Post-deploy helpers (boto3 only).
+
+Use this module from post_cdk_build_quickstart.py so you do not need Node.js or
+aws-cdk-lib installed to start CodeBuild / ECS after deployment.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import re
+import time
+from typing import Any, Dict, List, Optional, Union
+
+import boto3
+from cdk_config import (
+    AWS_REGION,
+    CLOUDFRONT_DOMAIN,
+)
+
+_TASK_DEF_REGISTER_KEYS = (
+    "family",
+    "taskRoleArn",
+    "executionRoleArn",
+    "networkMode",
+    "containerDefinitions",
+    "volumes",
+    "placementConstraints",
+    "requiresCompatibilities",
+    "cpu",
+    "memory",
+    "pidMode",
+    "ipcMode",
+    "proxyConfiguration",
+    "inferenceAccelerators",
+    "ephemeralStorage",
+    "runtimePlatform",
+)
+
+_CONTAINER_REGISTER_OMIT_KEYS = frozenset(
+    {
+        "containerArn",
+        "taskDefinitionArn",
+        "status",
+        "lastStatus",
+        "managedAgents",
+        "networkInterfaces",
+        "healthStatus",
+        "cpu",
+        "memory",
+        "gpu",
+    }
+)
+
+
+def start_codebuild_build(project_name: str, aws_region: str = AWS_REGION) -> None:
+    """Start an existing CodeBuild project build."""
+    client = boto3.client("codebuild", region_name=aws_region)
+
+    try:
+        print(f"Attempting to start build for project: {project_name}")
+        response = client.start_build(projectName=project_name)
+        build_id = response["build"]["id"]
+        print(f"Successfully started build with ID: {build_id}")
+        print(f"Build ARN: {response['build']['arn']}")
+        print(
+            f"https://{aws_region}.console.aws.amazon.com/codesuite/codebuild/projects/"
+            f"{project_name}/build/{build_id.split(':')[-1]}/detail"
+        )
+    except client.exceptions.ResourceNotFoundException:
+        print(f"Error: Project '{project_name}' not found in region '{aws_region}'.")
+    except Exception as e:
+        print(f"An unexpected error occurred: {e}")
+
+
+def upload_file_to_s3(
+    local_file_paths: Union[str, List[str]],
+    s3_key: str,
+    s3_bucket: str,
+    run_aws_functions: str = "1",
+    aws_region: str = AWS_REGION,
+) -> str:
+    """Upload local file(s) to S3."""
+    final_out_message: List[str] = []
+    final_out_message_str = ""
+
+    if run_aws_functions != "1":
+        return "App not set to run AWS functions"
+
+    try:
+        if not (s3_bucket and local_file_paths):
+            return "At least one essential variable is empty, could not upload to S3"
+
+        s3_client = boto3.client("s3", region_name=aws_region)
+        paths = (
+            [local_file_paths]
+            if isinstance(local_file_paths, str)
+            else list(local_file_paths)
+        )
+
+        for file_path in paths:
+            try:
+                file_name = os.path.basename(file_path)
+                s3_key_full = s3_key + file_name
+                print("S3 key: ", s3_key_full)
+                s3_client.upload_file(file_path, s3_bucket, s3_key_full)
+                out_message = f"File {file_name} uploaded successfully!"
+                print(out_message)
+            except Exception as e:
+                out_message = f"Error uploading file(s): {e}"
+                print(out_message)
+            final_out_message.append(out_message)
+
+        final_out_message_str = "\n".join(final_out_message)
+    except Exception as e:
+        final_out_message_str = "Could not upload files to S3 due to: " + str(e)
+        print(final_out_message_str)
+
+    return final_out_message_str
+
+
+def start_ecs_task(
+    cluster_name: str,
+    service_name: str,
+    aws_region: str = AWS_REGION,
+) -> dict:
+    """Scale a legacy Fargate ECS service to one running task."""
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+
+    try:
+        ecs_client.update_service(
+            cluster=cluster_name, service=service_name, desiredCount=1
+        )
+        return {
+            "statusCode": 200,
+            "body": (
+                f"Service {service_name} in cluster {cluster_name} "
+                "has been updated to 1 task."
+            ),
+        }
+    except Exception as e:
+        return {"statusCode": 500, "body": f"Error updating service: {str(e)}"}
+
+
+EXPRESS_GATEWAY_ACTIVE_SCALING_TARGET = {
+    "minTaskCount": 1,
+    "maxTaskCount": 1,
+    "autoScalingMetric": "AVERAGE_CPU",
+    "autoScalingTargetValue": 60,
+}
+
+
+def resolve_express_gateway_service_arn(
+    cluster_name: str,
+    service_name: str,
+    aws_region: str = AWS_REGION,
+) -> str:
+    """Look up an Express gateway service ARN by cluster and service name."""
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+    paginator = ecs_client.get_paginator("list_services")
+    for page in paginator.paginate(cluster=cluster_name):
+        for arn in page.get("serviceArns", []):
+            if arn.rstrip("/").split("/")[-1] == service_name:
+                return arn
+    raise ValueError(
+        f"Express gateway service '{service_name}' not found in cluster "
+        f"'{cluster_name}'."
+    )
+
+
+def _task_definition_has_port_name(
+    task_definition: Dict[str, Any], port_name: str
+) -> bool:
+    for container in task_definition.get("containerDefinitions", []):
+        for mapping in container.get("portMappings") or []:
+            if mapping.get("name") == port_name:
+                return True
+    return False
+
+
+def _container_definitions_with_named_port(
+    container_definitions: List[Dict[str, Any]],
+    *,
+    port_name: str,
+    container_port: int,
+) -> List[Dict[str, Any]]:
+    updated: List[Dict[str, Any]] = []
+    has_matching_port = any(
+        mapping.get("containerPort") == container_port
+        for container in container_definitions
+        for mapping in container.get("portMappings") or []
+    )
+    for index, container in enumerate(container_definitions):
+        container = {
+            key: value
+            for key, value in container.items()
+            if key not in _CONTAINER_REGISTER_OMIT_KEYS
+        }
+        port_mappings = [
+            dict(mapping) for mapping in container.get("portMappings") or []
+        ]
+        matched = False
+        for mapping in port_mappings:
+            if mapping.get("containerPort") == container_port:
+                matched = True
+                mapping["name"] = port_name
+                mapping.setdefault("protocol", "tcp")
+        if not matched and not has_matching_port and index == 0:
+            port_mappings.append(
+                {
+                    "name": port_name,
+                    "containerPort": container_port,
+                    "protocol": "tcp",
+                }
+            )
+        container["portMappings"] = port_mappings
+        updated.append(container)
+    return updated
+
+
+def resolve_service_task_definition_arn(
+    cluster_name: str,
+    service_name: str,
+    aws_region: str = AWS_REGION,
+) -> str:
+    """
+    Resolve the task definition ARN for a Fargate or Express gateway ECS service.
+
+    Express gateway services omit ``taskDefinition`` on ``describe_services``; use the
+    active service revision from ``describe_express_gateway_service`` instead.
+    """
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+    services = ecs_client.describe_services(
+        cluster=cluster_name, services=[service_name]
+    ).get("services", [])
+    if services:
+        task_definition_arn = services[0].get("taskDefinition")
+        if task_definition_arn:
+            return task_definition_arn
+        service_arn = services[0].get("serviceArn")
+    else:
+        service_arn = None
+
+    if not service_arn:
+        service_arn = resolve_express_gateway_service_arn(
+            cluster_name, service_name, aws_region
+        )
+
+    express = ecs_client.describe_express_gateway_service(serviceArn=service_arn)
+    active_configs = (express.get("service") or {}).get("activeConfigurations") or []
+    if not active_configs:
+        raise ValueError(
+            f"Could not resolve task definition for service '{service_name}' in "
+            f"cluster '{cluster_name}' (no active Express gateway configuration)."
+        )
+    revision_arn = active_configs[0].get("serviceRevisionArn")
+    if not revision_arn:
+        raise ValueError(
+            f"Could not resolve task definition for service '{service_name}' "
+            "(active Express configuration has no serviceRevisionArn)."
+        )
+    revisions = ecs_client.describe_service_revisions(
+        serviceRevisionArns=[revision_arn]
+    ).get("serviceRevisions", [])
+    if not revisions:
+        raise ValueError(
+            f"Service revision '{revision_arn}' not found for service "
+            f"'{service_name}'."
+        )
+    task_definition_arn = revisions[0].get("taskDefinition")
+    if not task_definition_arn:
+        raise ValueError(
+            f"Service revision '{revision_arn}' has no taskDefinition for service "
+            f"'{service_name}'."
+        )
+    return task_definition_arn
+
+
+def ensure_ecs_service_port_mapping_name(
+    cluster_name: str,
+    service_name: str,
+    port_name: str,
+    container_port: int,
+    aws_region: str = AWS_REGION,
+) -> str:
+    """
+    Service Connect requires a named portMapping in the task definition.
+    Express gateway services only set containerPort at create time.
+    """
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+    task_definition_arn = resolve_service_task_definition_arn(
+        cluster_name, service_name, aws_region
+    )
+    task_definition = ecs_client.describe_task_definition(
+        taskDefinition=task_definition_arn
+    )["taskDefinition"]
+    if _task_definition_has_port_name(task_definition, port_name):
+        return task_definition_arn
+
+    new_containers = _container_definitions_with_named_port(
+        task_definition["containerDefinitions"],
+        port_name=port_name,
+        container_port=container_port,
+    )
+    register_kwargs = {
+        key: copy.deepcopy(task_definition[key])
+        for key in _TASK_DEF_REGISTER_KEYS
+        if key in task_definition
+    }
+    register_kwargs["containerDefinitions"] = new_containers
+    if task_definition.get("tags"):
+        register_kwargs["tags"] = [
+            {"key": tag["key"], "value": tag["value"]}
+            for tag in task_definition["tags"]
+        ]
+
+    new_task_definition = ecs_client.register_task_definition(**register_kwargs)[
+        "taskDefinition"
+    ]
+    new_arn = new_task_definition["taskDefinitionArn"]
+    ecs_client.update_service(
+        cluster=cluster_name,
+        service=service_name,
+        taskDefinition=new_arn,
+        forceNewDeployment=True,
+    )
+    print(
+        f"Registered task definition {new_arn} with Service Connect port "
+        f"name {port_name!r} on container port {container_port}."
+    )
+    return new_arn
+
+
+def apply_ecs_service_connect(
+    cluster_name: str,
+    service_name: str,
+    service_connect_configuration: Dict[str, Any],
+    aws_region: str = AWS_REGION,
+) -> None:
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+    ecs_client.update_service(
+        cluster=cluster_name,
+        service=service_name,
+        serviceConnectConfiguration=service_connect_configuration,
+        forceNewDeployment=True,
+    )
+    print(f"Applied Service Connect to {service_name} in cluster {cluster_name}.")
+
+
+def configure_express_pi_service_connect(
+    cluster_name: str,
+    main_service_name: str,
+    pi_service_name: str,
+    namespace: str,
+    main_port_name: str,
+    discovery_name: str,
+    main_port: int,
+    aws_region: str = AWS_REGION,
+) -> None:
+    """Enable Service Connect for Pi Express -> main Express (post image build)."""
+    ensure_ecs_service_port_mapping_name(
+        cluster_name,
+        main_service_name,
+        main_port_name,
+        main_port,
+        aws_region=aws_region,
+    )
+    apply_ecs_service_connect(
+        cluster_name,
+        main_service_name,
+        {
+            "enabled": True,
+            "namespace": namespace,
+            "services": [
+                {
+                    "portName": main_port_name,
+                    "discoveryName": discovery_name,
+                    "clientAliases": [
+                        {"port": int(main_port), "dnsName": discovery_name}
+                    ],
+                }
+            ],
+        },
+        aws_region=aws_region,
+    )
+    apply_ecs_service_connect(
+        cluster_name,
+        pi_service_name,
+        {"enabled": True, "namespace": namespace},
+        aws_region=aws_region,
+    )
+
+
+def start_express_gateway_service(
+    cluster_name: str,
+    service_name: str,
+    aws_region: str = AWS_REGION,
+) -> dict:
+    """Scale an ECS Express gateway service to one running task after image build."""
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+
+    try:
+        service_arn = resolve_express_gateway_service_arn(
+            cluster_name, service_name, aws_region=aws_region
+        )
+        ecs_client.update_express_gateway_service(
+            serviceArn=service_arn,
+            scalingTarget=EXPRESS_GATEWAY_ACTIVE_SCALING_TARGET,
+        )
+        return {
+            "statusCode": 200,
+            "body": (
+                f"Express service {service_name} in cluster {cluster_name} "
+                "has been updated to run 1 task."
+            ),
+        }
+    except Exception as e:
+        return {
+            "statusCode": 500,
+            "body": f"Error updating Express gateway service: {str(e)}",
+        }
+
+
+_ALB_COGNITO_CALLBACK_SUFFIX = "/oauth2/idpresponse"
+
+# Fields preserved from describe_user_pool_client when updating CallbackURLs only.
+_USER_POOL_CLIENT_UPDATE_PASSTHROUGH_KEYS = (
+    "ClientName",
+    "RefreshTokenValidity",
+    "AccessTokenValidity",
+    "IdTokenValidity",
+    "TokenValidityUnits",
+    "ReadAttributes",
+    "WriteAttributes",
+    "ExplicitAuthFlows",
+    "SupportedIdentityProviders",
+    "DefaultRedirectURI",
+    "AllowedOAuthFlows",
+    "AllowedOAuthScopes",
+    "AllowedOAuthFlowsUserPoolClient",
+    "AnalyticsConfiguration",
+    "PreventUserExistenceErrors",
+    "EnableTokenRevocation",
+    "EnablePropagateAdditionalUserContextData",
+    "AuthSessionValidity",
+    "RefreshTokenRotation",
+)
+
+
+def cognito_https_callback_urls(redirect_base: str) -> List[str]:
+    """
+    ALB authenticate-cognito requires the app URL and ``/oauth2/idpresponse``.
+    """
+    base = (redirect_base or "").strip().rstrip("/")
+    if not base:
+        raise ValueError("redirect_base is required for Cognito callback URLs")
+    if not base.startswith("https://"):
+        base = f"https://{base.lstrip('/')}"
+    return [base, f"{base}{_ALB_COGNITO_CALLBACK_SUFFIX}"]
+
+
+def cognito_callback_urls_match(
+    existing_callbacks: List[str],
+    desired_callbacks: List[str],
+) -> bool:
+    return set(existing_callbacks or []) == set(desired_callbacks)
+
+
+def get_user_pool_client_callback_urls(
+    user_pool_id: str,
+    client_id: str,
+    *,
+    aws_region: str = AWS_REGION,
+) -> List[str]:
+    cognito_client = boto3.client("cognito-idp", region_name=aws_region)
+    existing = cognito_client.describe_user_pool_client(
+        UserPoolId=user_pool_id,
+        ClientId=client_id,
+    )["UserPoolClient"]
+    return list(existing.get("CallbackURLs") or [])
+
+
+def cognito_alb_callbacks_need_update(
+    user_pool_id: str,
+    client_id: str,
+    redirect_base: str,
+    *,
+    aws_region: str = AWS_REGION,
+) -> bool:
+    desired = cognito_https_callback_urls(redirect_base)
+    current = get_user_pool_client_callback_urls(
+        user_pool_id, client_id, aws_region=aws_region
+    )
+    return not cognito_callback_urls_match(current, desired)
+
+
+def update_user_pool_client_callback_urls(
+    user_pool_id: str,
+    client_id: str,
+    callback_urls: List[str],
+    *,
+    aws_region: str = AWS_REGION,
+) -> None:
+    """
+    Set Cognito app client callback URLs without a CDK redeploy.
+
+    Merges existing client settings from ``describe_user_pool_client`` so OAuth
+    flows/scopes and token validity are not reset.
+    """
+    cognito_client = boto3.client("cognito-idp", region_name=aws_region)
+    existing = cognito_client.describe_user_pool_client(
+        UserPoolId=user_pool_id,
+        ClientId=client_id,
+    )["UserPoolClient"]
+
+    update_kwargs: Dict[str, Any] = {
+        "UserPoolId": user_pool_id,
+        "ClientId": client_id,
+        "CallbackURLs": callback_urls,
+    }
+    for key in _USER_POOL_CLIENT_UPDATE_PASSTHROUGH_KEYS:
+        value = existing.get(key)
+        if value is not None:
+            update_kwargs[key] = value
+    logout_urls = existing.get("LogoutURLs")
+    if logout_urls:
+        update_kwargs["LogoutURLs"] = logout_urls
+
+    cognito_client.update_user_pool_client(**update_kwargs)
+    print("Updated Cognito app client callback URLs: " + ", ".join(callback_urls))
+
+
+def apply_cognito_alb_callback_fixup(
+    *,
+    user_pool_id: str,
+    client_id: str,
+    redirect_base: str,
+    aws_region: str = AWS_REGION,
+) -> bool:
+    """
+    Update Cognito callbacks when they differ from ``redirect_base``.
+
+    Returns True if URLs were updated, False if already correct.
+    """
+    desired = cognito_https_callback_urls(redirect_base)
+    cognito_client = boto3.client("cognito-idp", region_name=aws_region)
+    existing = cognito_client.describe_user_pool_client(
+        UserPoolId=user_pool_id,
+        ClientId=client_id,
+    )["UserPoolClient"]
+    current = existing.get("CallbackURLs") or []
+    if cognito_callback_urls_match(current, desired):
+        print("Cognito app client callback URLs already match the target endpoint.")
+        return False
+    update_user_pool_client_callback_urls(
+        user_pool_id,
+        client_id,
+        desired,
+        aws_region=aws_region,
+    )
+    return True
+
+
+_TARGET_GROUP_REGISTER_EVENT = re.compile(
+    r"target-group (arn:aws:elasticloadbalancing:[^\s)]+)",
+    re.IGNORECASE,
+)
+
+EXPRESS_TARGET_GROUP_RESOLVE_MAX_WAIT_SECONDS = 600
+EXPRESS_TARGET_GROUP_RESOLVE_POLL_INTERVAL_SECONDS = 15
+
+
+def target_group_arn_from_ecs_register_event(message: str) -> Optional[str]:
+    """Parse target group ARN from ECS ``registered N targets in (target-group ...)``."""
+    if "registered" not in (message or "").lower():
+        return None
+    match = _TARGET_GROUP_REGISTER_EVENT.search(message)
+    return match.group(1) if match else None
+
+
+def _target_group_arn_from_service_events(
+    events: List[Dict[str, Any]],
+) -> Optional[str]:
+    for event in events:
+        target_group_arn = target_group_arn_from_ecs_register_event(
+            event.get("message", "")
+        )
+        if target_group_arn:
+            return target_group_arn
+    return None
+
+
+def _task_private_ipv4_addresses(
+    ecs_client: Any,
+    cluster_name: str,
+    service_name: str,
+) -> set[str]:
+    task_arns = ecs_client.list_tasks(
+        cluster=cluster_name, serviceName=service_name
+    ).get("taskArns", [])
+    if not task_arns:
+        return set()
+    tasks = ecs_client.describe_tasks(cluster=cluster_name, tasks=task_arns).get(
+        "tasks", []
+    )
+    addresses: set[str] = set()
+    for task in tasks:
+        for attachment in task.get("attachments", []):
+            for detail in attachment.get("details", []):
+                if detail.get("name") == "privateIPv4Address" and detail.get("value"):
+                    addresses.add(detail["value"])
+    return addresses
+
+
+def _target_group_arn_from_task_ips(
+    elbv2_client: Any,
+    load_balancer_arn: str,
+    task_ips: set[str],
+) -> Optional[str]:
+    if not task_ips:
+        return None
+    target_groups = elbv2_client.describe_target_groups(
+        LoadBalancerArn=load_balancer_arn
+    ).get("TargetGroups", [])
+    for target_group in target_groups:
+        health = elbv2_client.describe_target_health(
+            TargetGroupArn=target_group["TargetGroupArn"]
+        ).get("TargetHealthDescriptions", [])
+        for description in health:
+            target_id = (description.get("Target") or {}).get("Id")
+            if target_id in task_ips:
+                return target_group["TargetGroupArn"]
+    return None
+
+
+def resolve_express_service_target_group_arn(
+    cluster_name: str,
+    service_name: str,
+    *,
+    aws_region: str = AWS_REGION,
+    load_balancer_arn: Optional[str] = None,
+    max_wait_seconds: int = EXPRESS_TARGET_GROUP_RESOLVE_MAX_WAIT_SECONDS,
+    poll_interval_seconds: int = EXPRESS_TARGET_GROUP_RESOLVE_POLL_INTERVAL_SECONDS,
+) -> str:
+    """
+    Target group where Express most recently registered tasks.
+
+    After post-deploy scaling, this ARN can differ from the TG baked into the CDK
+    Cognito listener custom resource at deploy time. Polls until a registration
+    event appears or running tasks are visible in an Express ALB target group.
+    """
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+    elbv2_client = (
+        boto3.client("elbv2", region_name=aws_region) if load_balancer_arn else None
+    )
+    deadline = time.monotonic() + max_wait_seconds
+    attempt = 0
+    while True:
+        attempt += 1
+        services = ecs_client.describe_services(
+            cluster=cluster_name, services=[service_name]
+        ).get("services", [])
+        if not services:
+            raise ValueError(
+                f"ECS service '{service_name}' not found in cluster '{cluster_name}'."
+            )
+        service = services[0]
+        target_group_arn = _target_group_arn_from_service_events(
+            service.get("events", [])
+        )
+        if target_group_arn:
+            if attempt > 1:
+                print(
+                    f"Resolved target group for '{service_name}' "
+                    f"after {attempt} poll(s)."
+                )
+            return target_group_arn
+
+        if elbv2_client and load_balancer_arn:
+            task_ips = _task_private_ipv4_addresses(
+                ecs_client, cluster_name, service_name
+            )
+            target_group_arn = _target_group_arn_from_task_ips(
+                elbv2_client, load_balancer_arn, task_ips
+            )
+            if target_group_arn:
+                print(
+                    f"Resolved target group for '{service_name}' from running task IPs."
+                )
+                return target_group_arn
+
+        if time.monotonic() >= deadline:
+            running = service.get("runningCount", 0)
+            desired = service.get("desiredCount", 0)
+            raise ValueError(
+                f"No target group registration event found for service "
+                f"'{service_name}' after {max_wait_seconds}s "
+                f"(running {running}/{desired} tasks). "
+                "Ensure CodeBuild finished and the service scaled to at least one task."
+            )
+
+        if attempt == 1:
+            print(
+                f"Waiting for target group registration for '{service_name}' "
+                f"(up to {max_wait_seconds}s)..."
+            )
+        time.sleep(poll_interval_seconds)
+
+
+def find_express_gateway_https_listener(
+    *,
+    aws_region: str = AWS_REGION,
+) -> Dict[str, str]:
+    """Return Express-managed ALB HTTPS listener metadata."""
+    elbv2 = boto3.client("elbv2", region_name=aws_region)
+    for load_balancer in elbv2.describe_load_balancers().get("LoadBalancers", []):
+        if not load_balancer["LoadBalancerName"].startswith("ecs-express-gateway-alb"):
+            continue
+        listeners = elbv2.describe_listeners(
+            LoadBalancerArn=load_balancer["LoadBalancerArn"]
+        ).get("Listeners", [])
+        https_listener = next(
+            (listener for listener in listeners if listener.get("Port") == 443),
+            None,
+        )
+        if https_listener:
+            return {
+                "load_balancer_arn": load_balancer["LoadBalancerArn"],
+                "listener_arn": https_listener["ListenerArn"],
+                "dns_name": load_balancer["DNSName"],
+            }
+    raise ValueError(
+        "Express gateway ALB (ecs-express-gateway-alb-*) with HTTPS listener not found."
+    )
+
+
+def listener_actions_with_target_group(
+    existing_actions: List[Dict[str, Any]],
+    target_group_arn: str,
+) -> List[Dict[str, Any]]:
+    """Copy listener/rule actions, replacing the forward target group ARN."""
+    updated_actions: List[Dict[str, Any]] = []
+    for action in sorted(existing_actions, key=lambda item: item.get("Order", 0)):
+        action_copy = copy.deepcopy(action)
+        if action_copy.get("Type") == "forward":
+            action_copy["TargetGroupArn"] = target_group_arn
+            forward_config = action_copy.setdefault("ForwardConfig", {})
+            forward_config["TargetGroups"] = [
+                {"TargetGroupArn": target_group_arn, "Weight": 1}
+            ]
+        updated_actions.append(action_copy)
+    return updated_actions
+
+
+def apply_express_alb_listener_target_group_fixup(
+    *,
+    cluster_name: str,
+    main_service_name: str,
+    pi_service_name: Optional[str] = None,
+    pi_path_prefixes: Optional[List[str]] = None,
+    aws_region: str = AWS_REGION,
+) -> bool:
+    """
+    Point ALB Cognito listener actions at the target groups Express tasks use.
+
+    Express creates fresh target groups when a service scales up after deploy; the
+    CDK custom resource may still forward authenticated traffic to an empty TG.
+    """
+    ingress = find_express_gateway_https_listener(aws_region=aws_region)
+    load_balancer_arn = ingress["load_balancer_arn"]
+    main_target_group_arn = resolve_express_service_target_group_arn(
+        cluster_name,
+        main_service_name,
+        aws_region=aws_region,
+        load_balancer_arn=load_balancer_arn,
+    )
+    pi_target_group_arn = None
+    if pi_service_name:
+        try:
+            pi_target_group_arn = resolve_express_service_target_group_arn(
+                cluster_name,
+                pi_service_name,
+                aws_region=aws_region,
+                load_balancer_arn=load_balancer_arn,
+            )
+        except ValueError as exc:
+            print(f"Note: skipping Pi listener rule TG fixup: {exc}")
+
+    elbv2 = boto3.client("elbv2", region_name=aws_region)
+    listener_arn = ingress["listener_arn"]
+    listener = elbv2.describe_listeners(ListenerArns=[listener_arn])["Listeners"][0]
+    current_default = listener.get("DefaultActions", [])
+    current_forward_arn = next(
+        (
+            action.get("TargetGroupArn")
+            for action in current_default
+            if action.get("Type") == "forward"
+        ),
+        None,
+    )
+    changed = current_forward_arn != main_target_group_arn
+
+    if changed:
+        elbv2.modify_listener(
+            ListenerArn=listener_arn,
+            DefaultActions=listener_actions_with_target_group(
+                current_default, main_target_group_arn
+            ),
+        )
+        print(
+            "Updated Express ALB default listener forward target group to "
+            f"{main_target_group_arn}."
+        )
+    else:
+        print(
+            "Express ALB default listener already forwards to the active target group."
+        )
+
+    if pi_target_group_arn and pi_path_prefixes:
+        rules = elbv2.describe_rules(ListenerArn=listener_arn).get("Rules", [])
+        prefixes = {prefix.rstrip("/") for prefix in pi_path_prefixes}
+        for rule in rules:
+            if rule.get("IsDefault"):
+                continue
+            path_values = []
+            for condition in rule.get("Conditions", []):
+                if condition.get("Field") == "path-pattern":
+                    path_values.extend(condition.get("Values", []))
+            if not prefixes.intersection({value.rstrip("/") for value in path_values}):
+                continue
+            current_actions = rule.get("Actions", [])
+            current_pi_forward = next(
+                (
+                    action.get("TargetGroupArn")
+                    for action in current_actions
+                    if action.get("Type") == "forward"
+                ),
+                None,
+            )
+            if current_pi_forward == pi_target_group_arn:
+                continue
+            elbv2.modify_rule(
+                RuleArn=rule["RuleArn"],
+                Actions=listener_actions_with_target_group(
+                    current_actions, pi_target_group_arn
+                ),
+            )
+            print(
+                "Updated Pi ALB listener rule forward target group to "
+                f"{pi_target_group_arn}."
+            )
+            changed = True
+
+    return changed
+
+
+def listener_rule_has_cognito_auth(actions: List[Dict[str, Any]]) -> bool:
+    return any(action.get("Type") == "authenticate-cognito" for action in actions)
+
+
+def _listener_rule_is_cloudfront_bypass_without_cognito(
+    rule: Dict[str, Any],
+    *,
+    cloudfront_host_header: str,
+) -> bool:
+    """True for legacy forward-only host-header rules matching the CloudFront domain."""
+    if listener_rule_has_cognito_auth(rule.get("Actions", [])):
+        return False
+    host = (cloudfront_host_header or "").strip()
+    if not host or host == "cloudfront_placeholder.net":
+        return False
+    for condition in rule.get("Conditions") or []:
+        if condition.get("Field") != "host-header":
+            continue
+        values = (condition.get("HostHeaderConfig") or {}).get("Values") or []
+        if host in values:
+            return True
+    return False
+
+
+def remove_express_listener_rules_without_cognito(
+    *,
+    aws_region: str = AWS_REGION,
+    cloudfront_host_header: Optional[str] = None,
+) -> bool:
+    """
+    Delete legacy Express ALB rules that forward CloudFront host traffic without Cognito.
+
+    Only removes host-header rules whose value matches ``CLOUDFRONT_DOMAIN`` (or the
+    supplied override). ECS Express-managed ``*.ecs.*.on.aws`` host rules are left
+    intact.
+    """
+    cloudfront_host = (cloudfront_host_header or CLOUDFRONT_DOMAIN or "").strip()
+    ingress = find_express_gateway_https_listener(aws_region=aws_region)
+    elbv2 = boto3.client("elbv2", region_name=aws_region)
+    listener_arn = ingress["listener_arn"]
+    changed = False
+    for rule in elbv2.describe_rules(ListenerArn=listener_arn).get("Rules", []):
+        if rule.get("IsDefault"):
+            continue
+        if not _listener_rule_is_cloudfront_bypass_without_cognito(
+            rule, cloudfront_host_header=cloudfront_host
+        ):
+            continue
+        rule_arn = rule["RuleArn"]
+        elbv2.delete_rule(RuleArn=rule_arn)
+        print(
+            "Removed legacy Express CloudFront bypass ALB listener rule "
+            f"(host {cloudfront_host!r}): {rule_arn}"
+        )
+        changed = True
+    return changed
+
+
+def build_cognito_secret_payload(
+    user_pool_id: str,
+    client_id: str,
+    *,
+    aws_region: str = AWS_REGION,
+) -> Dict[str, str]:
+    """Build Secrets Manager JSON for SUMMARISATION_* Cognito keys."""
+    cognito_client = boto3.client("cognito-idp", region_name=aws_region)
+    client = cognito_client.describe_user_pool_client(
+        UserPoolId=user_pool_id,
+        ClientId=client_id,
+    )["UserPoolClient"]
+    client_secret = client.get("ClientSecret") or ""
+    return {
+        "SUMMARISATION_USER_POOL_ID": user_pool_id,
+        "SUMMARISATION_CLIENT_ID": client_id,
+        "SUMMARISATION_CLIENT_SECRET": client_secret,
+    }
+
+
+def cognito_secret_payload_matches(
+    existing_secret_string: str,
+    desired_payload: Dict[str, str],
+) -> bool:
+    try:
+        current = json.loads(existing_secret_string or "{}")
+    except json.JSONDecodeError:
+        return False
+    return all(current.get(key) == value for key, value in desired_payload.items())
+
+
+def apply_cognito_secret_fixup(
+    *,
+    secret_name: str,
+    user_pool_id: str,
+    client_id: str,
+    aws_region: str = AWS_REGION,
+    recycle_express_service: Optional[Dict[str, str]] = None,
+) -> bool:
+    """
+    Sync imported Secrets Manager JSON with the stack's Cognito pool and app client.
+
+    Express tasks read ``AWS_USER_POOL_ID`` / ``AWS_CLIENT_*`` from this secret.
+    When the secret predates a redeploy, values can reference a deleted user pool.
+    """
+    desired_payload = build_cognito_secret_payload(
+        user_pool_id, client_id, aws_region=aws_region
+    )
+    secrets_client = boto3.client("secretsmanager", region_name=aws_region)
+    current = secrets_client.get_secret_value(SecretId=secret_name)
+    current_string = current.get("SecretString") or ""
+    if cognito_secret_payload_matches(current_string, desired_payload):
+        print(
+            "Cognito secret already matches Cognito user pool ID "
+            "and Cognito app client ID."
+        )
+        return False
+
+    secrets_client.put_secret_value(
+        SecretId=secret_name,
+        SecretString=json.dumps(desired_payload),
+    )
+    print(
+        "Updated Cognito secret for Cognito user pool ID " "and Cognito app client ID."
+    )
+    if recycle_express_service:
+        recycle_express_gateway_tasks(
+            recycle_express_service["cluster_name"],
+            recycle_express_service["service_name"],
+            aws_region=aws_region,
+        )
+    return True
+
+
+def recycle_express_gateway_tasks(
+    cluster_name: str,
+    service_name: str,
+    *,
+    aws_region: str = AWS_REGION,
+) -> None:
+    """Stop running Express tasks so replacements pick up updated secrets/env."""
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+    task_arns = ecs_client.list_tasks(
+        cluster=cluster_name,
+        serviceName=service_name,
+    ).get("taskArns", [])
+    for task_arn in task_arns:
+        ecs_client.stop_task(
+            cluster=cluster_name,
+            task=task_arn,
+            reason="Recycle task after Cognito secret/config sync",
+        )
+    if task_arns:
+        print(
+            f"Stopped {len(task_arns)} task(s) for {service_name} to pick up Cognito updates."
+        )
+
+
+def apply_express_disable_in_app_cognito_auth(
+    cluster_name: str,
+    service_name: str,
+    *,
+    aws_region: str = AWS_REGION,
+) -> bool:
+    """
+    Set ``COGNITO_AUTH=False`` on a running Express service revision.
+
+    ALB ``authenticate-cognito`` already gates access; in-app Gradio login is redundant
+    and fails when Secrets Manager still references an old user pool.
+    """
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+    service_arn = resolve_express_gateway_service_arn(
+        cluster_name, service_name, aws_region=aws_region
+    )
+    express = ecs_client.describe_express_gateway_service(serviceArn=service_arn)[
+        "service"
+    ]
+    active_configs = express.get("activeConfigurations") or []
+    if not active_configs:
+        raise ValueError(
+            f"No active configuration for Express service '{service_name}'."
+        )
+    active = active_configs[0]
+    primary = copy.deepcopy(active.get("primaryContainer") or {})
+    environment = {
+        item["name"]: item["value"]
+        for item in primary.get("environment") or []
+        if item.get("name")
+    }
+    if environment.get("COGNITO_AUTH") == "False":
+        print(f"{service_name} already has COGNITO_AUTH=False.")
+        return False
+    environment["COGNITO_AUTH"] = "False"
+    primary["environment"] = [
+        {"name": name, "value": value} for name, value in sorted(environment.items())
+    ]
+    update_kwargs: Dict[str, Any] = {
+        "serviceArn": service_arn,
+        "primaryContainer": primary,
+    }
+    for key in (
+        "executionRoleArn",
+        "taskRoleArn",
+        "cpu",
+        "memory",
+        "healthCheckPath",
+        "networkConfiguration",
+    ):
+        value = active.get(key)
+        if value is not None:
+            update_kwargs[key] = value
+    scaling = express.get("scalingTarget") or active.get("scalingTarget")
+    if scaling is not None:
+        update_kwargs["scalingTarget"] = scaling
+    ecs_client.update_express_gateway_service(**update_kwargs)
+    print(f"Set COGNITO_AUTH=False on Express service {service_name}.")
+    return True
+
+
+def apply_cognito_secret_fixup_from_stack(
+    *,
+    stack_name: str,
+    secret_name: str,
+    cluster_name: str,
+    main_service_name: str,
+    aws_region: str = AWS_REGION,
+    recycle_tasks: bool = True,
+) -> bool:
+    """Read Cognito outputs from CloudFormation and sync the app client secret."""
+    cfn_client = boto3.client("cloudformation", region_name=aws_region)
+    stacks = cfn_client.describe_stacks(StackName=stack_name).get("Stacks", [])
+    outputs = {
+        item["OutputKey"]: item["OutputValue"]
+        for item in (stacks[0].get("Outputs") or [])
+    }
+    user_pool_id = outputs.get("CognitoPoolId")
+    client_id = outputs.get("CognitoAppClientId")
+    if not user_pool_id or not client_id:
+        raise ValueError(
+            f"Stack '{stack_name}' is missing CognitoPoolId or CognitoAppClientId outputs."
+        )
+    return apply_cognito_secret_fixup(
+        secret_name=secret_name,
+        user_pool_id=user_pool_id,
+        client_id=client_id,
+        aws_region=aws_region,
+        recycle_express_service=(
+            {"cluster_name": cluster_name, "service_name": main_service_name}
+            if recycle_tasks
+            else None
+        ),
+    )
+
+
+def get_stack_output(
+    stack_name: str,
+    output_key: str,
+    region: str,
+) -> Optional[str]:
+    """Return a CloudFormation stack output value, or None if missing."""
+    from botocore.exceptions import ClientError
+
+    cfn = boto3.client("cloudformation", region_name=region)
+    try:
+        response = cfn.describe_stacks(StackName=stack_name)
+    except ClientError:
+        return None
+    for stack in response.get("Stacks", []):
+        for output in stack.get("Outputs", []):
+            if output.get("OutputKey") == output_key:
+                return output.get("OutputValue")
+    return None
+
+
+def print_express_mode_next_steps(
+    values: Dict[str, str],
+    *,
+    stack_name: str = "SummarisationStack",
+    region: Optional[str] = None,
+) -> None:
+    """Print user-facing next steps after Express mode deploy + quickstart."""
+    from cdk_config import normalize_https_redirect_url
+    from cdk_functions import format_express_pi_public_url
+
+    aws_region = region or values.get("AWS_REGION") or AWS_REGION
+
+    main_raw = (values.get("ECS_EXPRESS_COGNITO_REDIRECT_BASE") or "").strip()
+    if not main_raw:
+        main_raw = (
+            get_stack_output(stack_name, "ExpressServiceEndpoint", aws_region) or ""
+        )
+    main_url = normalize_https_redirect_url(main_raw) if main_raw else ""
+
+    print("\nDone. Next steps:")
+    print("  - Wait 10 minutes for app deployment to finish.")
+    pi_express = values.get("ENABLE_PI_AGENT_EXPRESS_SERVICE") == "True"
+    if pi_express:
+        print(
+            "- Register a Cognito user in AWS Console, change password at the login page URL "
+            "(available in the Cognito AWS console -> App Clients -> Login pages -> View login page "
+            "and sign in at the Pi agent URL below. The main topic-modelling backend runs without "
+            "in-app login so the Pi agent can call it over Service Connect. You can disable "
+            "Cognito login by setting COGNITO_AUTH to False in the ECS task definition / "
+            "ECS service options."
+        )
+    else:
+        print(
+            "  - If you have enabled Cognito login in the app, register a new user "
+            "to your Cognito user pool in AWS Console and complete sign up with the app "
+            "client login. If you do not want Cognito login, then set COGNITO_AUTH to "
+            "False in the ECS task definition / ECS service options."
+        )
+    if main_url:
+        print(f"  - The main topic modelling app can be accessed at {main_url}")
+    else:
+        print(
+            "  - The main topic modelling app URL: see ExpressServiceEndpoint stack output"
+        )
+
+    if values.get("ENABLE_PI_AGENT_EXPRESS_SERVICE") == "True":
+        pi_raw = get_stack_output(stack_name, "PiExpressEndpoint", aws_region) or ""
+        pi_url = (
+            format_express_pi_public_url(normalize_https_redirect_url(pi_raw))
+            if pi_raw
+            else ""
+        )
+        if pi_url:
+            print(f"  - The Pi agent app can be accessed at {pi_url}")
+        else:
+            print("  - The Pi agent app URL: see PiExpressEndpoint stack output")
+
+
+def _s3_object_exists(s3_client, bucket: str, key: str) -> bool:
+    from botocore.exceptions import ClientError
+
+    try:
+        s3_client.head_object(Bucket=bucket, Key=key)
+        return True
+    except ClientError as exc:
+        code = exc.response.get("Error", {}).get("Code", "")
+        if code in ("404", "NoSuchKey", "NotFound"):
+            return False
+        raise
+
+
+def seed_headless_batch_s3_layout(
+    output_bucket: str,
+    *,
+    input_prefix: str = "input/",
+    env_prefix: str = "input/config/",
+    example_env_local_path: str,
+    example_env_basename: str = "example_headless_env_file.env",
+    aws_region: str = AWS_REGION,
+    log_bucket: str = "",
+    default_params_key: str = "general-config/app_defaults.env",
+    app_defaults_local_path: str = "",
+    s3_outputs_bucket_name: str = "",
+    env_overrides: Optional[Dict[str, str]] = None,
+) -> None:
+    """
+    Ensure headless batch prefixes and example job .env exist on the output bucket.
+
+    When ``log_bucket`` is set, also ensure durable ``app_defaults.env`` exists on
+    the log/config bucket (so it is not deleted by output-bucket lifecycle rules).
+
+    Idempotent: existing keys are left unchanged (safe to run from quickstart).
+    """
+    if not output_bucket:
+        print("Skipping headless S3 layout seed: output bucket name is empty.")
+        return
+
+    input_prefix_norm = (
+        input_prefix if input_prefix.endswith("/") else f"{input_prefix}/"
+    )
+    env_prefix_norm = env_prefix if env_prefix.endswith("/") else f"{env_prefix}/"
+    if not env_prefix_norm.startswith(input_prefix_norm):
+        env_prefix_norm = f"{input_prefix_norm}{env_prefix_norm.lstrip('/')}"
+        if not env_prefix_norm.endswith("/"):
+            env_prefix_norm += "/"
+
+    s3_client = boto3.client("s3", region_name=aws_region)
+    markers = (
+        input_prefix_norm,
+        env_prefix_norm,
+    )
+    for key in markers:
+        if _s3_object_exists(s3_client, output_bucket, key):
+            print(f"S3 prefix marker already present: s3://{output_bucket}/{key}")
+            continue
+        s3_client.put_object(Bucket=output_bucket, Key=key, Body=b"")
+        print(f"Created S3 prefix marker: s3://{output_bucket}/{key}")
+
+    example_key = f"{env_prefix_norm}{example_env_basename}"
+    if _s3_object_exists(s3_client, output_bucket, example_key):
+        print(f"Example job .env already present: s3://{output_bucket}/{example_key}")
+    elif not os.path.isfile(example_env_local_path):
+        print(f"Skipping example job .env upload: {example_env_local_path} not found.")
+    else:
+        with open(example_env_local_path, "rb") as handle:
+            s3_client.put_object(
+                Bucket=output_bucket, Key=example_key, Body=handle.read()
+            )
+        print(f"Uploaded example job .env to s3://{output_bucket}/{example_key}")
+
+    if not log_bucket:
+        return
+
+    defaults_key = (default_params_key or "general-config/app_defaults.env").lstrip("/")
+    if _s3_object_exists(s3_client, log_bucket, defaults_key):
+        print(f"app_defaults.env already present: s3://{log_bucket}/{defaults_key}")
+        return
+
+    defaults_path = app_defaults_local_path
+    if not defaults_path:
+        defaults_path = os.path.join(
+            os.path.dirname(__file__),
+            "config",
+            "headless_s3_seed",
+            "general-config",
+            "app_defaults.env",
+        )
+
+    # Prefer rendered content (fills S3_OUTPUTS_BUCKET) when seed helpers are available.
+    body: Optional[bytes] = None
+    try:
+        from cdk_functions import build_headless_app_defaults_env_content
+
+        seed_dir = os.path.join(os.path.dirname(__file__), "config", "headless_s3_seed")
+        if env_overrides is None:
+            try:
+                from cdk_config import (
+                    BEDROCK_GUARDRAIL_IDENTIFIER,
+                    BEDROCK_GUARDRAIL_TRACE,
+                    BEDROCK_GUARDRAIL_VERSION,
+                    ENABLE_BEDROCK_GUARDRAILS,
+                )
+                from cdk_functions import bedrock_guardrail_env_overrides_for_defaults
+
+                env_overrides = bedrock_guardrail_env_overrides_for_defaults(
+                    ENABLE_BEDROCK_GUARDRAILS,
+                    BEDROCK_GUARDRAIL_IDENTIFIER,
+                    BEDROCK_GUARDRAIL_VERSION,
+                    BEDROCK_GUARDRAIL_TRACE,
+                )
+            except Exception:
+                env_overrides = {}
+
+        rendered = build_headless_app_defaults_env_content(
+            seed_dir,
+            s3_outputs_bucket_name=s3_outputs_bucket_name or output_bucket,
+            env_overrides=env_overrides or None,
+        )
+        body = rendered.encode("utf-8")
+    except Exception as exc:
+        print(f"Warning: could not render app_defaults.env ({exc}); using local file.")
+
+    if body is None:
+        if not os.path.isfile(defaults_path):
+            print(f"Skipping app_defaults.env upload: {defaults_path} not found.")
+            return
+        with open(defaults_path, "rb") as handle:
+            body = handle.read()
+
+    s3_client.put_object(Bucket=log_bucket, Key=defaults_key, Body=body)
+    print(f"Uploaded app_defaults.env to s3://{log_bucket}/{defaults_key}")
+
+
+def print_headless_deployment_next_steps(
+    values: Dict[str, str],
+    *,
+    stack_name: str = "SummarisationStack",
+    region: Optional[str] = None,
+) -> None:
+    """Print user-facing next steps after headless deploy + quickstart."""
+    aws_region = region or values.get("AWS_REGION") or AWS_REGION
+    output_bucket = (values.get("S3_OUTPUT_BUCKET_NAME") or "").strip()
+    log_bucket = (values.get("S3_LOG_CONFIG_BUCKET_NAME") or "").strip()
+    input_prefix = (values.get("S3_BATCH_INPUT_PREFIX") or "input/").strip("/")
+    config_prefix = (values.get("S3_BATCH_ENV_PREFIX") or "input/config/").strip("/")
+    defaults_key = (
+        (values.get("S3_BATCH_DEFAULT_PARAMS_KEY") or "general-config/app_defaults.env")
+        .strip()
+        .lstrip("/")
+    )
+
+    lambda_name = (values.get("S3_BATCH_LAMBDA_FUNCTION_NAME") or "").strip()
+    if not lambda_name:
+        lambda_name = (
+            get_stack_output(stack_name, "BatchEcsTriggerLambdaName", aws_region) or ""
+        ).strip()
+    if not lambda_name:
+        prefix = (values.get("CDK_PREFIX") or "").strip()
+        lambda_name = f"{prefix}S3BatchEcsTrigger" if prefix else "S3BatchEcsTrigger"
+
+    input_uri = (
+        f"s3://{output_bucket}/{input_prefix}/"
+        if output_bucket
+        else f"<output-bucket>/{input_prefix}/"
+    )
+    config_uri = (
+        f"s3://{output_bucket}/{config_prefix}/"
+        if output_bucket
+        else f"<output-bucket>/{config_prefix}/"
+    )
+    output_uri = (
+        f"s3://{output_bucket}/output/<session-folder>/"
+        if output_bucket
+        else "<output-bucket>/output/<session-folder>/"
+    )
+    defaults_uri = (
+        f"s3://{log_bucket}/{defaults_key}"
+        if log_bucket
+        else f"<log-bucket>/{defaults_key}"
+    )
+    example_name = "example_headless_env_file.env"
+
+    print("\nDone. Next steps:")
+    print(
+        f"  - Upload a consultation spreadsheet (.xlsx) to {input_uri}. "
+        "You can use dummy_consultation_response.xlsx as a placeholder filename "
+        "in the example job .env below."
+    )
+    print(
+        f"  - Create a job .env file for submitting a task to {config_uri}. "
+        f"You can copy the example at cdk/config/headless_s3_seed/input/config/{example_name} "
+        f"(also seeded at {config_uri}{example_name}) and adjust DIRECT_MODE_INPUT_FILE "
+        "and DIRECT_MODE_TEXT_COLUMN. Further DIRECT_MODE_* variables are documented in "
+        "tools/config.py and cli_topics.py."
+    )
+    print(f"  - Upload your job .env file to {config_uri}")
+    print(
+        f"  - Durable batch defaults (app_defaults.env) live at {defaults_uri} "
+        "on the log/config bucket (not deleted by the output bucket lifecycle rule)."
+    )
+    print(
+        f"  - AWS Lambda function {lambda_name} will start an ECS task to run "
+        "topic modelling according to your job .env (RUN_DIRECT_MODE=1)."
+    )
+    print(
+        f"  - Outputs are written to {output_uri} when SAVE_OUTPUTS_TO_S3=True "
+        "in your job .env (see the example file)."
+    )
+    log_group = (values.get("ECS_LOG_GROUP_NAME") or "").strip()
+    if log_group:
+        print(
+            f"  - Batch task logs: CloudWatch log group {log_group} "
+            "(streams appear once the container starts)."
+        )
+
+
+def print_headless_output_notification_steps(values: Dict[str, str]) -> None:
+    """Print follow-on steps for S3 output alarms, SNS, and IAM reader user."""
+    email = (values.get("HEADLESS_OUTPUT_NOTIFY_EMAIL") or "").strip()
+    iam_user = (values.get("HEADLESS_OUTPUT_IAM_USER_NAME") or "").strip()
+    output_bucket = (values.get("S3_OUTPUT_BUCKET_NAME") or "").strip()
+    output_prefix = (values.get("HEADLESS_OUTPUT_S3_PREFIX") or "output/").strip()
+    alarm_name = (values.get("HEADLESS_OUTPUT_ALARM_NAME") or "").strip()
+    secret_name = (values.get("HEADLESS_OUTPUT_IAM_SECRET_NAME") or "").strip()
+
+    print("\nHeadless output notifications:")
+    if email:
+        print(
+            f"  - Confirm the SNS email subscription sent to {email} "
+            "(check spam; status shows Pending until confirmed)."
+        )
+    if output_bucket:
+        print(
+            f"  - CloudWatch alarm fires when objects are uploaded under "
+            f"s3://{output_bucket}/{output_prefix.rstrip('/')}/"
+        )
+    if alarm_name:
+        print(f"  - Alarm name: {alarm_name}")
+    if iam_user:
+        print(
+            f"  - IAM user {iam_user} can list/get/put/delete objects in the "
+            f"output bucket for programmatic result download."
+        )
+    if secret_name:
+        print(
+            "  - If an access key was created, credentials are stored in "
+            "the relevantSecrets Manager secret."
+        )
+
+
+def provision_headless_output_reader_access_key(
+    values: Dict[str, str],
+    *,
+    region: Optional[str] = None,
+) -> Optional[str]:
+    """
+    Create an IAM access key for the headless output reader user.
+
+    Stores JSON credentials in Secrets Manager when HEADLESS_OUTPUT_IAM_SECRET_NAME
+    is set in cdk_config.env.
+    """
+    from botocore.exceptions import ClientError
+
+    iam_user = (values.get("HEADLESS_OUTPUT_IAM_USER_NAME") or "").strip()
+    if not iam_user:
+        print("Warning: HEADLESS_OUTPUT_IAM_USER_NAME not set; skipping access key.")
+        return None
+
+    aws_region = region or values.get("AWS_REGION") or AWS_REGION
+    iam_client = boto3.client("iam", region_name=aws_region)
+    secret_name = (values.get("HEADLESS_OUTPUT_IAM_SECRET_NAME") or "").strip()
+
+    try:
+        response = iam_client.create_access_key(UserName=iam_user)
+    except ClientError as exc:
+        print(f"Could not create IAM access key for {iam_user}: {exc}")
+        return None
+
+    access_key = response["AccessKey"]
+    payload = json.dumps(
+        {
+            "aws_access_key_id": access_key["AccessKeyId"],
+            "aws_secret_access_key": access_key["SecretAccessKey"],
+        }
+    )
+
+    if secret_name:
+        sm_client = boto3.client("secretsmanager", region_name=aws_region)
+        try:
+            sm_client.create_secret(Name=secret_name, SecretString=payload)
+            print("Stored output-reader credentials in Secrets Manager secret")
+        except ClientError as exc:
+            if exc.response["Error"]["Code"] == "ResourceExistsException":
+                sm_client.put_secret_value(SecretId=secret_name, SecretString=payload)
+                print("Updated output-reader credentials in Secrets Manager secret")
+            else:
+                print(f"Warning: could not store credentials in Secrets Manager: {exc}")
+                print("IAM access key created (view in IAM console if needed):")
+    else:
+        print("IAM access key created (view in IAM console if needed):")
+
+    return access_key["AccessKeyId"]

cdk/check_resources.py

@@ -0,0 +1,583 @@
+import json
+import os
+from typing import Dict, List
+
+from cdk_config import (  # Import necessary config
+    ALB_NAME,
+    AWS_REGION,
+    CDK_CONFIG_PATH,
+    CDK_FOLDER,
+    CODEBUILD_PROJECT_NAME,
+    CODEBUILD_ROLE_NAME,
+    COGNITO_USER_POOL_CLIENT_NAME,
+    COGNITO_USER_POOL_CLIENT_SECRET_NAME,
+    COGNITO_USER_POOL_DOMAIN_PREFIX,
+    COGNITO_USER_POOL_NAME,
+    CONTEXT_FILE,
+    ECR_CDK_REPO_NAME,
+    ECR_PI_REPO_NAME,
+    ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_NAMES_TO_LOOKUP,
+    ECS_TASK_EXECUTION_ROLE_NAME,
+    ECS_TASK_ROLE_NAME,
+    ENABLE_ECS_SERVICE_CONNECT,
+    ENABLE_HEADLESS_DEPLOYMENT,
+    ENABLE_PI_AGENT_ECS_SERVICE,
+    ENABLE_S3_BATCH_ECS_TRIGGER,
+    EXISTING_IGW_ID,
+    PRIVATE_SUBNET_AVAILABILITY_ZONES,
+    PRIVATE_SUBNET_CIDR_BLOCKS,
+    PRIVATE_SUBNETS_TO_USE,
+    PUBLIC_SUBNET_AVAILABILITY_ZONES,
+    PUBLIC_SUBNET_CIDR_BLOCKS,
+    PUBLIC_SUBNETS_TO_USE,
+    S3_LOG_CONFIG_BUCKET_NAME,
+    S3_OUTPUT_BUCKET_NAME,
+    USE_ECS_EXPRESS_MODE,
+    VPC_NAME,
+    WEB_ACL_NAME,
+)
+from cdk_functions import (  # Import your check functions (assuming they use Boto3)
+    _get_existing_subnets_in_vpc,
+    audit_public_subnet_internet_connectivity,
+    check_alb_exists,
+    check_codebuild_project_exists,
+    check_ecr_repo_exists,
+    check_for_existing_role,
+    check_for_existing_user_pool,
+    check_for_existing_user_pool_client,
+    check_for_secret,
+    check_subnet_exists_by_name,
+    check_web_acl_exists,
+    get_secret_kms_key_arn,
+    get_security_group_id_by_name,
+    get_vpc_id_by_name,
+    list_existing_vpc_endpoint_service_names,
+    resolve_cognito_domain_prefix_availability,
+    resolve_s3_bucket_availability,
+    validate_subnet_creation_parameters,
+    # Add other check functions as needed
+)
+
+cdk_folder = CDK_FOLDER  # <FULL_PATH_TO_CDK_FOLDER_HERE>
+
+# Full path needed to find config file
+os.environ["CDK_CONFIG_PATH"] = cdk_folder + CDK_CONFIG_PATH
+
+
+# --- Helper to parse environment variables into lists ---
+def _get_env_list(env_var_name: str) -> List[str]:
+    """Parses a comma-separated environment variable into a list of strings."""
+    value = env_var_name[1:-1].strip().replace('"', "").replace("'", "")
+    if not value:
+        return []
+    # Split by comma and filter out any empty strings that might result from extra commas
+    return [s.strip() for s in value.split(",") if s.strip()]
+
+
+if PUBLIC_SUBNETS_TO_USE and not isinstance(PUBLIC_SUBNETS_TO_USE, list):
+    PUBLIC_SUBNETS_TO_USE = _get_env_list(PUBLIC_SUBNETS_TO_USE)
+if PRIVATE_SUBNETS_TO_USE and not isinstance(PRIVATE_SUBNETS_TO_USE, list):
+    PRIVATE_SUBNETS_TO_USE = _get_env_list(PRIVATE_SUBNETS_TO_USE)
+if PUBLIC_SUBNET_CIDR_BLOCKS and not isinstance(PUBLIC_SUBNET_CIDR_BLOCKS, list):
+    PUBLIC_SUBNET_CIDR_BLOCKS = _get_env_list(PUBLIC_SUBNET_CIDR_BLOCKS)
+if PUBLIC_SUBNET_AVAILABILITY_ZONES and not isinstance(
+    PUBLIC_SUBNET_AVAILABILITY_ZONES, list
+):
+    PUBLIC_SUBNET_AVAILABILITY_ZONES = _get_env_list(PUBLIC_SUBNET_AVAILABILITY_ZONES)
+if PRIVATE_SUBNET_CIDR_BLOCKS and not isinstance(PRIVATE_SUBNET_CIDR_BLOCKS, list):
+    PRIVATE_SUBNET_CIDR_BLOCKS = _get_env_list(PRIVATE_SUBNET_CIDR_BLOCKS)
+if PRIVATE_SUBNET_AVAILABILITY_ZONES and not isinstance(
+    PRIVATE_SUBNET_AVAILABILITY_ZONES, list
+):
+    PRIVATE_SUBNET_AVAILABILITY_ZONES = _get_env_list(PRIVATE_SUBNET_AVAILABILITY_ZONES)
+
+# Check for the existence of elements in your AWS environment to see if it's necessary to create new versions of the same
+
+
+def check_and_set_context():
+    context_data = {}
+
+    # --- Find the VPC ID first ---
+    if VPC_NAME:
+        print("VPC_NAME:", VPC_NAME)
+        vpc_lookup = get_vpc_id_by_name(VPC_NAME)
+        if not vpc_lookup:
+            raise RuntimeError(
+                f"Required VPC '{VPC_NAME}' not found. Cannot proceed with subnet checks."
+            )
+        vpc_id, nat_gateways, vpc_cidr_block, vpc_cidr_blocks = vpc_lookup
+
+        # If you expect only one, or one per AZ and you're creating one per AZ in CDK:
+        if nat_gateways:
+            # For simplicity, let's just check if *any* NAT exists in the VPC
+            # A more robust check would match by subnet, AZ, or a specific tag.
+            context_data["exists:NatGateway"] = True
+            context_data["id:NatGateway"] = nat_gateways[0][
+                "NatGatewayId"
+            ]  # Store the ID of the first one found
+        else:
+            context_data["exists:NatGateway"] = False
+            context_data["id:NatGateway"] = None
+
+        context_data["vpc_id"] = vpc_id  # Store VPC ID in context
+        if vpc_cidr_block:
+            context_data["vpc_cidr_block"] = vpc_cidr_block
+        if vpc_cidr_blocks:
+            context_data["vpc_cidr_blocks"] = vpc_cidr_blocks
+
+        existing_endpoint_services = sorted(
+            list_existing_vpc_endpoint_service_names(vpc_id, region_name=AWS_REGION)
+        )
+        if existing_endpoint_services:
+            context_data["existing_vpc_endpoint_service_names"] = (
+                existing_endpoint_services
+            )
+            print(
+                "Existing VPC endpoints in target VPC (will be skipped on deploy): "
+                + ", ".join(existing_endpoint_services)
+            )
+
+        # SUBNET CHECKS
+        all_proposed_subnets_data: List[Dict[str, str]] = []
+
+        # Flag to indicate if full validation mode (with CIDR/AZs) is active
+        full_validation_mode = False
+
+        # Determine if full validation mode is possible/desired
+        # It's 'desired' if CIDR/AZs are provided, and their lengths match the name lists.
+        public_ready_for_full_validation = (
+            len(PUBLIC_SUBNETS_TO_USE) > 0
+            and len(PUBLIC_SUBNET_CIDR_BLOCKS) == len(PUBLIC_SUBNETS_TO_USE)
+            and len(PUBLIC_SUBNET_AVAILABILITY_ZONES) == len(PUBLIC_SUBNETS_TO_USE)
+        )
+        private_ready_for_full_validation = (
+            len(PRIVATE_SUBNETS_TO_USE) > 0
+            and len(PRIVATE_SUBNET_CIDR_BLOCKS) == len(PRIVATE_SUBNETS_TO_USE)
+            and len(PRIVATE_SUBNET_AVAILABILITY_ZONES) == len(PRIVATE_SUBNETS_TO_USE)
+        )
+
+        # Activate full validation if *any* type of subnet (public or private) has its full details provided.
+        # You might adjust this logic if you require ALL subnet types to have CIDRs, or NONE.
+        if public_ready_for_full_validation or private_ready_for_full_validation:
+            full_validation_mode = True
+
+            # If some are ready but others aren't, print a warning or raise an error based on your strictness
+            if (
+                public_ready_for_full_validation
+                and not private_ready_for_full_validation
+                and PRIVATE_SUBNETS_TO_USE
+            ):
+                print(
+                    "Warning: Public subnets have CIDRs/AZs, but private subnets do not. Only public will be fully validated/created with CIDRs."
+                )
+            if (
+                private_ready_for_full_validation
+                and not public_ready_for_full_validation
+                and PUBLIC_SUBNETS_TO_USE
+            ):
+                print(
+                    "Warning: Private subnets have CIDRs/AZs, but public subnets do not. Only private will be fully validated/created with CIDRs."
+                )
+
+            # Prepare data for validate_subnet_creation_parameters for all subnets that have full details
+            if public_ready_for_full_validation:
+                for i, name in enumerate(PUBLIC_SUBNETS_TO_USE):
+                    all_proposed_subnets_data.append(
+                        {
+                            "name": name,
+                            "cidr": PUBLIC_SUBNET_CIDR_BLOCKS[i],
+                            "az": PUBLIC_SUBNET_AVAILABILITY_ZONES[i],
+                        }
+                    )
+            if private_ready_for_full_validation:
+                for i, name in enumerate(PRIVATE_SUBNETS_TO_USE):
+                    all_proposed_subnets_data.append(
+                        {
+                            "name": name,
+                            "cidr": PRIVATE_SUBNET_CIDR_BLOCKS[i],
+                            "az": PRIVATE_SUBNET_AVAILABILITY_ZONES[i],
+                        }
+                    )
+
+        print(f"Target VPC ID for Boto3 lookup: {vpc_id}")
+
+        # Fetch all existing subnets in the target VPC once to avoid repeated API calls
+        try:
+            existing_aws_subnets = _get_existing_subnets_in_vpc(vpc_id)
+        except Exception as e:
+            print(f"Failed to fetch existing VPC subnets. Aborting. Error: {e}")
+            raise SystemExit(1)  # Exit immediately if we can't get baseline data
+
+        print("\n--- Running Name-Only Subnet Existence Check Mode ---")
+        # Fallback: check only by name using the existing data
+        checked_public_subnets = {}
+        if PUBLIC_SUBNETS_TO_USE:
+            for subnet_name in PUBLIC_SUBNETS_TO_USE:
+                print("subnet_name:", subnet_name)
+                exists, subnet_id = check_subnet_exists_by_name(
+                    subnet_name, existing_aws_subnets
+                )
+                checked_public_subnets[subnet_name] = {
+                    "exists": exists,
+                    "id": subnet_id,
+                    "az": (
+                        existing_aws_subnets["by_name"].get(subnet_name, {}).get("az")
+                        if exists
+                        else None
+                    ),
+                    "route_table_id": (
+                        existing_aws_subnets["by_name"]
+                        .get(subnet_name, {})
+                        .get("route_table_id")
+                        if exists
+                        else None
+                    ),
+                }
+
+                # If the subnet exists, remove it from the proposed subnets list
+                if checked_public_subnets[subnet_name]["exists"] is True:
+                    all_proposed_subnets_data = [
+                        subnet
+                        for subnet in all_proposed_subnets_data
+                        if subnet["name"] != subnet_name
+                    ]
+
+        context_data["checked_public_subnets"] = checked_public_subnets
+
+        checked_private_subnets = {}
+        if PRIVATE_SUBNETS_TO_USE:
+            for subnet_name in PRIVATE_SUBNETS_TO_USE:
+                print("subnet_name:", subnet_name)
+                exists, subnet_id = check_subnet_exists_by_name(
+                    subnet_name, existing_aws_subnets
+                )
+                checked_private_subnets[subnet_name] = {
+                    "exists": exists,
+                    "id": subnet_id,
+                    "az": (
+                        existing_aws_subnets["by_name"].get(subnet_name, {}).get("az")
+                        if exists
+                        else None
+                    ),
+                    "route_table_id": (
+                        existing_aws_subnets["by_name"]
+                        .get(subnet_name, {})
+                        .get("route_table_id")
+                        if exists
+                        else None
+                    ),
+                }
+
+                # If the subnet exists, remove it from the proposed subnets list
+                if checked_private_subnets[subnet_name]["exists"] is True:
+                    all_proposed_subnets_data = [
+                        subnet
+                        for subnet in all_proposed_subnets_data
+                        if subnet["name"] != subnet_name
+                    ]
+
+        context_data["checked_private_subnets"] = checked_private_subnets
+
+        # Internet Gateway + public subnet default routes (legacy ALB / NAT public subnets)
+        if PUBLIC_SUBNETS_TO_USE and vpc_id:
+            public_entries_for_igw_audit = []
+            for subnet_name in PUBLIC_SUBNETS_TO_USE:
+                info = checked_public_subnets.get(subnet_name, {})
+                if not info.get("exists"):
+                    continue
+                public_entries_for_igw_audit.append(
+                    {
+                        "name": subnet_name,
+                        "subnet_id": info.get("id"),
+                        "route_table_id": info.get("route_table_id"),
+                    }
+                )
+            if public_entries_for_igw_audit or EXISTING_IGW_ID:
+                print("\n--- Auditing Internet Gateway and public subnet routes ---")
+                try:
+                    igw_audit = audit_public_subnet_internet_connectivity(
+                        vpc_id,
+                        EXISTING_IGW_ID,
+                        public_entries_for_igw_audit,
+                    )
+                    context_data["internet_gateway_id"] = igw_audit[
+                        "internet_gateway_id"
+                    ]
+                    context_data["internet_gateway_needs_vpc_attachment"] = igw_audit[
+                        "internet_gateway_needs_vpc_attachment"
+                    ]
+                    context_data["public_subnets_needing_igw_route"] = igw_audit[
+                        "public_subnets_needing_igw_route"
+                    ]
+                    needing = igw_audit["public_subnets_needing_igw_route"]
+                    if igw_audit["internet_gateway_needs_vpc_attachment"]:
+                        print(
+                            f"CDK will attach IGW '{igw_audit['internet_gateway_id']}' "
+                            f"to VPC '{vpc_id}' on deploy."
+                        )
+                    if needing:
+                        print(
+                            f"CDK will add default internet routes on deploy for: "
+                            f"{', '.join(n['name'] for n in needing)}"
+                        )
+                    else:
+                        print(
+                            "All audited public subnets already have 0.0.0.0/0 -> IGW routes."
+                        )
+                except ValueError as e:
+                    print(
+                        f"\nFATAL ERROR: Internet Gateway / public route audit failed: {e}\n"
+                    )
+                    raise SystemExit(1) from e
+
+        print("\nName-only existence subnet check complete.\n")
+
+        if full_validation_mode:
+            print(
+                "\n--- Running in Full Subnet Validation Mode (CIDR/AZs provided) ---"
+            )
+            try:
+                validate_subnet_creation_parameters(
+                    vpc_id, all_proposed_subnets_data, existing_aws_subnets
+                )
+                print("\nPre-synth validation successful. Proceeding with CDK synth.\n")
+
+                # Populate context_data for downstream CDK construct creation.
+                # Skip subnets that already exist in AWS (imported in the stack).
+                context_data["public_subnets_to_create"] = []
+                if public_ready_for_full_validation:
+                    for i, name in enumerate(PUBLIC_SUBNETS_TO_USE):
+                        if checked_public_subnets.get(name, {}).get("exists"):
+                            continue
+                        context_data["public_subnets_to_create"].append(
+                            {
+                                "name": name,
+                                "cidr": PUBLIC_SUBNET_CIDR_BLOCKS[i],
+                                "az": PUBLIC_SUBNET_AVAILABILITY_ZONES[i],
+                                "is_public": True,
+                            }
+                        )
+                context_data["private_subnets_to_create"] = []
+                if private_ready_for_full_validation:
+                    for i, name in enumerate(PRIVATE_SUBNETS_TO_USE):
+                        if checked_private_subnets.get(name, {}).get("exists"):
+                            continue
+                        context_data["private_subnets_to_create"].append(
+                            {
+                                "name": name,
+                                "cidr": PRIVATE_SUBNET_CIDR_BLOCKS[i],
+                                "az": PRIVATE_SUBNET_AVAILABILITY_ZONES[i],
+                                "is_public": False,
+                            }
+                        )
+
+            except (ValueError, Exception) as e:
+                print(f"\nFATAL ERROR: Subnet parameter validation failed: {e}\n")
+                raise SystemExit(1)  # Exit if validation fails
+
+    # Example checks and setting context values
+    # IAM Roles
+    role_name = CODEBUILD_ROLE_NAME
+    exists, role_arn, _ = check_for_existing_role(role_name)
+    context_data[f"exists:{role_name}"] = exists
+    if exists:
+        context_data[f"arn:{role_name}"] = role_arn
+
+    role_name = ECS_TASK_ROLE_NAME
+    exists, role_arn, _ = check_for_existing_role(role_name)
+    context_data[f"exists:{role_name}"] = exists
+    if exists:
+        context_data[f"arn:{role_name}"] = role_arn
+
+    role_name = ECS_TASK_EXECUTION_ROLE_NAME
+    exists, role_arn, _ = check_for_existing_role(role_name)
+    context_data[f"exists:{role_name}"] = exists
+    if exists:
+        context_data[f"arn:{role_name}"] = role_arn
+
+    # S3 Buckets
+    def _record_s3_bucket_context(name: str) -> None:
+        status, _ = resolve_s3_bucket_availability(name)
+        context_data[f"exists:{name}"] = status == "owned"
+        context_data[f"globally_taken:{name}"] = status == "globally_taken"
+
+    bucket_name = S3_LOG_CONFIG_BUCKET_NAME
+    _record_s3_bucket_context(bucket_name)
+
+    output_bucket_name = S3_OUTPUT_BUCKET_NAME
+    _record_s3_bucket_context(output_bucket_name)
+
+    # ECR Repositories
+    for repo_name in (ECR_CDK_REPO_NAME, ECR_PI_REPO_NAME):
+        exists, _ = check_ecr_repo_exists(repo_name)
+        context_data[f"exists:{repo_name}"] = exists
+
+    # CodeBuild Project
+    project_name = CODEBUILD_PROJECT_NAME
+    exists, project_arn, service_role_arn = check_codebuild_project_exists(project_name)
+    context_data[f"exists:{project_name}"] = exists
+    if exists:
+        context_data[f"arn:{project_name}"] = project_arn
+        if service_role_arn:
+            context_data[f"service_role_arn:{project_name}"] = service_role_arn
+
+    # ALB (by name lookup) — skipped when Express Mode will provision its own ALB
+    alb_name = ALB_NAME[-32:] if len(ALB_NAME) > 32 else ALB_NAME
+    if USE_ECS_EXPRESS_MODE == "True":
+        context_data[f"exists:{alb_name}"] = False
+        print(
+            "USE_ECS_EXPRESS_MODE=True: skipping ALB pre-check (Express provisions ALB)."
+        )
+    elif ENABLE_HEADLESS_DEPLOYMENT == "True":
+        context_data[f"exists:{alb_name}"] = False
+        print(
+            "ENABLE_HEADLESS_DEPLOYMENT=True: skipping ALB pre-check (no web ingress)."
+        )
+    if ENABLE_HEADLESS_DEPLOYMENT == "True":
+        print(
+            "ENABLE_HEADLESS_DEPLOYMENT=True: requires ENABLE_S3_BATCH_ECS_TRIGGER=True "
+            "and USE_ECS_EXPRESS_MODE=False."
+        )
+    elif ENABLE_S3_BATCH_ECS_TRIGGER == "True":
+        print(
+            "ENABLE_S3_BATCH_ECS_TRIGGER=True: requires legacy Fargate (USE_ECS_EXPRESS_MODE=False)."
+        )
+    if ENABLE_PI_AGENT_ECS_SERVICE == "True":
+        print(
+            "ENABLE_PI_AGENT_ECS_SERVICE=True: requires legacy Fargate, Service Connect, "
+            "and PI_ALB_ROUTING (default path=/pi on shared ALB; host mode needs PI_ALB_HOST_HEADER)."
+        )
+    elif ENABLE_HEADLESS_DEPLOYMENT == "True":
+        print(
+            "ENABLE_HEADLESS_DEPLOYMENT=True: legacy Fargate task definition + "
+            "S3 batch Lambda only (no ALB pre-check)."
+        )
+    else:
+        exists, alb_object = check_alb_exists(alb_name, region_name=AWS_REGION)
+        context_data[f"exists:{alb_name}"] = exists
+        if exists:
+            print("alb_object:", alb_object)
+            context_data[f"arn:{alb_name}"] = alb_object["LoadBalancerArn"]
+            context_data[f"dns:{alb_name}"] = alb_object["DNSName"]
+            context_data[f"canonical_hosted_zone_id:{alb_name}"] = alb_object[
+                "CanonicalHostedZoneId"
+            ]
+            if alb_object.get("SecurityGroups"):
+                context_data[f"security_group_id:{alb_name}"] = alb_object[
+                    "SecurityGroups"
+                ][0]
+
+    # Cognito (web login only; headless batch mode has no Gradio/ALB ingress)
+    if ENABLE_HEADLESS_DEPLOYMENT != "True":
+        domain_prefix = (COGNITO_USER_POOL_DOMAIN_PREFIX or "").strip().lower()
+        if domain_prefix:
+            availability = resolve_cognito_domain_prefix_availability(
+                domain_prefix, region_name=AWS_REGION
+            )
+            context_data[f"cognito_domain_taken:{domain_prefix}"] = (
+                availability == "taken"
+            )
+
+        user_pool_name = COGNITO_USER_POOL_NAME
+        exists, user_pool_id, _ = check_for_existing_user_pool(user_pool_name)
+        context_data[f"exists:{user_pool_name}"] = exists
+        if exists:
+            context_data[f"id:{user_pool_name}"] = user_pool_id
+
+        # Cognito User Pool Client (by name and pool ID) - requires User Pool ID from check
+        if user_pool_id:
+            user_pool_id_for_client_check = user_pool_id  # context_data.get(f"id:{user_pool_name}") # Use ID from context
+            user_pool_client_name = COGNITO_USER_POOL_CLIENT_NAME
+            if user_pool_id_for_client_check:
+                exists, client_id, _ = check_for_existing_user_pool_client(
+                    user_pool_client_name, user_pool_id_for_client_check
+                )
+                context_data[f"exists:{user_pool_client_name}"] = exists
+                if exists:
+                    context_data[f"id:{user_pool_client_name}"] = client_id
+                else:
+                    print(
+                        f"User pool '{user_pool_name}' exists but app client "
+                        f"'{user_pool_client_name}' does not; CDK will create a new client."
+                    )
+
+        # Secrets Manager Secret (by name)
+        secret_name = COGNITO_USER_POOL_CLIENT_SECRET_NAME
+        exists, secret_response = check_for_secret(secret_name)
+        context_data[f"exists:{secret_name}"] = exists
+        if exists:
+            secret_arn = (
+                secret_response.get("ARN")
+                if isinstance(secret_response, dict)
+                else None
+            )
+            if secret_arn:
+                context_data[f"arn:{secret_name}"] = secret_arn
+                print("Cognito secret ARN recorded for IAM grants.")
+                secret_kms_key_arn = get_secret_kms_key_arn(
+                    secret_name, region_name=AWS_REGION
+                )
+                if secret_kms_key_arn:
+                    context_data[f"kms_key_arn:{secret_name}"] = secret_kms_key_arn
+                    print("Cognito secret KMS key recorded for execution role decrypt.")
+            else:
+                print(
+                    "Warning: Cognito secret exists but ARN was not returned; "
+                    "CDK will use a name-based ARN wildcard in IAM policies."
+                )
+    else:
+        print(
+            "ENABLE_HEADLESS_DEPLOYMENT=True: skipping Cognito user pool and secret pre-checks."
+        )
+
+    # Service Connect client security groups (by name in VPC)
+    if ENABLE_ECS_SERVICE_CONNECT == "True":
+        vpc_id_for_sg = context_data.get("vpc_id")
+        if vpc_id_for_sg:
+            for sg_name in ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_NAMES_TO_LOOKUP:
+                exists, sg_id = get_security_group_id_by_name(
+                    sg_name, vpc_id_for_sg, region_name=AWS_REGION
+                )
+                context_data[f"exists:sg:{sg_name}"] = exists
+                if exists:
+                    context_data[f"security_group_id:{sg_name}"] = sg_id
+                    print(f"Service Connect client SG '{sg_name}' -> {sg_id}")
+                else:
+                    print(
+                        f"Warning: Service Connect client SG '{sg_name}' "
+                        f"not found in VPC {vpc_id_for_sg}"
+                    )
+        else:
+            print(
+                "Warning: vpc_id missing from context; cannot resolve Service "
+                "Connect client security group names."
+            )
+
+    # WAF Web ACL (by name and scope)
+    web_acl_name = WEB_ACL_NAME
+    exists, existing_web_acl = check_web_acl_exists(web_acl_name, scope="CLOUDFRONT")
+    context_data[f"exists:{web_acl_name}"] = exists
+    if exists:
+        context_data[f"arn:{web_acl_name}"] = existing_web_acl["ARN"]
+
+    # Write the context data to the file
+    with open(CONTEXT_FILE, "w") as f:
+        json.dump(context_data, f, indent=2)
+
+    print(f"Context data written to {CONTEXT_FILE}")
+
+
+if __name__ == "__main__":
+    print(f"Pre-check context file: {CONTEXT_FILE}")
+    print(
+        "Running AWS pre-check (requires credentials for the target account/region)..."
+    )
+    try:
+        check_and_set_context()
+    except SystemExit:
+        raise
+    except Exception as exc:
+        raise SystemExit(f"Pre-check failed: {exc}") from exc
+    if not os.path.exists(CONTEXT_FILE):
+        raise SystemExit(f"Pre-check finished but {CONTEXT_FILE} was not created.")
+    print(f"Pre-check complete. Context written to {os.path.abspath(CONTEXT_FILE)}")

cdk/config/app_config.env.example

@@ -0,0 +1,31 @@
+# AWS deployment app settings (copy to cdk/config/app_config.env — do not commit secrets).
+# Same variable names as tools/config.py; loaded by ECS from S3 or Express env.
+COGNITO_AUTH=True
+RUN_AWS_FUNCTIONS=True
+RUN_AWS_BEDROCK_MODELS=True
+RUN_LOCAL_MODEL=False
+RUN_GEMINI_MODELS=False
+RUN_AZURE_MODELS=False
+PRIORITISE_SSO_OVER_AWS_ENV_ACCESS_KEYS=True
+DISPLAY_FILE_NAMES_IN_LOGS=False
+SESSION_OUTPUT_FOLDER=True
+SAVE_LOGS_TO_CSV=True
+SAVE_LOGS_TO_DYNAMODB=True
+SHOW_COSTS=True
+S3_LOG_BUCKET=demo-llm-topic-s3-logs
+S3_OUTPUTS_BUCKET=
+S3_OUTPUTS_FOLDER=
+SAVE_OUTPUTS_TO_S3=False
+UPLOAD_USAGE_LOG_TO_S3_OUTPUTS=False
+UPLOAD_PROMPT_RESPONSE_LOG_TO_S3_OUTPUTS=False
+ACCESS_LOG_DYNAMODB_TABLE_NAME=demo-llm-topic-dynamodb-access-logs
+FEEDBACK_LOG_DYNAMODB_TABLE_NAME=demo-llm-topic-dynamodb-feedback-logs
+USAGE_LOG_DYNAMODB_TABLE_NAME=demo-llm-topic-dynamodb-usage-logs
+# Optional Bedrock Guardrails on Converse (same Region as the guardrail resource)
+# ENABLE_BEDROCK_GUARDRAILS=False
+# BEDROCK_GUARDRAIL_IDENTIFIER=
+# BEDROCK_GUARDRAIL_VERSION=1
+# BEDROCK_GUARDRAIL_TRACE=enabled
+LOG_FILE_NAME=log.csv
+USAGE_LOG_FILE_NAME=usage_log.csv
+FEEDBACK_LOG_FILE_NAME=feedback_log.csv

cdk/config/headless_s3_seed/general-config/app_defaults.env

@@ -0,0 +1,52 @@
+RUN_DIRECT_MODE=1
+RUN_AWS_FUNCTIONS=1
+RUN_AWS_BEDROCK_MODELS=1
+RUN_LOCAL_MODEL=0
+RUN_INFERENCE_SERVER=0
+RUN_GEMINI_MODELS=0
+RUN_AZURE_MODELS=0
+DIRECT_MODE_TASK=extract
+DIRECT_MODE_OUTPUT_DIR=output/
+SAVE_OUTPUTS_TO_S3=True
+S3_OUTPUTS_BUCKET=
+S3_OUTPUTS_FOLDER=output
+DIRECT_MODE_MAX_TOKENS=8192
+DIRECT_MODE_TEMPERATURE=1.0
+BEDROCK_READ_TIMEOUT_SECONDS=300
+BEDROCK_CONNECT_TIMEOUT_SECONDS=60
+# ENABLE_BEDROCK_GUARDRAILS=False
+# BEDROCK_GUARDRAIL_IDENTIFIER=
+# BEDROCK_GUARDRAIL_VERSION=1
+# BEDROCK_GUARDRAIL_TRACE=enabled
+DIRECT_MODE_BATCH_SIZE=10
+DIRECT_MODE_MODEL_CHOICE=google.gemma-3-27b-it
+DIRECT_MODE_RANDOM_SEED=42
+DIRECT_MODE_TASK=all_in_one
+SESSION_OUTPUT_FOLDER=True
+LLM_CONTEXT_LENGTH=65536
+LLM_RESET=False
+LLM_TOP_K=64
+LLM_TOP_P=0.95
+MAX_COMMENT_CHARS=100000
+OUTPUT_DEBUG_FILES=False
+DEFAULT_COST_CODE=D13922
+SAVE_LOGS_TO_DYNAMODB=True
+SAVE_LOGS_TO_CSV=True
+USAGE_LOG_FILE_NAME=usage_log.csv
+FEEDBACK_LOG_FILE_NAME=feedback_log.csv
+ENABLE_VALIDATION=False
+INCLUDE_TOPIC_CONFIDENCE=False
+DIRECT_MODE_INCLUDE_TOPIC_CONFIDENCE=No
+INCLUDE_RESPONSE_LEVEL_SUMMARY=False
+INCLUDE_GENERAL_TOPIC_PIVOT_TABLE=False
+PRIORITISE_SSO_OVER_AWS_ENV_ACCESS_KEYS=1
+DIRECT_MODE_S3_UPLOAD_ONLY_XLSX=True
+UPLOAD_USAGE_LOG_TO_S3_OUTPUTS=True
+ALL_IN_ONE_USE_LLM_DEDUP=True
+UPLOAD_PROMPT_RESPONSE_LOG_TO_S3_OUTPUTS=True
+ENABLE_INPUT_REDACTION=False
+ENABLE_ORIGINAL_DATA_REDACTION=False
+REDACTION_ENTITIES=['EMAIL_ADDRESS', 'PHONE_NUMBER', 'CREDIT_CARD', 'IBAN_CODE', 'UK_NHS', 'UKPOSTCODE', 'IP_ADDRESS', 'STREETNAME']
+REDACTION_STRATEGY=entity_type
+SPACY_MODEL=en_core_web_sm
+SPACY_MODEL_PATH=

cdk/config/headless_s3_seed/input/config/example_headless_env_file.env

@@ -0,0 +1,15 @@
+# Example job file for headless batch topic modelling.
+# 1. Upload your consultation spreadsheet to s3://<output-bucket>/input/
+# 2. Copy this file, set DIRECT_MODE_INPUT_FILE to that filename, save as my-job.env
+# 3. Upload my-job.env to s3://<output-bucket>/input/config/ to start the ECS task.
+# Durable defaults (app_defaults.env) live on the log/config bucket under
+# general-config/ — not the output bucket, which expires objects after N days.
+#
+# More DIRECT_MODE_* variables: tools/config.py and cli_topics.py in this repo.
+
+RUN_DIRECT_MODE=1
+DIRECT_MODE_TASK=extract
+DIRECT_MODE_INPUT_FILE=dummy_consultation_response.xlsx
+DIRECT_MODE_TEXT_COLUMN="Response Text"
+SAVE_OUTPUTS_TO_S3=True
+S3_OUTPUTS_FOLDER=output/

cdk/config/lambda/lambda_function.py

@@ -0,0 +1,192 @@
+import os
+import urllib.parse
+
+import boto3
+
+ecs = boto3.client("ecs")
+s3 = boto3.client("s3")
+
+# Move static config to Lambda env vars for easier ops
+BUCKET = os.environ.get("BUCKET", "lambeth-llm-topic-modelling")
+# Durable config (app_defaults.env) lives on the log/config bucket so it is not
+# deleted by the output bucket object-expiration lifecycle rule.
+LOG_BUCKET = os.environ.get("LOG_BUCKET") or BUCKET
+INPUT_PREFIX = os.environ.get("INPUT_PREFIX", "input/")
+ENV_PREFIX = os.environ.get("ENV_PREFIX", f"{INPUT_PREFIX}config/")
+GENERAL_ENV_PREFIX = os.environ.get("GENERAL_ENV_PREFIX", "general-config/")
+ENV_SUFFIX = os.environ.get("ENV_SUFFIX", ".env")
+DEFAULT_PARAMS_KEY = os.environ.get(
+    "DEFAULT_PARAMS_KEY", f"{GENERAL_ENV_PREFIX}app_defaults{ENV_SUFFIX}"
+)
+CLUSTER = os.environ.get("ECS_CLUSTER", "analytics_fargate_cluster")
+TASK_DEF = os.environ.get("ECS_TASK_DEF", "llm_topic_modelling_fargate_def:5")
+SUBNETS = os.environ.get(
+    "SUBNETS", "subnet-083650a35f93a0ee5,subnet-0a41ba70470cabab8"
+).split(",")
+SECURITY_GROUPS = os.environ.get("SECURITY_GROUPS", "sg-051effb4c5e752df1").split(",")
+ECS_ASSIGN_PUBLIC_IP = os.environ.get("ECS_ASSIGN_PUBLIC_IP", "DISABLED").upper()
+DEFAULT_INPUT_S3_URI = os.environ.get(
+    "DEFAULT_INPUT_S3_URI",
+    f"s3://{BUCKET}/{INPUT_PREFIX}dummy_consultation_response.xlsx",
+)
+DEFAULT_TASK_TYPE = os.environ.get("DEFAULT_TASK_TYPE", "extract")
+CONTAINER_NAME = os.environ.get("CONTAINER_NAME", "llm_topic_modelling_container")
+
+
+def _key_matches(key: str) -> bool:
+    return key.startswith(ENV_PREFIX) and key.endswith(ENV_SUFFIX)
+
+
+def _derive_runtime_params_from_key(key: str) -> dict:
+    """Optional convention: decide task type from file name."""
+    basename = key.split("/")[-1].lower()
+    if "train" in basename:
+        task_type = "train"
+    elif "infer" in basename or "staging" in basename:
+        task_type = "infer"
+    else:
+        task_type = DEFAULT_TASK_TYPE
+
+    return {
+        "DIRECT_MODE_TASK": task_type,
+        "DIRECT_MODE_INPUT_FILE": DEFAULT_INPUT_S3_URI,
+    }
+
+
+def _parse_dotenv(dotenv_bytes: bytes, bucket: str, input_prefix: str) -> dict:
+    """
+    Parse a basic .env and prepend S3 paths to specific keys if they have values.
+    """
+    env = {}
+    text = dotenv_bytes.decode("utf-8", errors="replace")
+
+    # 1. Parse the file (Existing Logic)
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export ") :].strip()
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        if (value.startswith('"') and value.endswith('"')) or (
+            value.startswith("'") and value.endswith("'")
+        ):
+            value = value[1:-1]
+        env[key] = value
+
+    # 2. Apply S3 Prefix Logic (New Logic)
+    # We define the base S3 path string using the provided arguments
+    s3_base = f"s3://{bucket}/{input_prefix}"
+
+    # List of keys that need modification
+    keys_to_modify = ["DIRECT_MODE_INPUT_FILE", "DIRECT_MODE_CANDIDATE_TOPICS"]
+
+    for key in keys_to_modify:
+        # env.get(key) returns the value.
+        # The 'if' check ensures the key exists AND is not an empty string.
+        if env.get(key):
+            env[key] = s3_base + env[key]
+
+    return env
+
+
+def _build_environment_array(*env_dicts):
+    """Merge dictionaries left→right and produce ECS environment array format."""
+    merged = {}
+    for d in env_dicts:
+        merged.update(d or {})
+    # ECS override format: [{"name": "...","value":"..."}]
+    return [{"name": k, "value": v} for k, v in merged.items()]
+
+
+def lambda_handler(event, context):
+    runs = []
+
+    # Parse default env file with default config.
+    # Read from LOG_BUCKET (log/config bucket) so app_defaults.env survives
+    # output-bucket lifecycle expiration.
+    print(f"Loading default params from s3://{LOG_BUCKET}/{DEFAULT_PARAMS_KEY}")
+    default_obj = s3.get_object(Bucket=LOG_BUCKET, Key=DEFAULT_PARAMS_KEY)
+    default_dotenv_bytes = default_obj["Body"].read()
+
+    # Parse .env → dict of env vars (input paths still resolve against output BUCKET)
+    default_file_env = _parse_dotenv(default_dotenv_bytes, BUCKET, INPUT_PREFIX)
+
+    for record in event.get("Records", []):
+
+        # Parse env file from user
+        s3rec = record.get("s3", {})
+        bucket = s3rec.get("bucket", {}).get("name")
+        raw_key = s3rec.get("object", {}).get("key")
+        if not bucket or not raw_key:
+            print(f"Object in bucket {bucket} and key {raw_key} not found, exiting.")
+            continue
+
+        key = urllib.parse.unquote_plus(raw_key)
+
+        # combined_key = ENV_PREFIX + key
+        combined_key = key
+
+        print("combined_key:", combined_key)
+
+        # Only process the intended prefix/suffix
+        if not _key_matches(combined_key):
+            print(f"Key does not match: {combined_key}, exiting")
+            continue
+
+        # Fetch the .env file content from S3
+        obj = s3.get_object(Bucket=bucket, Key=combined_key)
+        dotenv_bytes = obj["Body"].read()
+
+        # Parse .env → dict of env vars
+        file_env = _parse_dotenv(dotenv_bytes, BUCKET, INPUT_PREFIX)
+
+        # Optionally derive run-time params from naming
+        # run_params = _derive_runtime_params_from_key(key)
+
+        # Merge: file env (dominant), overwrites default values.
+        environment = _build_environment_array(file_env, default_file_env)
+
+        print("Combined environment variables:", environment)
+
+        # Execute ECS Fargate task with fully dynamic environment overrides
+        response = ecs.run_task(
+            cluster=CLUSTER,
+            launchType="FARGATE",
+            taskDefinition=TASK_DEF,
+            networkConfiguration={
+                "awsvpcConfiguration": {
+                    "subnets": SUBNETS,
+                    "securityGroups": SECURITY_GROUPS,
+                    "assignPublicIp": (
+                        ECS_ASSIGN_PUBLIC_IP
+                        if ECS_ASSIGN_PUBLIC_IP in ("ENABLED", "DISABLED")
+                        else "DISABLED"
+                    ),
+                }
+            },
+            overrides={
+                "containerOverrides": [
+                    {
+                        "name": CONTAINER_NAME,
+                        "environment": environment,
+                    }
+                ]
+            },
+        )
+
+        runs.append(
+            {
+                "bucket": bucket,
+                "key": key,
+                "taskArns": [t["taskArn"] for t in response.get("tasks", [])],
+                "failures": response.get("failures", []),
+                "envCount": len(environment),
+            }
+        )
+
+    return {"runs": runs}

cdk/docs/express_pi_service_connect_spike.md

@@ -0,0 +1,71 @@
+# Phase 0: Express Service Connect validation (dev account)
+
+Service Connect for Express is applied in `post_cdk_build_quickstart.py` (not during
+`cdk deploy`). Express primary containers do not define named `portMappings` at create
+time, so the post-deploy step registers a task-definition revision with
+`port-{port}` and then calls `ecs:UpdateService` with `serviceConnectConfiguration`.
+Use this checklist to confirm behaviour in a dev account before relying on Pi Express demos.
+
+## Prerequisites
+
+- Main Express stack deployed (`USE_ECS_EXPRESS_MODE=True`).
+- Optional: deploy with `ENABLE_PI_AGENT_EXPRESS_SERVICE=True` and run
+  `python post_cdk_build_quickstart.py` (Service Connect is configured there).
+
+## Manual validation (without Pi CDK flag)
+
+1. Note cluster name, main Express **service name**, and task security group from stack outputs.
+2. Ensure the cluster has a default Cloud Map namespace (CDK creates one when Pi Express is enabled).
+3. Update the main Express service (server):
+
+```bash
+aws ecs update-service \
+  --cluster <CLUSTER_NAME> \
+  --service <ECS_EXPRESS_SERVICE_NAME> \
+  --force-new-deployment \
+  --service-connect-configuration '{
+    "enabled": true,
+    "namespace": "<ECS_SERVICE_CONNECT_NAMESPACE>",
+    "services": [{
+      "portName": "port-7860",
+      "discoveryName": "summarisation",
+      "clientAliases": [{"port": 7860, "dnsName": "summarisation"}]
+    }]
+  }'
+```
+
+4. Deploy a second Express service (Pi image, port **7862**) or use CDK Pi Express.
+5. Update the Pi Express service (client only):
+
+```bash
+aws ecs update-service \
+  --cluster <CLUSTER_NAME> \
+  --service <ECS_PI_EXPRESS_SERVICE_NAME> \
+  --force-new-deployment \
+  --service-connect-configuration '{
+    "enabled": true,
+    "namespace": "<ECS_SERVICE_CONNECT_NAMESPACE>"
+  }'
+```
+
+6. Exec into a Pi task (ECS Exec enabled on the service):
+
+```bash
+curl -sS -o /dev/null -w "%{http_code}\n" http://summarisation:7860/
+```
+
+Expect HTTP **200** (or Gradio redirect) without Cognito.
+
+7. Optional: run a minimal `gradio_client` predict against `/doc_redact` from the Pi task.
+
+## Exit criteria
+
+- Service Connect DNS `summarisation` resolves inside the Pi task network namespace.
+- Gradio responds on port 7860 without ALB Cognito.
+- If `update-service` fails or `portName` is rejected, stop and use legacy Fargate Pi +
+  `ENABLE_ECS_SERVICE_CONNECT` until AWS/CDK support is confirmed (plan Phase 2 hybrid).
+
+## CDK deploy path
+
+With `ENABLE_PI_AGENT_EXPRESS_SERVICE=True`, run `post_cdk_build_quickstart.py` after
+`cdk deploy`. Check its output for Service Connect / task-definition errors.

cdk/example_headless_env_file.env

@@ -0,0 +1 @@
+DIRECT_MODE_INPUT_FILE=example_of_emails_sent_to_a_professor_before_applying.pdf

cdk/lambda_dynamo_logs_export/lambda_function.py

@@ -0,0 +1,316 @@
+"""
+Lambda handler to export DynamoDB usage log table to CSV and upload to S3.
+
+All inputs are read from environment variables (no argparse).
+Intended to run as an AWS Lambda function; can also be invoked locally
+by setting env vars and calling lambda_handler({}, None).
+
+Environment variables (same semantics as load_dynamo_logs.py CLI):
+  DYNAMODB_TABLE_NAME       - DynamoDB table name (default: summarisation_usage)
+  AWS_REGION                - AWS region (optional; if unset, uses AWS_DEFAULT_REGION,
+                              then region from Lambda context ARN, then eu-west-2)
+  OUTPUT_FOLDER             - Local output directory, e.g. /tmp (optional)
+  OUTPUT_FILENAME           - Local output file name (default: dynamodb_logs_export.csv)
+  OUTPUT                    - Full local output path (overrides folder + filename if set).
+                              In Lambda only /tmp is writable; relative paths are auto-resolved to /tmp.
+  FROM_DATE                 - Only include entries on/after this date YYYY-MM-DD (optional)
+  TO_DATE                   - Only include entries on/before this date YYYY-MM-DD (optional)
+  DATE_ATTRIBUTE            - Attribute name for date filtering (default: timestamp)
+  S3_OUTPUT_BUCKET          - S3 bucket for the output CSV (required for upload)
+  S3_OUTPUT_KEY             - S3 object key/path for the output CSV (required for upload)
+"""
+
+import csv
+import datetime
+import os
+from decimal import Decimal
+from io import StringIO
+
+import boto3
+
+
+def _get_region_from_context(context):
+    """Extract region from Lambda context invoked_function_arn (arn:aws:lambda:REGION:ACCOUNT:function:NAME)."""
+    if context is None:
+        return None
+    arn = getattr(context, "invoked_function_arn", None)
+    if not arn or not isinstance(arn, str):
+        return None
+    parts = arn.split(":")
+    if len(parts) >= 4:
+        return parts[3]  # region is 4th segment
+    return None
+
+
+def get_config_from_env(context=None):
+    """Read all settings from environment variables (same inputs as load_dynamo_logs.py).
+    When running in Lambda, context can be passed to derive region from the function ARN if env is not set.
+    """
+    today = datetime.datetime.now().date()
+    one_year_ago = today - datetime.timedelta(days=365)
+
+    table_name = os.environ.get("DYNAMODB_TABLE_NAME") or os.environ.get(
+        "USAGE_LOG_DYNAMODB_TABLE_NAME", "summarisation_usage"
+    )
+    region = (
+        os.environ.get("AWS_REGION") or os.environ.get("AWS_DEFAULT_REGION") or ""
+    ).strip()
+    output = os.environ.get("OUTPUT")
+    output_folder = os.environ.get("OUTPUT_FOLDER", "output/")
+    output_filename = os.environ.get("OUTPUT_FILENAME", "dynamodb_logs_export.csv")
+    from_date_str = os.environ.get("FROM_DATE")
+    to_date_str = os.environ.get("TO_DATE")
+    date_attribute = os.environ.get("DATE_ATTRIBUTE", "timestamp")
+    s3_output_bucket = os.environ.get("S3_OUTPUT_BUCKET")
+    s3_output_key = os.environ.get("S3_OUTPUT_KEY")
+
+    if output:
+        local_output_path = output
+    else:
+        folder = output_folder.rstrip("/").rstrip("\\")
+        local_output_path = os.path.join(folder, output_filename)
+
+    # In AWS Lambda only /tmp is writable; resolve relative paths to /tmp to avoid read-only FS errors
+    if os.environ.get("AWS_LAMBDA_FUNCTION_NAME"):
+        resolved = os.path.abspath(local_output_path)
+        if not resolved.startswith("/tmp"):
+            local_output_path = os.path.join(
+                "/tmp", os.path.basename(local_output_path)
+            )
+
+    # Region: env (AWS_REGION / AWS_DEFAULT_REGION) → Lambda context ARN → hardcoded fallback
+    if not region and context is not None:
+        region = _get_region_from_context(context) or ""
+    if not region:
+        region = "eu-west-2"
+
+    from_date = None
+    to_date = None
+    if from_date_str:
+        from_date = datetime.datetime.strptime(from_date_str, "%Y-%m-%d").date()
+    if to_date_str:
+        to_date = datetime.datetime.strptime(to_date_str, "%Y-%m-%d").date()
+    if from_date is None and to_date is None:
+        from_date = one_year_ago
+        to_date = today
+    elif from_date is None:
+        from_date = one_year_ago
+    elif to_date is None:
+        to_date = today
+
+    return {
+        "table_name": table_name,
+        "region": region,
+        "local_output_path": local_output_path,
+        "from_date": from_date,
+        "to_date": to_date,
+        "date_attribute": date_attribute,
+        "s3_output_bucket": s3_output_bucket,
+        "s3_output_key": s3_output_key,
+    }
+
+
+def convert_types(item):
+    new_item = {}
+    for key, value in item.items():
+        if isinstance(value, Decimal):
+            new_item[key] = int(value) if value % 1 == 0 else float(value)
+        elif isinstance(value, str):
+            try:
+                dt_obj = datetime.datetime.fromisoformat(value.replace("Z", "+00:00"))
+                new_item[key] = dt_obj.strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+            except (ValueError, TypeError):
+                new_item[key] = value
+        else:
+            new_item[key] = value
+    return new_item
+
+
+def _parse_item_date(value):
+    """Parse a DynamoDB attribute value to datetime for comparison. Returns None if unparseable."""
+    if value is None:
+        return None
+    if isinstance(value, Decimal):
+        try:
+            return datetime.datetime.utcfromtimestamp(float(value))
+        except (ValueError, OSError):
+            return None
+    if isinstance(value, (int, float)):
+        try:
+            return datetime.datetime.utcfromtimestamp(float(value))
+        except (ValueError, OSError):
+            return None
+    if isinstance(value, str):
+        for fmt in (
+            "%Y-%m-%d %H:%M:%S.%f",
+            "%Y-%m-%d %H:%M:%S",
+            "%Y-%m-%d",
+            "%Y-%m-%dT%H:%M:%S",
+        ):
+            try:
+                return datetime.datetime.strptime(value, fmt)
+            except (ValueError, TypeError):
+                continue
+        try:
+            return datetime.datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except (ValueError, TypeError):
+            pass
+    return None
+
+
+def filter_items_by_date(items, from_date, to_date, date_attribute: str):
+    """Return items whose date attribute falls within [from_date, to_date] (inclusive)."""
+    if from_date is None and to_date is None:
+        return items
+    start = datetime.datetime.combine(from_date, datetime.time.min)
+    end = datetime.datetime.combine(to_date, datetime.time.max)
+    filtered = []
+    for item in items:
+        raw = item.get(date_attribute)
+        dt = _parse_item_date(raw)
+        if dt is None:
+            continue
+        if dt.tzinfo:
+            dt = dt.replace(tzinfo=None)
+        if start <= dt <= end:
+            filtered.append(item)
+    return filtered
+
+
+def scan_table(table):
+    """Paginated scan of DynamoDB table."""
+    items = []
+    response = table.scan()
+    items.extend(response["Items"])
+    while "LastEvaluatedKey" in response:
+        response = table.scan(ExclusiveStartKey=response["LastEvaluatedKey"])
+        items.extend(response["Items"])
+    return items
+
+
+def export_to_csv_buffer(items, fields_to_drop=None):
+    """
+    Write items to a CSV in memory; return (csv_string, fieldnames).
+    Use for uploading to S3 without writing to disk.
+    """
+    if not items:
+        return "", []
+
+    drop_set = set(fields_to_drop or [])
+    all_keys = set()
+    for item in items:
+        all_keys.update(item.keys())
+    fieldnames = sorted(list(all_keys - drop_set))
+
+    buf = StringIO()
+    writer = csv.DictWriter(
+        buf, fieldnames=fieldnames, extrasaction="ignore", restval=""
+    )
+    writer.writeheader()
+    for item in items:
+        writer.writerow(convert_types(item))
+    return buf.getvalue(), fieldnames
+
+
+def export_to_csv_file(items, output_path, fields_to_drop=None):
+    """Write items to a CSV file (for optional /tmp or local path)."""
+    csv_string, _ = export_to_csv_buffer(items, fields_to_drop)
+    if not csv_string:
+        return
+    os.makedirs(os.path.dirname(os.path.abspath(output_path)) or ".", exist_ok=True)
+    with open(output_path, "w", newline="", encoding="utf-8-sig") as f:
+        f.write(csv_string)
+
+
+def run_export(config):
+    """
+    Run the full export: scan DynamoDB, filter by date, write CSV (buffer and/or file), upload to S3.
+    """
+    table_name = config["table_name"]
+    region = config["region"]
+    local_output_path = config["local_output_path"]
+    from_date = config["from_date"]
+    to_date = config["to_date"]
+    date_attribute = config["date_attribute"]
+    s3_output_bucket = config["s3_output_bucket"]
+    s3_output_key = config["s3_output_key"]
+
+    if from_date > to_date:
+        raise ValueError("FROM_DATE must be on or before TO_DATE")
+
+    dynamodb = boto3.resource("dynamodb", region_name=region or None)
+    table = dynamodb.Table(table_name)
+
+    items = scan_table(table)
+    items = filter_items_by_date(items, from_date, to_date, date_attribute)
+
+    csv_string, fieldnames = export_to_csv_buffer(items, fields_to_drop=[])
+    result = {
+        "item_count": len(items),
+        "from_date": str(from_date),
+        "to_date": str(to_date),
+        "columns": fieldnames,
+    }
+
+    if csv_string:
+        try:
+            export_to_csv_file(items, local_output_path, fields_to_drop=[])
+            result["local_path"] = local_output_path
+        except Exception as e:
+            result["local_write_error"] = str(e)
+
+        if s3_output_bucket and s3_output_key:
+            s3 = boto3.client("s3", region_name=region or None)
+            s3.put_object(
+                Bucket=s3_output_bucket,
+                Key=s3_output_key,
+                Body=csv_string.encode("utf-8-sig"),
+                ContentType="text/csv; charset=utf-8",
+            )
+            result["s3_uri"] = f"s3://{s3_output_bucket}/{s3_output_key}"
+        elif s3_output_bucket or s3_output_key:
+            result["s3_skip_reason"] = (
+                "Both S3_OUTPUT_BUCKET and S3_OUTPUT_KEY must be set"
+            )
+
+    return result
+
+
+def lambda_handler(event, context):
+    """
+    AWS Lambda entrypoint. Config is read from environment variables.
+
+    Event is not required for config; it can be used to override env vars
+    (e.g. pass table_name, from_date, to_date, s3_output_bucket, s3_output_key).
+    """
+    config = get_config_from_env(context=context)
+
+    if isinstance(event, dict):
+        if event.get("table_name"):
+            config["table_name"] = event["table_name"]
+        if event.get("region"):
+            config["region"] = event["region"]
+        if event.get("from_date"):
+            config["from_date"] = datetime.datetime.strptime(
+                event["from_date"], "%Y-%m-%d"
+            ).date()
+        if event.get("to_date"):
+            config["to_date"] = datetime.datetime.strptime(
+                event["to_date"], "%Y-%m-%d"
+            ).date()
+        if event.get("date_attribute"):
+            config["date_attribute"] = event["date_attribute"]
+        if event.get("s3_output_bucket"):
+            config["s3_output_bucket"] = event["s3_output_bucket"]
+        if event.get("s3_output_key"):
+            config["s3_output_key"] = event["s3_output_key"]
+
+    result = run_export(config)
+    return {"statusCode": 200, "body": result}
+
+
+if __name__ == "__main__":
+    import json
+
+    result = lambda_handler({}, None)
+    print(json.dumps(result, indent=2))

cdk/lambda_elbv2_listener_rule_upsert/lambda_function.py

@@ -0,0 +1,187 @@
+"""
+CloudFormation custom resource: create or update an ALB listener rule (upsert by priority).
+
+If a rule already exists at the requested priority with matching conditions, it is
+modified in place. This supports stack retries after partial deploys left orphaned rules.
+If priority is taken by a rule with different conditions, the operation fails with a
+clear error so operators can choose another PI_ALB_LISTENER_RULE_PRIORITY.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import boto3
+from botocore.exceptions import ClientError
+
+LOGGER = logging.getLogger()
+LOGGER.setLevel(logging.INFO)
+
+elbv2 = boto3.client("elbv2")
+
+_DELETE_NOT_FOUND = frozenset(
+    {
+        "RuleNotFound",
+        "ResourceNotFound",
+        "ValidationError",
+    }
+)
+# CloudFormation custom-resource properties are strings; ELBv2 expects typed fields.
+_ELBV2_INT_KEYS = frozenset(
+    {
+        "Order",
+        "Priority",
+        "SessionTimeout",
+        "DurationSeconds",
+        "SessionCookieName",
+    }
+)
+_ELBV2_BOOL_KEYS = frozenset({"Enabled"})
+
+
+def _parse_json(value: Any) -> Any:
+    if isinstance(value, str):
+        return json.loads(value)
+    return value
+
+
+def _coerce_elbv2_api_value(key: str, value: Any) -> Any:
+    """Coerce CloudFormation string properties to types boto3 elbv2 expects."""
+    if isinstance(value, dict):
+        return {k: _coerce_elbv2_api_value(k, v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_coerce_elbv2_api_value(key, item) for item in value]
+    if isinstance(value, str):
+        if key in _ELBV2_INT_KEYS:
+            try:
+                return int(value)
+            except ValueError:
+                return value
+        if key in _ELBV2_BOOL_KEYS:
+            lowered = value.lower()
+            if lowered == "true":
+                return True
+            if lowered == "false":
+                return False
+    return value
+
+
+def _normalize_listener_rule_payload(
+    conditions: list[dict[str, Any]],
+    actions: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    return (
+        [_coerce_elbv2_api_value("", c) for c in conditions],
+        [_coerce_elbv2_api_value("", a) for a in actions],
+    )
+
+
+def _condition_values(condition: dict[str, Any]) -> list[str]:
+    field = condition.get("Field")
+    if field == "path-pattern":
+        cfg = condition.get("PathPatternConfig") or {}
+        return sorted(cfg.get("Values") or condition.get("Values") or [])
+    if field == "host-header":
+        cfg = condition.get("HostHeaderConfig") or {}
+        return sorted(cfg.get("Values") or condition.get("Values") or [])
+    return sorted(condition.get("Values") or [])
+
+
+def _conditions_match(
+    rule_conditions: list[dict[str, Any]], expected: list[dict[str, Any]]
+) -> bool:
+    if len(rule_conditions) != len(expected):
+        return False
+    for exp in expected:
+        exp_field = exp.get("Field")
+        exp_vals = _condition_values(exp)
+        if not any(
+            rc.get("Field") == exp_field and _condition_values(rc) == exp_vals
+            for rc in rule_conditions
+        ):
+            return False
+    return True
+
+
+def _rule_at_priority(
+    rules: list[dict[str, Any]], priority: int
+) -> dict[str, Any] | None:
+    target = str(priority)
+    for rule in rules:
+        if rule.get("Priority") == target:
+            return rule
+    return None
+
+
+def _upsert_rule(
+    *,
+    listener_arn: str,
+    priority: int,
+    conditions: list[dict[str, Any]],
+    actions: list[dict[str, Any]],
+) -> str:
+    described = elbv2.describe_rules(ListenerArn=listener_arn)
+    existing = _rule_at_priority(described.get("Rules", []), priority)
+    if existing:
+        if _conditions_match(existing.get("Conditions", []), conditions):
+            rule_arn = existing["RuleArn"]
+            LOGGER.info(
+                "Modifying existing listener rule %s at priority %s", rule_arn, priority
+            )
+            elbv2.modify_rule(RuleArn=rule_arn, Conditions=conditions, Actions=actions)
+            return rule_arn
+        raise RuntimeError(
+            f"Listener rule priority {priority} is already in use by {existing['RuleArn']} "
+            "with different conditions. Delete that rule in the ELB console or set "
+            "PI_ALB_LISTENER_RULE_PRIORITY to a free value, then redeploy."
+        )
+    LOGGER.info("Creating listener rule at priority %s on %s", priority, listener_arn)
+    created = elbv2.create_rule(
+        ListenerArn=listener_arn,
+        Priority=priority,
+        Conditions=conditions,
+        Actions=actions,
+    )
+    return created["Rules"][0]["RuleArn"]
+
+
+def _delete_rule(rule_arn: str) -> None:
+    if not rule_arn:
+        return
+    try:
+        elbv2.delete_rule(RuleArn=rule_arn)
+    except ClientError as exc:
+        code = exc.response.get("Error", {}).get("Code", "")
+        if code in _DELETE_NOT_FOUND:
+            LOGGER.info("Rule %s already deleted (%s)", rule_arn, code)
+            return
+        raise
+
+
+def handler(event, context):
+    request_type = event["RequestType"]
+    props = event["ResourceProperties"]
+    listener_arn = props["ListenerArn"]
+    priority = int(props["Priority"])
+    conditions, actions = _normalize_listener_rule_payload(
+        _parse_json(props["Conditions"]),
+        _parse_json(props["Actions"]),
+    )
+
+    if request_type == "Delete":
+        _delete_rule(event.get("PhysicalResourceId", ""))
+        return {"PhysicalResourceId": event.get("PhysicalResourceId", "deleted")}
+
+    rule_arn = _upsert_rule(
+        listener_arn=listener_arn,
+        priority=priority,
+        conditions=conditions,
+        actions=actions,
+    )
+    if request_type == "Update":
+        prior_arn = event.get("PhysicalResourceId", "")
+        if prior_arn and prior_arn != rule_arn:
+            _delete_rule(prior_arn)
+    return {"PhysicalResourceId": rule_arn}

cdk/post_cdk_build_quickstart.py

@@ -0,0 +1,201 @@
+import os
+import time
+
+from cdk_config import (
+    AWS_REGION,
+    CDK_PREFIX,
+    CLUSTER_NAME,
+    CODEBUILD_PI_PROJECT_NAME,
+    CODEBUILD_PROJECT_NAME,
+    COGNITO_USER_POOL_CLIENT_SECRET_NAME,
+    ECS_EXPRESS_COGNITO_REDIRECT_BASE,
+    ECS_EXPRESS_SC_PORT_NAME,
+    ECS_EXPRESS_SERVICE_NAME,
+    ECS_LOG_GROUP_NAME,
+    ECS_PI_EXPRESS_SERVICE_NAME,
+    ECS_PI_SERVICE_NAME,
+    ECS_SERVICE_CONNECT_DISCOVERY_NAME,
+    ECS_SERVICE_CONNECT_NAMESPACE,
+    ECS_SERVICE_NAME,
+    ENABLE_HEADLESS_DEPLOYMENT,
+    ENABLE_PI_AGENT_ECS_SERVICE,
+    ENABLE_PI_AGENT_EXPRESS_SERVICE,
+    GITHUB_REPO_BRANCH,
+    GITHUB_REPO_NAME,
+    GITHUB_REPO_USERNAME,
+    GRADIO_SERVER_PORT,
+    PI_AGENT_ENV_S3_KEY,
+    S3_BATCH_DEFAULT_PARAMS_KEY,
+    S3_BATCH_ENV_PREFIX,
+    S3_BATCH_INPUT_PREFIX,
+    S3_BATCH_LAMBDA_FUNCTION_NAME,
+    S3_LOG_CONFIG_BUCKET_NAME,
+    S3_OUTPUT_BUCKET_NAME,
+    USE_ECS_EXPRESS_MODE,
+)
+from cdk_functions import create_basic_config_env, ensure_codebuild_public_github_source
+
+# boto3-only module (does not import aws-cdk / Node.js)
+from cdk_post_deploy import (
+    apply_cognito_secret_fixup_from_stack,
+    configure_express_pi_service_connect,
+    print_headless_deployment_next_steps,
+    seed_headless_batch_s3_layout,
+    start_codebuild_build,
+    start_ecs_task,
+    start_express_gateway_service,
+    upload_file_to_s3,
+)
+from tqdm import tqdm
+
+# Create basic app_config.env file that user can use to run the app later. Input is the folder it is saved into.
+create_basic_config_env(
+    "config",
+    headless=ENABLE_HEADLESS_DEPLOYMENT == "True",
+    pi_express_backend=ENABLE_PI_AGENT_EXPRESS_SERVICE == "True",
+)
+
+# Ensure CodeBuild clones the public GitHub repo (not CodeConnections/OAuth).
+ensure_codebuild_public_github_source(
+    CODEBUILD_PROJECT_NAME,
+    GITHUB_REPO_USERNAME,
+    GITHUB_REPO_NAME,
+    GITHUB_REPO_BRANCH,
+    aws_region=AWS_REGION,
+)
+
+# Start CodeBuild for the main app image
+print("Starting main app CodeBuild project.")
+start_codebuild_build(project_name=CODEBUILD_PROJECT_NAME)
+
+_enable_pi_image_build = (
+    ENABLE_PI_AGENT_ECS_SERVICE == "True" or ENABLE_PI_AGENT_EXPRESS_SERVICE == "True"
+)
+if _enable_pi_image_build:
+    ensure_codebuild_public_github_source(
+        CODEBUILD_PI_PROJECT_NAME,
+        GITHUB_REPO_USERNAME,
+        GITHUB_REPO_NAME,
+        GITHUB_REPO_BRANCH,
+        aws_region=AWS_REGION,
+    )
+    print("Starting Pi agent CodeBuild project.")
+    start_codebuild_build(project_name=CODEBUILD_PI_PROJECT_NAME)
+
+# Upload app_config.env file to S3 bucket
+upload_file_to_s3(
+    local_file_paths="config/app_config.env",
+    s3_key="",
+    s3_bucket=S3_LOG_CONFIG_BUCKET_NAME,
+)
+
+if _enable_pi_image_build:
+    pi_env_local = os.path.join("config", "pi_agent.env")
+    if os.path.isfile(pi_env_local):
+        print(
+            f"Uploading {pi_env_local} to s3://{S3_LOG_CONFIG_BUCKET_NAME}/{PI_AGENT_ENV_S3_KEY}"
+        )
+        upload_file_to_s3(
+            local_file_paths=pi_env_local,
+            s3_key="",
+            s3_bucket=S3_LOG_CONFIG_BUCKET_NAME,
+        )
+    else:
+        print(
+            f"Skipping Pi env upload: {pi_env_local} not found. "
+            f"Create it (from config/pi_agent.env.example) and upload to "
+            f"s3://{S3_LOG_CONFIG_BUCKET_NAME}/{PI_AGENT_ENV_S3_KEY} before scaling the Pi service."
+        )
+
+total_seconds = 480  # 8 minutes
+update_interval = 1  # Update every second
+
+print("Waiting 8 minutes for CodeBuild container image(s) to build.")
+
+# tqdm iterates over a range, and you perform a small sleep in each iteration
+for i in tqdm(range(total_seconds), desc="Building container"):
+    time.sleep(update_interval)
+
+# Scale main ECS service to one task (skipped for headless batch-only deployments)
+if ENABLE_HEADLESS_DEPLOYMENT != "True":
+    if USE_ECS_EXPRESS_MODE == "True":
+        print(f"Starting Express ECS service {ECS_EXPRESS_SERVICE_NAME}")
+        start_express_gateway_service(
+            cluster_name=CLUSTER_NAME, service_name=ECS_EXPRESS_SERVICE_NAME
+        )
+        if ENABLE_PI_AGENT_EXPRESS_SERVICE == "True":
+            print(
+                "Configuring Service Connect for main Express (server) and "
+                "Pi Express (client)."
+            )
+            try:
+                configure_express_pi_service_connect(
+                    cluster_name=CLUSTER_NAME,
+                    main_service_name=ECS_EXPRESS_SERVICE_NAME,
+                    pi_service_name=ECS_PI_EXPRESS_SERVICE_NAME,
+                    namespace=ECS_SERVICE_CONNECT_NAMESPACE,
+                    main_port_name=ECS_EXPRESS_SC_PORT_NAME,
+                    discovery_name=ECS_SERVICE_CONNECT_DISCOVERY_NAME,
+                    main_port=int(GRADIO_SERVER_PORT),
+                )
+            except Exception as exc:
+                print("Warning: could not configure Express Service Connect: " f"{exc}")
+        print("Syncing Cognito app client secret for in-app authentication.")
+        apply_cognito_secret_fixup_from_stack(
+            stack_name="SummarisationStack",
+            secret_name=COGNITO_USER_POOL_CLIENT_SECRET_NAME,
+            cluster_name=CLUSTER_NAME,
+            main_service_name=ECS_EXPRESS_SERVICE_NAME,
+            recycle_tasks=False,
+        )
+    else:
+        print(f"Starting ECS service {ECS_SERVICE_NAME}")
+        start_ecs_task(cluster_name=CLUSTER_NAME, service_name=ECS_SERVICE_NAME)
+else:
+    print(
+        "Headless deployment: skipping always-on ECS service start "
+        "(tasks are started by the S3 batch Lambda)."
+    )
+    seed_headless_batch_s3_layout(
+        S3_OUTPUT_BUCKET_NAME,
+        input_prefix=S3_BATCH_INPUT_PREFIX,
+        env_prefix=S3_BATCH_ENV_PREFIX,
+        example_env_local_path=os.path.join("config", "example_headless_env_file.env"),
+        log_bucket=S3_LOG_CONFIG_BUCKET_NAME,
+        default_params_key=S3_BATCH_DEFAULT_PARAMS_KEY,
+        s3_outputs_bucket_name=S3_OUTPUT_BUCKET_NAME,
+    )
+    print_headless_deployment_next_steps(
+        {
+            "AWS_REGION": AWS_REGION,
+            "S3_OUTPUT_BUCKET_NAME": S3_OUTPUT_BUCKET_NAME,
+            "S3_LOG_CONFIG_BUCKET_NAME": S3_LOG_CONFIG_BUCKET_NAME,
+            "S3_BATCH_INPUT_PREFIX": S3_BATCH_INPUT_PREFIX,
+            "S3_BATCH_ENV_PREFIX": S3_BATCH_ENV_PREFIX,
+            "S3_BATCH_DEFAULT_PARAMS_KEY": S3_BATCH_DEFAULT_PARAMS_KEY,
+            "ECS_LOG_GROUP_NAME": ECS_LOG_GROUP_NAME,
+            "S3_BATCH_LAMBDA_FUNCTION_NAME": S3_BATCH_LAMBDA_FUNCTION_NAME,
+            "CDK_PREFIX": CDK_PREFIX,
+        }
+    )
+
+if ENABLE_PI_AGENT_ECS_SERVICE == "True":
+    print(f"Starting Pi agent ECS service {ECS_PI_SERVICE_NAME}")
+    start_ecs_task(cluster_name=CLUSTER_NAME, service_name=ECS_PI_SERVICE_NAME)
+
+if ENABLE_PI_AGENT_EXPRESS_SERVICE == "True":
+    print(f"Starting Pi Express ECS service {ECS_PI_EXPRESS_SERVICE_NAME}")
+    start_express_gateway_service(
+        cluster_name=CLUSTER_NAME, service_name=ECS_PI_EXPRESS_SERVICE_NAME
+    )
+
+if USE_ECS_EXPRESS_MODE == "True" and ENABLE_HEADLESS_DEPLOYMENT != "True":
+    from cdk_post_deploy import print_express_mode_next_steps
+
+    print_express_mode_next_steps(
+        {
+            "AWS_REGION": AWS_REGION,
+            "ECS_EXPRESS_COGNITO_REDIRECT_BASE": ECS_EXPRESS_COGNITO_REDIRECT_BASE,
+            "ENABLE_PI_AGENT_EXPRESS_SERVICE": ENABLE_PI_AGENT_EXPRESS_SERVICE,
+        }
+    )

cdk/requirements.txt

@@ -0,0 +1,8 @@
+aws-cdk-lib>=2.268.0
+# Optional: only needed when ENABLE_APPREGISTRY=True (legacy myApplications; new-
+# customer cut-off 30 Jul 2026). Can be removed once the AppRegistry path is retired.
+# aws-cdk.aws-servicecatalogappregistry-alpha~=2.257.0a0
+boto3
+pandas
+nodejs
+python-dotenv

cdk/test/test_application_tags_and_resource_group.py

@@ -0,0 +1,79 @@
+"""Synth coverage for application tags and tag-based Resource Groups."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+
+def test_apply_application_tags_to_app():
+    from aws_cdk import App, Environment, Stack
+    from aws_cdk import aws_s3 as s3
+    from cdk_application_tags import apply_application_tags_to_app
+
+    app = App()
+    apply_application_tags_to_app(
+        app,
+        tag_key="Application",
+        application_name="demo-llm-topic-modeller",
+        repository_url="https://github.com/example/repo.git",
+    )
+    stack = Stack(
+        app,
+        "TagTestStack",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    s3.Bucket(stack, "TaggedBucket")
+
+    template = app.synth().get_stack_by_name("TagTestStack").template
+    buckets = [
+        r for r in template["Resources"].values() if r["Type"] == "AWS::S3::Bucket"
+    ]
+    assert buckets
+    tags = buckets[0]["Properties"].get("Tags", [])
+    tag_map = {t["Key"]: t["Value"] for t in tags}
+    assert tag_map.get("Application") == "demo-llm-topic-modeller"
+    assert tag_map.get("ManagedBy") == "cdk"
+    assert tag_map.get("Repository") == "https://github.com/example/repo.git"
+
+
+def test_create_application_resource_group_synth():
+    from aws_cdk import App, Environment, Stack
+    from cdk_application_tags import create_application_resource_group
+
+    app = App()
+    stack = Stack(
+        app,
+        "ResourceGroupTest",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    create_application_resource_group(
+        stack,
+        "ApplicationResourceGroup",
+        group_name="demo-llm-topic-modeller-resources",
+        tag_key="Application",
+        application_name="demo-llm-topic-modeller",
+    )
+
+    template = app.synth().get_stack_by_name("ResourceGroupTest").template
+    groups = [
+        r
+        for r in template["Resources"].values()
+        if r["Type"] == "AWS::ResourceGroups::Group"
+    ]
+    assert len(groups) == 1
+    props = groups[0]["Properties"]
+    assert props["Name"] == "demo-llm-topic-modeller-resources"
+    assert all(
+        character.isalnum() or character in " _.-" for character in props["Description"]
+    )
+    assert props["ResourceQuery"]["Type"] == "TAG_FILTERS_1_0"
+    tag_filters = props["ResourceQuery"]["Query"]["TagFilters"]
+    assert any(
+        f.get("Key") == "Application"
+        and "demo-llm-topic-modeller" in f.get("Values", [])
+        for f in tag_filters
+    )
+    outputs = template.get("Outputs", {})
+    assert any("ApplicationResourceGroup" in name for name in outputs)

cdk/test/test_bedrock_model_invocation_logging.py

@@ -0,0 +1,106 @@
+"""Synth coverage for Bedrock model invocation logging (S3 + CloudWatch)."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+
+def test_add_bedrock_s3_policy_documents_prefix_paths():
+    from aws_cdk import App, Environment, Stack
+    from aws_cdk import aws_s3 as s3
+    from cdk_functions import add_bedrock_model_invocation_s3_bucket_policy
+
+    app = App()
+    stack = Stack(
+        app,
+        "BedrockS3PolicyTest",
+        env=Environment(account="063418083240", region="eu-west-2"),
+    )
+    bucket = s3.Bucket(stack, "LogBucket", bucket_name="test-summarisation-s3-logs")
+    add_bedrock_model_invocation_s3_bucket_policy(
+        bucket,
+        region="eu-west-2",
+        account="063418083240",
+        key_prefix="bedrock-logs",
+    )
+
+    template = app.synth().get_stack_by_name("BedrockS3PolicyTest").template
+    policies = [
+        r
+        for r in template["Resources"].values()
+        if r["Type"] == "AWS::S3::BucketPolicy"
+    ]
+    assert policies
+    blob = str(policies)
+    assert "bedrock.amazonaws.com" in blob
+    assert "BedrockModelInvocationLogs" in blob
+    assert "bedrock-logs" in blob
+    assert "063418083240" in blob
+
+
+def test_create_bedrock_model_invocation_logging_synth():
+    from aws_cdk import App, Environment, RemovalPolicy, Stack
+    from aws_cdk import aws_kms as kms
+    from aws_cdk import aws_s3 as s3
+    from cdk_functions import create_bedrock_model_invocation_logging
+
+    app = App()
+    stack = Stack(
+        app,
+        "BedrockLoggingTest",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    key = kms.Key(stack, "SharedKey", removal_policy=RemovalPolicy.DESTROY)
+    bucket = s3.Bucket(
+        stack,
+        "LogBucket",
+        encryption=s3.BucketEncryption.KMS,
+        encryption_key=key,
+        removal_policy=RemovalPolicy.DESTROY,
+        auto_delete_objects=True,
+    )
+    create_bedrock_model_invocation_logging(
+        stack,
+        "BedrockModelInvocationLogging",
+        log_bucket=bucket,
+        region="eu-west-2",
+        account="123456789012",
+        key_prefix="bedrock-logs",
+        log_group_name="/aws/bedrock/test-model-invocations",
+        log_retention_days=90,
+        kms_key=key,
+    )
+
+    template = app.synth().get_stack_by_name("BedrockLoggingTest").template
+    resources = template["Resources"]
+    types = {r["Type"] for r in resources.values()}
+
+    assert "AWS::Logs::LogGroup" in types
+    assert "AWS::IAM::Role" in types
+    assert "AWS::S3::BucketPolicy" in types
+    assert "Custom::AWS" in types or any(
+        "Custom::AWS" in r.get("Type", "") for r in resources.values()
+    )
+
+    log_groups = [r for r in resources.values() if r["Type"] == "AWS::Logs::LogGroup"]
+    assert any(
+        r["Properties"].get("LogGroupName") == "/aws/bedrock/test-model-invocations"
+        for r in log_groups
+    )
+
+    roles = [r for r in resources.values() if r["Type"] == "AWS::IAM::Role"]
+    bedrock_roles = [
+        r
+        for r in roles
+        if "bedrock.amazonaws.com"
+        in str(r["Properties"].get("AssumeRolePolicyDocument", {}))
+    ]
+    assert bedrock_roles
+
+    policy_blob = str(
+        [r for r in resources.values() if r["Type"] == "AWS::IAM::Policy"]
+        + [r for r in resources.values() if r["Type"] == "AWS::KMS::Key"]
+    )
+    assert "GenerateDataKey" in policy_blob or "kms:GenerateDataKey" in str(resources)

cdk/test/test_cdk_install.py

@@ -0,0 +1,1116 @@
+"""Unit tests for cdk_install.py (no live AWS or cdk deploy)."""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+import cdk_install as inst
+
+
+def _demo_answers() -> inst.InstallAnswers:
+    return inst.InstallAnswers(
+        profile="demo",
+        aws_account_id="123456789012",
+        aws_region="eu-west-2",
+        cdk_prefix="Test-Summarisation-",
+        cognito_domain_prefix="test-summarisation",
+        vpc_mode="existing",
+        vpc_name="test-vpc",
+        public_subnet_mode="auto",
+        private_subnet_mode="auto",
+    )
+
+
+def _production_answers() -> inst.InstallAnswers:
+    a = _demo_answers()
+    a.profile = "production"
+    a.acm_cert_arn = "arn:aws:acm:eu-west-2:123:certificate/abc"
+    a.ssl_domain = "summarisation.example.com"
+    a.cloudfront_geo = "GB"
+    return a
+
+
+def _headless_answers() -> inst.InstallAnswers:
+    return inst.InstallAnswers(
+        profile="headless",
+        aws_account_id="123456789012",
+        aws_region="eu-west-2",
+        cdk_prefix="Headless-Summarisation-",
+        cognito_domain_prefix="headless-summarisation",
+        vpc_mode="existing",
+        vpc_name="test-vpc",
+        public_subnet_mode="auto",
+        private_subnet_mode="auto",
+        enable_s3_batch=True,
+    )
+
+
+def test_default_cognito_domain_prefix_strips_reserved_words_from_cdk_prefix():
+    prefix = inst.default_cognito_domain_prefix_from_cdk_prefix(
+        "Lambeth-AWS-SharedServices-Dev-Summarisation-"
+    )
+    assert prefix == "lambeth-sharedservic"
+    assert "aws" not in prefix
+    assert "amazon" not in prefix
+    assert "cognito" not in prefix
+
+
+def test_sanitize_cognito_domain_prefix_removes_reserved_substrings():
+    assert (
+        inst.sanitize_cognito_domain_prefix("lambeth-aws-sharedse")
+        == "lambeth-sharedse"
+    )
+    assert inst.sanitize_cognito_domain_prefix("my-cognito-login") == "my-login"
+    assert (
+        inst.sanitize_cognito_domain_prefix("amazon-summarisation-dev")
+        == "summarisation-dev"
+    )
+    assert inst.sanitize_cognito_domain_prefix("aws") == "llm-topic-app"
+
+
+def test_validate_cognito_domain_prefix_rejects_reserved_words():
+    assert inst.validate_cognito_domain_prefix("lambeth-aws-sharedse") is not None
+    assert inst.validate_cognito_domain_prefix("lambeth-sharedse-dev") is None
+
+
+def test_build_env_values_demo():
+    values = inst.build_env_values(_demo_answers())
+    assert values["USE_ECS_EXPRESS_MODE"] == "True"
+    assert values["ECS_EXPRESS_USE_PUBLIC_SUBNETS"] == "True"
+    assert values["PRIVATE_SUBNETS_TO_USE"] == ""
+    assert values["USE_CLOUDFRONT"] == "False"
+    assert values["ENABLE_RESOURCE_DELETE_PROTECTION"] == "False"
+    assert values["ENABLE_APPREGISTRY"] == "False"
+    assert values["ENABLE_APPLICATION_RESOURCE_GROUP"] == "True"
+    assert values["APPLICATION_TAG_KEY"] == "Application"
+    assert values["APPLICATION_NAME"].endswith("llm-topic-modeller")
+    assert values["APPLICATION_RESOURCE_GROUP_NAME"].endswith(
+        "llm-topic-modeller-resources"
+    )
+    assert values["VPC_NAME"] == "test-vpc"
+    assert values["CONTEXT_FILE"] == "precheck.context.json"
+    assert values["CDK_FOLDER"].endswith("/cdk/")
+
+
+def test_build_env_values_appregistry_opt_in():
+    answers = _demo_answers()
+    answers.enable_appregistry = True
+    answers.application_name = "demo-llm-topic-modeller"
+    values = inst.build_env_values(answers)
+    assert values["ENABLE_APPREGISTRY"] == "True"
+    assert values["APPREGISTRY_STACK_NAME"].endswith("AppRegistryStack")
+    assert values["APPREGISTRY_APPLICATION_NAME"] == "demo-llm-topic-modeller"
+
+
+def test_build_env_values_disable_application_resource_group():
+    answers = _headless_answers()
+    answers.enable_application_resource_group = False
+    values = inst.build_env_values(answers)
+    assert values["ENABLE_APPLICATION_RESOURCE_GROUP"] == "False"
+    assert values["APPLICATION_NAME"]
+    assert values["ENABLE_APPREGISTRY"] == "False"
+
+
+def test_default_application_name():
+    assert (
+        inst.default_application_name("Demo-Summarisation-")
+        == "Demo-Summarisation-llm-topic-modeller"
+    )
+
+
+def test_build_env_values_production():
+    values = inst.build_env_values(_production_answers())
+    assert values["USE_ECS_EXPRESS_MODE"] == "False"
+    assert values["USE_CLOUDFRONT"] == "True"
+    assert values["RUN_USEAST_STACK"] == "True"
+    assert values["ENABLE_RESOURCE_DELETE_PROTECTION"] == "True"
+    assert values["ACM_SSL_CERTIFICATE_ARN"].startswith("arn:aws:acm:")
+    assert values["SSL_CERTIFICATE_DOMAIN"] == "summarisation.example.com"
+    assert values["ENABLE_APPREGISTRY"] == "False"
+    assert "APPREGISTRY_STACK_NAME" not in values
+    assert values["ENABLE_APPLICATION_RESOURCE_GROUP"] == "True"
+    assert values["APPLICATION_NAME"] == "Test-Summarisation-llm-topic-modeller"
+
+
+def test_build_env_values_uses_custom_s3_bucket_names():
+    answers = _demo_answers()
+    answers.s3_log_bucket_name = "063418083240-demo-summarisation-s3-logs"
+    answers.s3_output_bucket_name = "063418083240-demo-summarisation-s3-output"
+    values = inst.build_env_values(answers)
+    assert (
+        values["S3_LOG_CONFIG_BUCKET_NAME"] == "063418083240-demo-summarisation-s3-logs"
+    )
+    assert (
+        values["S3_OUTPUT_BUCKET_NAME"] == "063418083240-demo-summarisation-s3-output"
+    )
+
+
+def test_normalize_s3_bucket_name_truncates_and_sanitizes():
+    long_name = "A" * 80 + "/underscores"
+    normalized = inst.normalize_s3_bucket_name(long_name)
+    assert normalized == normalized.lower()
+    assert len(normalized) <= inst.S3_BUCKET_NAME_MAX_LEN
+    assert "_" not in normalized
+
+
+def test_suggest_available_s3_bucket_name_prefers_account_prefix(monkeypatch):
+    calls: list[str] = []
+
+    def fake_resolve(name: str, **kwargs):
+        calls.append(name)
+        if name.startswith("123456789012-"):
+            return ("available", name)
+        return ("globally_taken", name)
+
+    monkeypatch.setattr("cdk_functions.resolve_s3_bucket_availability", fake_resolve)
+    suggested = inst.suggest_available_s3_bucket_name(
+        "demo-summarisation-s3-logs", "123456789012"
+    )
+    assert suggested == "123456789012-demo-summarisation-s3-logs"
+    assert calls[0] == "demo-summarisation-s3-logs"
+
+
+def test_validate_globally_unique_env_values_flags_taken_bucket(monkeypatch):
+    monkeypatch.setattr(
+        "cdk_functions.resolve_s3_bucket_availability",
+        lambda name, **kwargs: ("globally_taken", name),
+    )
+    monkeypatch.setattr(
+        "cdk_functions.resolve_cognito_domain_prefix_availability",
+        lambda prefix, **kwargs: "available",
+    )
+    values = inst.build_env_values(_demo_answers())
+    errors = inst.validate_globally_unique_env_values(values)
+    assert any("taken globally" in err for err in errors)
+
+
+def test_prompt_globally_unique_cognito_prefix_suggests_when_taken(monkeypatch):
+    monkeypatch.setattr(
+        "cdk_functions.resolve_cognito_domain_prefix_availability",
+        lambda prefix, **kwargs: (
+            "taken" if prefix == "demo-summarisation" else "available"
+        ),
+    )
+    monkeypatch.setattr(
+        inst,
+        "suggest_available_cognito_domain_prefix",
+        lambda preferred, account_id, region, **kwargs: "063418083240-demo-summarisation",
+    )
+    monkeypatch.setattr(inst, "ask_yes_no", lambda *args, **kwargs: True)
+    result = inst._prompt_globally_unique_cognito_prefix(
+        "demo-summarisation",
+        "063418083240",
+        "eu-west-2",
+        interactive=True,
+        assume_yes=False,
+    )
+    assert result == "063418083240-demo-summarisation"
+
+
+def test_prompt_globally_unique_cognito_prefix_rejects_taken_cli_override(monkeypatch):
+    monkeypatch.setattr(
+        "cdk_functions.resolve_cognito_domain_prefix_availability",
+        lambda prefix, **kwargs: "taken",
+    )
+    with pytest.raises(SystemExit):
+        inst._prompt_globally_unique_cognito_prefix(
+            "demo-summarisation",
+            "063418083240",
+            "eu-west-2",
+            interactive=False,
+            assume_yes=False,
+            cli_override="demo-summarisation",
+        )
+
+
+def test_subnet_cidr_prefix_len_for_express_demo():
+    answers = _demo_answers()
+    assert inst.subnet_cidr_prefix_len_for_tier(answers, "public") == 27
+    assert inst.subnet_cidr_prefix_len_for_tier(answers, "private") == 28
+
+
+def test_validate_public_subnet_cidr_for_express_rejects_small_blocks():
+    assert inst.validate_public_subnet_cidr_for_express("10.0.0.0/28") is not None
+    assert inst.validate_public_subnet_cidr_for_express("10.0.0.0/27") is None
+    assert inst.validate_public_subnet_cidr_for_express("10.0.0.0/26") is None
+
+
+def test_validate_env_values_rejects_express_public_subnets_too_small():
+    values = inst.build_env_values(_demo_answers())
+    values["PUBLIC_SUBNET_CIDR_BLOCKS"] = "['10.0.0.0/28', '10.0.0.16/28']"
+    errors = inst.validate_env_values(values)
+    assert any("too small for ECS Express" in err for err in errors)
+
+
+def test_build_env_values_headless():
+    values = inst.build_env_values(_headless_answers())
+    assert values["USE_ECS_EXPRESS_MODE"] == "False"
+    assert values["USE_CLOUDFRONT"] == "False"
+    assert values["RUN_USEAST_STACK"] == "False"
+    assert values["ENABLE_HEADLESS_DEPLOYMENT"] == "True"
+    assert values["ENABLE_S3_BATCH_ECS_TRIGGER"] == "True"
+    assert values["COGNITO_AUTH"] == "False"
+    assert values["ECS_EXPRESS_USE_PUBLIC_SUBNETS"] == "True"
+    assert values["PRIVATE_SUBNETS_TO_USE"] == ""
+    assert values["S3_LOG_CONFIG_BUCKET_NAME"] == "headless-summarisation-s3-logs"
+    assert values["S3_OUTPUT_BUCKET_NAME"] == "headless-summarisation-s3-output"
+    assert "ENABLE_BEDROCK_MODEL_INVOCATION_LOGGING" not in values
+
+
+def test_build_env_values_bedrock_model_invocation_logging():
+    answers = _headless_answers()
+    answers.enable_bedrock_model_invocation_logging = True
+    answers.bedrock_invocation_s3_prefix = "bedrock-logs"
+    answers.bedrock_invocation_log_group_name = (
+        "/aws/bedrock/headless-model-invocations"
+    )
+    answers.bedrock_invocation_log_retention_days = "30"
+    values = inst.build_env_values(answers)
+    assert values["ENABLE_BEDROCK_MODEL_INVOCATION_LOGGING"] == "True"
+    assert values["BEDROCK_MODEL_INVOCATION_S3_PREFIX"] == "bedrock-logs"
+    assert (
+        values["BEDROCK_MODEL_INVOCATION_LOG_GROUP_NAME"]
+        == "/aws/bedrock/headless-model-invocations"
+    )
+    assert values["BEDROCK_MODEL_INVOCATION_LOG_RETENTION_DAYS"] == "30"
+
+
+def test_validate_install_answers_bedrock_logging_requires_prefix():
+    answers = _headless_answers()
+    answers.enable_bedrock_model_invocation_logging = True
+    answers.bedrock_invocation_s3_prefix = ""
+    answers.bedrock_invocation_log_group_name = "/aws/bedrock/test"
+    errors = inst.validate_install_answers(answers)
+    assert any("S3 key prefix" in err for err in errors)
+
+
+def test_build_env_values_bedrock_guardrails():
+    answers = _headless_answers()
+    answers.enable_bedrock_guardrails = True
+    answers.bedrock_guardrail_identifier = "gr-abc123"
+    answers.bedrock_guardrail_version = "2"
+    answers.bedrock_guardrail_trace = "enabled"
+    values = inst.build_env_values(answers)
+    assert values["ENABLE_BEDROCK_GUARDRAILS"] == "True"
+    assert values["BEDROCK_GUARDRAIL_IDENTIFIER"] == "gr-abc123"
+    assert values["BEDROCK_GUARDRAIL_VERSION"] == "2"
+    assert values["BEDROCK_GUARDRAIL_TRACE"] == "enabled"
+
+
+def test_build_app_config_env_values_includes_bedrock_guardrails():
+    answers = _headless_answers()
+    answers.enable_bedrock_guardrails = True
+    answers.bedrock_guardrail_identifier = "gr-abc123"
+    answers.bedrock_guardrail_version = "1"
+    answers.bedrock_guardrail_trace = "disabled"
+    values = inst.build_env_values(answers)
+    updates = inst.build_app_config_env_values(values)
+    assert updates["ENABLE_BEDROCK_GUARDRAILS"] == "True"
+    assert updates["BEDROCK_GUARDRAIL_IDENTIFIER"] == "gr-abc123"
+
+
+def test_validate_install_answers_bedrock_guardrails_requires_id_and_version():
+    answers = _headless_answers()
+    answers.enable_bedrock_guardrails = True
+    answers.bedrock_guardrail_identifier = ""
+    answers.bedrock_guardrail_version = ""
+    errors = inst.validate_install_answers(answers)
+    assert any("GUARDRAIL_IDENTIFIER" in err for err in errors)
+    assert any("GUARDRAIL_VERSION" in err for err in errors)
+
+
+def test_default_bedrock_invocation_log_group_name():
+    assert (
+        inst.default_bedrock_invocation_log_group_name("Headless-Summarisation-")
+        == "/aws/bedrock/Headless-Summarisation-model-invocations"
+    )
+
+
+def test_validate_env_values_rejects_bare_s3_bucket_names():
+    values = inst.build_env_values(_headless_answers())
+    values["S3_LOG_CONFIG_BUCKET_NAME"] = "s3-logs"
+    errors = inst.validate_env_values(values)
+    assert any("S3_LOG_CONFIG_BUCKET_NAME" in e for e in errors)
+
+
+def test_headless_profile_uses_public_subnets_only():
+    assert inst.answers_use_public_subnets_only(_headless_answers()) is True
+
+
+def test_build_env_values_production_headless():
+    answers = _production_answers()
+    answers.enable_headless = True
+    values = inst.build_env_values(answers)
+    assert values["USE_ECS_EXPRESS_MODE"] == "False"
+    assert values["USE_CLOUDFRONT"] == "False"
+    assert values["ENABLE_HEADLESS_DEPLOYMENT"] == "True"
+    assert values["ENABLE_RESOURCE_DELETE_PROTECTION"] == "True"
+    assert values.get("ECS_EXPRESS_USE_PUBLIC_SUBNETS") != "True"
+    assert "PRIVATE_SUBNET_CIDR_BLOCKS" in values
+
+
+def test_validate_install_answers_rejects_demo_headless():
+    answers = _demo_answers()
+    answers.enable_headless = True
+    errors = inst.validate_install_answers(answers)
+    assert any("Demonstration" in err for err in errors)
+
+
+def test_validate_install_answers_rejects_custom_express_headless():
+    answers = inst.InstallAnswers(profile="custom", enable_headless=True)
+    answers.custom_overrides["USE_ECS_EXPRESS_MODE"] = "True"
+    errors = inst.validate_install_answers(answers)
+    assert any("USE_ECS_EXPRESS_MODE=False" in err for err in errors)
+
+
+def test_profile_allows_headless_add_on():
+    assert inst.profile_allows_headless_add_on(_demo_answers()) is False
+    assert inst.profile_allows_headless_add_on(_production_answers()) is True
+    assert inst.profile_allows_headless_add_on(_headless_answers()) is True
+    custom = inst.InstallAnswers(profile="custom")
+    assert inst.profile_allows_headless_add_on(custom) is True
+    custom.custom_overrides["USE_ECS_EXPRESS_MODE"] = "True"
+    assert inst.profile_allows_headless_add_on(custom) is False
+
+
+def test_validate_install_answers_skips_cognito_prefix_for_headless():
+    values = inst.build_env_values(_headless_answers())
+    values["COGNITO_USER_POOL_DOMAIN_PREFIX"] = ""
+    assert inst.validate_env_values(values) == []
+
+
+def test_validate_headless_rejects_pi():
+    values = inst.build_env_values(_headless_answers())
+    values["ENABLE_ECS_SERVICE_CONNECT"] = "True"
+    errors = inst.validate_env_values(values)
+    assert any("HEADLESS" in e for e in errors)
+
+
+def test_validate_rejects_express_with_acm():
+    values = inst.build_env_values(_demo_answers())
+    values["ACM_SSL_CERTIFICATE_ARN"] = "arn:aws:acm:eu-west-2:123:certificate/x"
+    errors = inst.validate_env_values(values)
+    assert any("ACM_SSL_CERTIFICATE_ARN" in e for e in errors)
+
+
+def test_build_env_values_mixed_subnet_tiers():
+    answers = _production_answers()
+    answers.public_subnet_mode = "existing"
+    answers.private_subnet_mode = "create"
+    answers.public_subnet_names = ["existing-public-a", "existing-public-b"]
+    answers.public_subnet_cidrs = ["10.244.1.0/28", "10.244.2.0/28"]
+    answers.public_subnet_azs = ["eu-west-2a", "eu-west-2b"]
+    answers.private_subnet_names = ["Demo-Summarisation-PrivateSubnet1"]
+    answers.private_subnet_cidrs = ["10.0.10.0/28"]
+    answers.private_subnet_azs = ["eu-west-2a"]
+    values = inst.build_env_values(answers)
+    assert (
+        values["PUBLIC_SUBNETS_TO_USE"] == '["existing-public-a", "existing-public-b"]'
+    )
+    assert values["PUBLIC_SUBNET_CIDR_BLOCKS"] == "['10.244.1.0/28', '10.244.2.0/28']"
+    assert values["PUBLIC_SUBNET_AVAILABILITY_ZONES"] == "['eu-west-2a', 'eu-west-2b']"
+    assert values["PRIVATE_SUBNETS_TO_USE"] == '["Demo-Summarisation-PrivateSubnet1"]'
+    assert values["PRIVATE_SUBNET_CIDR_BLOCKS"] == "['10.0.10.0/28']"
+    assert values["PRIVATE_SUBNET_AVAILABILITY_ZONES"] == "['eu-west-2a']"
+
+
+def test_enrich_existing_subnet_details_from_aws(monkeypatch):
+    answers = _demo_answers()
+    answers.vpc_name = "test-vpc"
+    answers.public_subnet_mode = "existing"
+    answers.public_subnet_names = ["pub-a", "pub-b"]
+    answers.private_subnet_mode = "create"
+
+    monkeypatch.setattr(
+        inst,
+        "list_vpcs",
+        lambda _region: [{"name": "test-vpc", "id": "vpc-123", "cidr": "10.0.0.0/16"}],
+    )
+    monkeypatch.setattr(
+        inst,
+        "list_subnets_in_vpc",
+        lambda _vpc_id, _region: [
+            {"name": "pub-a", "cidr": "10.244.1.0/28", "az": "eu-west-2a"},
+            {"name": "pub-b", "cidr": "10.244.2.0/28", "az": "eu-west-2b"},
+        ],
+    )
+
+    errors = inst.enrich_existing_subnet_details_from_aws(answers)
+    assert errors == []
+    assert answers.public_subnet_cidrs == ["10.244.1.0/28", "10.244.2.0/28"]
+    assert answers.public_subnet_azs == ["eu-west-2a", "eu-west-2b"]
+
+
+def test_validate_subnet_answers_mixed_requires_public_names():
+    answers = _demo_answers()
+    answers.public_subnet_mode = "existing"
+    answers.private_subnet_mode = "create"
+    answers.private_subnet_names = ["new-private"]
+    errors = inst.validate_subnet_answers(answers)
+    assert any("Public subnets" in err for err in errors)
+
+
+def test_resolve_subnet_tier_modes_per_tier_override():
+    args = argparse.Namespace(
+        subnet_mode="auto",
+        public_subnet_mode="existing",
+        private_subnet_mode="create",
+    )
+    public, private = inst.resolve_subnet_tier_modes(args)
+    assert public == "existing"
+    assert private == "create"
+
+
+def test_suggest_vpc_cidr_block_empty_region():
+    assert inst.suggest_vpc_cidr_block([]) == "10.0.0.0/24"
+
+
+def test_suggest_vpc_cidr_block_skips_overlaps():
+    assert inst.suggest_vpc_cidr_block(["10.0.0.0/24"]) == "10.0.1.0/24"
+    assert inst.suggest_vpc_cidr_block(["10.0.0.0/16"]) == "10.1.0.0/24"
+
+
+def test_validate_new_vpc_cidr_rejects_overlap_and_public_space():
+    err = inst.validate_new_vpc_cidr("10.0.0.0/24", ["10.0.0.0/16"])
+    assert err is not None
+    assert "overlaps" in err
+    err = inst.validate_new_vpc_cidr("8.8.8.0/24", [])
+    assert err is not None
+    assert "RFC1918" in err
+
+
+def test_validate_new_vpc_cidr_accepts_available_block():
+    assert inst.validate_new_vpc_cidr("10.2.0.0/24", ["10.0.0.0/16"]) is None
+
+
+def test_prompt_new_vpc_cidr_validates_cli_override(monkeypatch):
+    answers = inst.InstallAnswers(aws_region="eu-west-2", new_vpc_cidr="10.0.0.0/24")
+    monkeypatch.setattr(
+        inst, "list_vpc_cidr_blocks_in_region", lambda _r: ["10.0.0.0/16"]
+    )
+    with pytest.raises(SystemExit):
+        inst.prompt_new_vpc_cidr(answers, interactive=False)
+
+
+def test_prompt_new_vpc_cidr_auto_select_noninteractive(monkeypatch):
+    answers = inst.InstallAnswers(aws_region="eu-west-2")
+    monkeypatch.setattr(inst, "list_vpc_cidr_blocks_in_region", lambda _r: [])
+    inst.prompt_new_vpc_cidr(answers, interactive=False)
+    assert answers.new_vpc_cidr == "10.0.0.0/24"
+
+
+def test_suggest_subnet_cidr_blocks_lowest_available():
+    blocks = inst.suggest_subnet_cidr_blocks("10.0.0.0/24", ["10.0.0.0/28"], 2)
+    assert blocks == ["10.0.0.16/28", "10.0.0.32/28"]
+
+
+def test_suggest_subnet_cidr_blocks_respects_reserved():
+    blocks = inst.suggest_subnet_cidr_blocks(
+        "10.0.0.0/24",
+        [],
+        1,
+        reserved_cidrs=["10.0.0.0/28"],
+    )
+    assert blocks == ["10.0.0.16/28"]
+
+
+def test_vpc_cidr_blocks_from_describe_includes_associations():
+    vpc = {
+        "CidrBlock": "10.0.0.0/16",
+        "CidrBlockAssociationSet": [{"CidrBlock": "10.1.0.0/16"}],
+    }
+    assert inst.vpc_cidr_blocks_from_describe(vpc) == [
+        "10.0.0.0/16",
+        "10.1.0.0/16",
+    ]
+
+
+def test_build_app_config_env_values_express_uses_in_app_cognito():
+    values = inst.build_env_values(_demo_answers())
+    updates = inst.build_app_config_env_values(values)
+    assert updates["COGNITO_AUTH"] == "True"
+    assert updates["RUN_AWS_FUNCTIONS"] == "True"
+    assert updates["S3_LOG_BUCKET"].endswith("s3-logs")
+
+
+def test_build_app_config_env_values_express_pi_disables_main_cognito():
+    values = inst.build_env_values(_demo_answers())
+    values["ENABLE_PI_AGENT_EXPRESS_SERVICE"] = "True"
+    updates = inst.build_app_config_env_values(values)
+    assert updates["COGNITO_AUTH"] == "False"
+
+
+def test_build_app_config_env_values_headless():
+    answers = _headless_answers()
+    values = inst.build_env_values(answers)
+    updates = inst.build_app_config_env_values(values)
+    assert updates["COGNITO_AUTH"] == "False"
+
+
+def test_write_app_config_env_from_example(tmp_path, monkeypatch):
+    example = tmp_path / "app_config.env.example"
+    example.write_text(
+        "RUN_AWS_FUNCTIONS=True\nS3_LOG_BUCKET=placeholder\n",
+        encoding="utf-8",
+    )
+    target = tmp_path / "app_config.env"
+    monkeypatch.setattr(inst, "APP_CONFIG_ENV_EXAMPLE", example)
+    monkeypatch.setattr(inst, "APP_CONFIG_ENV_PATH", target)
+
+    answers = _demo_answers()
+    answers.write_app_config_env = True
+    values = inst.build_env_values(answers)
+    inst.write_app_config_env_file(answers, values)
+
+    written = inst.read_env_file(target)
+    assert written["RUN_AWS_FUNCTIONS"] == "True"
+    assert written["S3_LOG_BUCKET"].endswith("s3-logs")
+    assert written["COGNITO_AUTH"] == "True"
+
+
+def test_format_list_env():
+    assert inst.format_list_env(["a", "b"]) == '["a", "b"]'
+    assert (
+        inst.format_list_env(["10.0.0.0/28"], use_single_quotes=True)
+        == "['10.0.0.0/28']"
+    )
+    assert inst.format_list_env([]) == "[]"
+
+
+def test_write_env_file_backs_up(tmp_path):
+    env_path = tmp_path / "cdk_config.env"
+    env_path.write_text("OLD=1\n", encoding="utf-8")
+    inst.write_env_file(env_path, {"NEW": "2"})
+    backups = list(tmp_path.glob("cdk_config.env.bak.*"))
+    assert len(backups) == 1
+    assert "NEW=2" in env_path.read_text(encoding="utf-8")
+
+
+def test_write_cdk_json_preserves_context(tmp_path, monkeypatch):
+    cdk_json = tmp_path / "cdk.json"
+    cdk_json.write_text(
+        json.dumps(
+            {
+                "app": "old-python app.py",
+                "context": {"@aws-cdk/custom:flag": True, "keep": 1},
+            }
+        ),
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(inst, "CDK_JSON_PATH", cdk_json)
+    monkeypatch.setattr(inst, "CDK_JSON_EXAMPLE", tmp_path / "missing.example")
+
+    py = Path(sys.executable)
+    inst.write_cdk_json(py, force=True)
+
+    data = json.loads(cdk_json.read_text(encoding="utf-8"))
+    assert data["context"]["@aws-cdk/custom:flag"] is True
+    assert data["context"]["keep"] == 1
+    assert data["app"].endswith("app.py")
+    assert "output" in data
+    backups = list(tmp_path.glob("cdk.json.bak.*"))
+    assert len(backups) == 1
+
+
+def test_format_cdk_app_command():
+    cmd = inst.format_cdk_app_command(Path(sys.executable))
+    assert cmd.endswith("app.py")
+    assert str(sys.executable).replace("/", "\\") in cmd or sys.executable in cmd
+
+
+def test_venv_python_paths_includes_sys_executable():
+    paths = inst._venv_python_paths()
+    assert Path(sys.executable).resolve() == paths[0].resolve()
+
+
+def test_merge_preset_custom():
+    merged = inst.merge_preset("demo", {"ECS_TASK_MEMORY_SIZE": "8192"})
+    assert merged["USE_ECS_EXPRESS_MODE"] == "True"
+    assert merged["ECS_TASK_MEMORY_SIZE"] == "8192"
+
+
+def test_build_env_values_pi_express_forced_off():
+    answers = _demo_answers()
+    answers.enable_pi_express = True
+    values = inst.build_env_values(answers)
+    assert values["ENABLE_PI_AGENT_EXPRESS_SERVICE"] == "False"
+    assert values["ENABLE_PI_AGENT_ECS_SERVICE"] == "False"
+
+
+def test_build_pi_agent_env_values_express_skips_root_path():
+    answers = _demo_answers()
+    answers.enable_pi_express = True
+    env = inst.build_pi_agent_env_values(answers)
+    assert env["RUN_FASTAPI"] == "True"
+    assert "PI_ROOT_PATH" not in env
+
+
+def test_build_env_values_pi_production_host_forced_off():
+    answers = _production_answers()
+    answers.enable_pi_legacy = True
+    answers.enable_service_connect = True
+    answers.pi_alb_routing = "host"
+    answers.pi_alb_host_header = "agent.example.com"
+    values = inst.build_env_values(answers)
+    assert values["ENABLE_PI_AGENT_ECS_SERVICE"] == "False"
+    assert values["ENABLE_PI_AGENT_EXPRESS_SERVICE"] == "False"
+
+
+def test_validate_pi_host_requires_header():
+    values = inst.build_env_values(_production_answers())
+    values["ENABLE_PI_AGENT_ECS_SERVICE"] = "True"
+    values["ENABLE_ECS_SERVICE_CONNECT"] = "True"
+    values["PI_ALB_ROUTING"] = "host"
+    values["PI_ALB_HOST_HEADER"] = ""
+    errors = inst.validate_env_values(values)
+    assert any("PI_ALB_HOST_HEADER" in e for e in errors)
+
+
+def test_validate_pi_express_skips_alb_routing():
+    values = inst.build_env_values(_demo_answers())
+    values["ENABLE_PI_AGENT_EXPRESS_SERVICE"] = "True"
+    values["USE_ECS_EXPRESS_MODE"] = "True"
+    assert inst.validate_env_values(values) == []
+
+
+def test_build_pi_agent_env_values():
+    answers = _demo_answers()
+    answers.enable_pi_express = False
+    answers.enable_pi_legacy = True
+    answers.pi_alb_routing = "path"
+    answers.pi_alb_path_prefix = "/pi"
+    values = inst.build_pi_agent_env_values(answers)
+    assert values["PI_DEPLOYMENT_PROFILE"] == "aws-ecs"
+    assert values["DOC_SUMMARISATION_GRADIO_URL"] == "http://llm-topic:7860"
+    assert values["PI_ROOT_PATH"] == "/pi"
+
+
+def test_apply_pi_cli_flags_enable_pi_demo():
+    answers = inst.InstallAnswers(profile="demo")
+    args = argparse.Namespace(
+        enable_pi=True,
+        enable_pi_express=False,
+        enable_pi_legacy=False,
+        pi_alb_routing=None,
+        pi_path_prefix="",
+        pi_host_header="",
+        pi_listener_priority="",
+        pi_gradio_port="",
+        sc_discovery_name="",
+        pi_provider="",
+        skip_pi_agent_env=False,
+    )
+    inst.apply_pi_cli_flags(args, answers)
+    assert answers.enable_pi_express is True
+
+
+def test_stacks_to_check_includes_appregistry_when_enabled():
+    checks = inst.stacks_to_check(
+        "eu-west-2",
+        {
+            "ENABLE_APPREGISTRY": "True",
+            "APPREGISTRY_STACK_NAME": "Demo-Summarisation-AppRegistryStack",
+        },
+    )
+    names = [name for name, _ in checks]
+    assert names == [
+        inst.CLOUDFRONT_STACK,
+        "Demo-Summarisation-AppRegistryStack",
+        inst.REGIONAL_STACK,
+    ]
+    assert checks[0][1] == inst.CLOUDFRONT_STACK_REGION
+    assert checks[-1] == (inst.REGIONAL_STACK, "eu-west-2")
+
+
+def test_stacks_to_check_without_appregistry():
+    checks = inst.stacks_to_check("eu-west-2", {"ENABLE_APPREGISTRY": "False"})
+    assert [name for name, _ in checks] == [
+        inst.CLOUDFRONT_STACK,
+        inst.REGIONAL_STACK,
+    ]
+
+
+def test_derived_appregistry_stack_name_from_cdk_prefix():
+    name = inst.derived_appregistry_stack_name(
+        {"CDK_PREFIX": "Demo-Summarisation-", "ENABLE_APPREGISTRY": "True"}
+    )
+    assert name == "Demo-Summarisation-AppRegistryStack"
+
+
+def test_stacks_to_check_derives_appregistry_from_cdk_prefix():
+    checks = inst.stacks_to_check(
+        "eu-west-2",
+        {
+            "CDK_PREFIX": "Demo-Summarisation-",
+            "ENABLE_APPREGISTRY": "True",
+        },
+    )
+    assert "Demo-Summarisation-AppRegistryStack" in [name for name, _ in checks]
+
+
+def test_stacks_to_check_skips_cloudfront_when_disabled():
+    checks = inst.stacks_to_check(
+        "eu-west-2",
+        {
+            "USE_CLOUDFRONT": "False",
+            "RUN_USEAST_STACK": "False",
+            "ENABLE_APPREGISTRY": "False",
+        },
+    )
+    assert checks == [(inst.REGIONAL_STACK, "eu-west-2")]
+
+
+def test_discover_existing_doc_summarisation_stacks_order(monkeypatch):
+    monkeypatch.setattr(
+        inst, "list_regional_appregistry_stack_names", lambda _region: []
+    )
+
+    def fake_describe(stack_name: str, region: str):
+        if stack_name == inst.REGIONAL_STACK and region == "eu-west-2":
+            return inst.ExistingStack(
+                name=stack_name,
+                region=region,
+                status="UPDATE_COMPLETE",
+            )
+        if (
+            stack_name == inst.CLOUDFRONT_STACK
+            and region == inst.CLOUDFRONT_STACK_REGION
+        ):
+            return inst.ExistingStack(
+                name=stack_name,
+                region=region,
+                status="CREATE_COMPLETE",
+                termination_protection=True,
+            )
+        return None
+
+    monkeypatch.setattr(inst, "describe_existing_stack", fake_describe)
+    found = inst.discover_existing_llm_topic_stacks("eu-west-2")
+    assert [s.name for s in found] == [inst.CLOUDFRONT_STACK, inst.REGIONAL_STACK]
+    assert found[0].termination_protection is True
+
+
+def test_discover_existing_stacks_continues_after_access_denied(monkeypatch):
+    from botocore.exceptions import ClientError
+
+    monkeypatch.setattr(
+        inst, "list_regional_appregistry_stack_names", lambda _region: []
+    )
+
+    def fake_describe(stack_name: str, region: str):
+        if (
+            stack_name == inst.CLOUDFRONT_STACK
+            and region == inst.CLOUDFRONT_STACK_REGION
+        ):
+            raise ClientError(
+                {
+                    "Error": {
+                        "Code": "AccessDenied",
+                        "Message": "explicit deny in SCP",
+                    }
+                },
+                "DescribeStacks",
+            )
+        if stack_name == inst.REGIONAL_STACK and region == "eu-west-2":
+            return inst.ExistingStack(
+                name=stack_name,
+                region=region,
+                status="UPDATE_COMPLETE",
+            )
+        return None
+
+    monkeypatch.setattr(inst, "describe_existing_stack", fake_describe)
+    found = inst.discover_existing_llm_topic_stacks("eu-west-2")
+    assert [s.name for s in found] == [inst.REGIONAL_STACK]
+
+
+def test_discover_includes_orphan_appregistry_when_disabled_in_config(monkeypatch):
+    monkeypatch.setattr(
+        inst,
+        "list_regional_appregistry_stack_names",
+        lambda _region: ["Old-Summarisation-AppRegistryStack"],
+    )
+
+    def fake_describe(stack_name: str, region: str):
+        if stack_name == "Old-Summarisation-AppRegistryStack":
+            return inst.ExistingStack(
+                name=stack_name,
+                region=region,
+                status="CREATE_COMPLETE",
+            )
+        return None
+
+    monkeypatch.setattr(inst, "describe_existing_stack", fake_describe)
+    found = inst.discover_existing_llm_topic_stacks(
+        "eu-west-2",
+        {"ENABLE_APPREGISTRY": "False"},
+    )
+    assert [s.name for s in found] == ["Old-Summarisation-AppRegistryStack"]
+
+
+def test_handle_existing_stacks_force_delete(monkeypatch):
+    stacks = [
+        inst.ExistingStack(
+            name=inst.CLOUDFRONT_STACK,
+            region=inst.CLOUDFRONT_STACK_REGION,
+            status="CREATE_COMPLETE",
+        )
+    ]
+    deleted: list = []
+
+    monkeypatch.setattr(
+        inst,
+        "discover_existing_llm_topic_stacks",
+        lambda *_a, **_k: stacks,
+    )
+    monkeypatch.setattr(
+        inst,
+        "force_delete_cloudformation_stacks",
+        lambda s, **kwargs: deleted.extend(s),
+    )
+
+    args = argparse.Namespace(
+        skip_stack_check=False,
+        config_only=False,
+        synth_only=False,
+        force_delete_stacks=True,
+        yes=True,
+    )
+    inst.handle_existing_stacks_at_start(args, "eu-west-2")
+    assert deleted == stacks
+
+
+def test_handle_existing_stacks_yes_without_force_skips_delete(monkeypatch):
+    monkeypatch.setattr(
+        inst,
+        "discover_existing_llm_topic_stacks",
+        lambda *_a, **_k: [
+            inst.ExistingStack(
+                name=inst.REGIONAL_STACK,
+                region="eu-west-2",
+                status="CREATE_COMPLETE",
+            )
+        ],
+    )
+    monkeypatch.setattr(
+        inst,
+        "force_delete_cloudformation_stacks",
+        lambda *_a, **_k: (_ for _ in ()).throw(AssertionError("should not delete")),
+    )
+
+    args = argparse.Namespace(
+        skip_stack_check=False,
+        config_only=False,
+        synth_only=False,
+        force_delete_stacks=False,
+        yes=True,
+    )
+    inst.handle_existing_stacks_at_start(args, "eu-west-2")
+
+
+def test_write_pi_agent_env_file_minimal(tmp_path, monkeypatch):
+    answers = _demo_answers()
+    answers.enable_pi_express = True
+    target = tmp_path / "pi_agent.env"
+    monkeypatch.setattr(inst, "PI_AGENT_ENV_PATH", target)
+    monkeypatch.setattr(inst, "PI_AGENT_ENV_EXAMPLE", tmp_path / "missing.example")
+    inst.write_pi_agent_env_file(answers)
+    text = target.read_text(encoding="utf-8")
+    assert "PI_DEPLOYMENT_PROFILE=aws-ecs" in text
+    assert "DOC_SUMMARISATION_GRADIO_URL=http://llm-topic:7860" in text
+
+
+def test_run_cdk_command_invokes_cdk_cli_not_python(monkeypatch):
+    calls: list = []
+
+    def fake_run(cmd, **kwargs):
+        calls.append((cmd, kwargs))
+        return subprocess.CompletedProcess(cmd, 0)
+
+    monkeypatch.setattr(inst, "resolve_cdk_executable", lambda: r"C:\npm\cdk.cmd")
+    monkeypatch.setattr(inst.subprocess, "run", fake_run)
+    inst.run_cdk_command(["synth"], check=False)
+    cmd, kwargs = calls[0]
+    assert cmd == [r"C:\npm\cdk.cmd", "synth"]
+    assert "executable" not in kwargs
+
+
+def test_build_cdk_subprocess_env_overrides_stale_defaults(tmp_path, monkeypatch):
+    env_path = tmp_path / "config" / "cdk_config.env"
+    env_path.parent.mkdir(parents=True)
+    env_path.write_text(
+        "VPC_NAME=my-vpc\nCDK_PREFIX=MyPrefix-\nAWS_REGION=eu-west-2\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(inst, "ENV_PATH", env_path)
+    monkeypatch.setattr(inst, "CDK_DIR", tmp_path)
+    monkeypatch.setenv("VPC_NAME", "")
+    monkeypatch.setenv("CDK_PREFIX", "")
+
+    env = inst.build_cdk_subprocess_env()
+    assert env["VPC_NAME"] == "my-vpc"
+    assert env["CDK_PREFIX"] == "MyPrefix-"
+    assert env["CDK_CONFIG_PATH"] == str(env_path)
+
+
+def test_apply_cdk_runtime_env_sets_paths(tmp_path, monkeypatch):
+    env_path = tmp_path / "cdk_config.env"
+    monkeypatch.setattr(inst, "ENV_PATH", env_path)
+    inst.apply_cdk_runtime_env(
+        {"CDK_FOLDER": "C:/example/cdk/", "AWS_REGION": "eu-west-2"}
+    )
+    assert os.environ["CDK_CONFIG_PATH"] == str(env_path)
+    assert os.environ["CDK_FOLDER"] == "C:/example/cdk/"
+
+
+def test_run_smoke_test_if_needed_skips_config_only(monkeypatch):
+    called = []
+
+    def fake_smoke(_python_exe):
+        called.append(True)
+
+    monkeypatch.setattr(inst, "smoke_test_python_app", fake_smoke)
+    args = argparse.Namespace(config_only=True, skip_cdk_json=False)
+    inst.run_smoke_test_if_needed(Path(sys.executable), args)
+    assert called == []
+
+
+def test_main_writes_config_before_smoke_test(monkeypatch, tmp_path):
+    call_order: list[str] = []
+    config_dir = tmp_path / "config"
+    config_dir.mkdir()
+    env_path = config_dir / "cdk_config.env"
+    cdk_json = tmp_path / "cdk.json"
+
+    monkeypatch.setattr(inst, "CONFIG_DIR", config_dir)
+    monkeypatch.setattr(inst, "ENV_PATH", env_path)
+    monkeypatch.setattr(inst, "CDK_JSON_PATH", cdk_json)
+    monkeypatch.setattr(inst, "CDK_DIR", tmp_path)
+    monkeypatch.setattr(inst, "check_cdk_cli", lambda: "2.0.0")
+    monkeypatch.setattr(
+        inst,
+        "handle_existing_stacks_at_start",
+        lambda *_a, **_k: None,
+    )
+    monkeypatch.setattr(
+        inst,
+        "resolve_python_executable",
+        lambda **_kw: Path(sys.executable),
+    )
+    monkeypatch.setattr(inst, "write_cdk_json", lambda *_a, **_k: cdk_json)
+
+    def fake_wizard(_args):
+        call_order.append("wizard")
+        return _demo_answers()
+
+    def fake_write_env_file(path, values):
+        call_order.append("write_config")
+        path.write_text("VPC_NAME=test-vpc\n", encoding="utf-8")
+        return values
+
+    def fake_smoke(_python_exe):
+        call_order.append("smoke")
+
+    monkeypatch.setattr(inst, "run_wizard", fake_wizard)
+    monkeypatch.setattr(inst, "write_env_file", fake_write_env_file)
+    monkeypatch.setattr(inst, "smoke_test_python_app", fake_smoke)
+    monkeypatch.setattr(inst, "print_summary", lambda *_a, **_k: None)
+    monkeypatch.setattr(inst, "ask_yes_no", lambda *_a, **_k: True)
+    monkeypatch.setattr(inst, "cdk_bootstrap_needed", lambda *_a, **_k: False)
+    monkeypatch.setattr(inst, "run_cdk_command", lambda *_a, **_k: None)
+
+    inst.main(
+        [
+            "--yes",
+            "--profile",
+            "demo",
+            "--vpc-name",
+            "test-vpc",
+            "--synth-only",
+        ]
+    )
+
+    assert call_order.index("wizard") < call_order.index("write_config")
+    assert call_order.index("write_config") < call_order.index("smoke")
+
+
+def test_resolve_fixup_env_values_derives_service_from_prefix():
+    values = {"CDK_PREFIX": "Demo-Summarisation-", "USE_ECS_EXPRESS_MODE": "True"}
+    resolved = inst.resolve_fixup_env_values(values)
+    assert resolved["ECS_EXPRESS_SERVICE_NAME"] == "Demo-Summarisation-ECSService"
+    assert resolved["CLUSTER_NAME"] == "Demo-Summarisation-Cluster"
+    assert (
+        resolved["ECS_PI_EXPRESS_SERVICE_NAME"] == "Demo-Summarisation-PiExpressService"
+    )
+
+
+def test_apply_post_deploy_fixup_express_syncs_cognito_secret_not_alb(monkeypatch):
+    import cdk_post_deploy as post
+
+    values = {
+        "USE_ECS_EXPRESS_MODE": "True",
+        "USE_CLOUDFRONT": "False",
+        "AWS_REGION": "eu-west-2",
+        "CDK_PREFIX": "Demo-Summarisation-",
+        "ECS_EXPRESS_COGNITO_REDIRECT_BASE": "",
+    }
+    outputs = {
+        "ExpressServiceEndpoint": "https://express.example.com",
+        "CognitoPoolId": "pool-1",
+        "CognitoAppClientId": "client-1",
+    }
+    monkeypatch.setattr(
+        inst,
+        "fetch_stack_output",
+        lambda _stack, key, _region: outputs.get(key),
+    )
+    monkeypatch.setattr(inst, "patch_env_file", lambda *_a, **_k: None)
+    monkeypatch.setattr(inst, "ask_yes_no", lambda *_a, **_k: True)
+    redeploy_calls: list = []
+    monkeypatch.setattr(
+        inst,
+        "run_cdk_command",
+        lambda *args, **_k: redeploy_calls.append(args),
+    )
+    monkeypatch.setattr(
+        post,
+        "cognito_alb_callbacks_need_update",
+        lambda *_a, **_k: True,
+    )
+    monkeypatch.setattr(
+        post,
+        "apply_cognito_alb_callback_fixup",
+        lambda *_a, **_k: True,
+    )
+    secret_fixup_calls: list = []
+    monkeypatch.setattr(
+        post,
+        "apply_cognito_secret_fixup_from_stack",
+        lambda **_k: secret_fixup_calls.append(_k) or True,
+    )
+
+    assert inst.apply_post_deploy_fixup(values, assume_yes=False) is True
+    assert redeploy_calls == []
+    assert secret_fixup_calls
+    assert secret_fixup_calls[0]["main_service_name"] == "Demo-Summarisation-ECSService"
+    assert secret_fixup_calls[0]["cluster_name"] == "Demo-Summarisation-Cluster"
+
+
+def test_jsii_import_failure_hint_detects_json_decode_error():
+    hint = inst._jsii_import_failure_hint(
+        "json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)"
+    )
+    assert "JSII Node.js helper" in hint
+    assert "node --version" in hint
+
+
+def test_jsii_import_failure_hint_empty_for_other_errors():
+    assert inst._jsii_import_failure_hint("ModuleNotFoundError: aws_cdk") == ""

cdk/test/test_cdk_post_deploy.py

@@ -0,0 +1,411 @@
+"""Unit tests for cdk_post_deploy.py (boto3 helpers, no live AWS)."""
+
+import json
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+import cdk_post_deploy as post
+
+
+def test_container_definitions_with_named_port_adds_mapping_to_first_container():
+    containers = [{"name": "app", "image": "nginx"}]
+    updated = post._container_definitions_with_named_port(
+        containers,
+        port_name="port-7860",
+        container_port=7860,
+    )
+    assert updated[0]["portMappings"] == [
+        {"name": "port-7860", "containerPort": 7860, "protocol": "tcp"}
+    ]
+
+
+def test_container_definitions_with_named_port_names_existing_mapping():
+    containers = [
+        {
+            "name": "app",
+            "image": "nginx",
+            "portMappings": [{"containerPort": 7860, "protocol": "tcp"}],
+        }
+    ]
+    updated = post._container_definitions_with_named_port(
+        containers,
+        port_name="port-7860",
+        container_port=7860,
+    )
+    assert updated[0]["portMappings"][0]["name"] == "port-7860"
+
+
+def test_resolve_service_task_definition_arn_from_describe_services():
+    mock_ecs = MagicMock()
+    mock_ecs.describe_services.return_value = {
+        "services": [
+            {
+                "serviceArn": "arn:aws:ecs:eu-west-2:123:service/cluster/app",
+                "taskDefinition": "arn:aws:ecs:eu-west-2:123:task-definition/app:1",
+            }
+        ]
+    }
+
+    with patch("cdk_post_deploy.boto3.client", return_value=mock_ecs):
+        arn = post.resolve_service_task_definition_arn("cluster", "app")
+
+    assert arn == "arn:aws:ecs:eu-west-2:123:task-definition/app:1"
+    mock_ecs.describe_express_gateway_service.assert_not_called()
+
+
+def test_resolve_service_task_definition_arn_from_express_service_revision():
+    mock_ecs = MagicMock()
+    mock_ecs.describe_services.return_value = {
+        "services": [
+            {
+                "serviceArn": "arn:aws:ecs:eu-west-2:123:service/cluster/express-app",
+            }
+        ]
+    }
+    mock_ecs.describe_express_gateway_service.return_value = {
+        "service": {
+            "activeConfigurations": [
+                {
+                    "serviceRevisionArn": "arn:aws:ecs:eu-west-2:123:service-revision/rev/1"
+                }
+            ]
+        }
+    }
+    mock_ecs.describe_service_revisions.return_value = {
+        "serviceRevisions": [
+            {
+                "taskDefinition": "arn:aws:ecs:eu-west-2:123:task-definition/express:3",
+            }
+        ]
+    }
+
+    with patch("cdk_post_deploy.boto3.client", return_value=mock_ecs):
+        arn = post.resolve_service_task_definition_arn("cluster", "express-app")
+
+    assert arn == "arn:aws:ecs:eu-west-2:123:task-definition/express:3"
+    mock_ecs.describe_express_gateway_service.assert_called_once()
+    mock_ecs.describe_service_revisions.assert_called_once_with(
+        serviceRevisionArns=["arn:aws:ecs:eu-west-2:123:service-revision/rev/1"]
+    )
+
+
+def test_start_express_gateway_service_updates_scaling_target():
+    mock_ecs = MagicMock()
+    mock_ecs.get_paginator.return_value.paginate.return_value = [
+        {
+            "serviceArns": [
+                "arn:aws:ecs:eu-west-2:123456789012:service/my-cluster/my-express"
+            ]
+        }
+    ]
+
+    with patch("cdk_post_deploy.boto3.client", return_value=mock_ecs):
+        result = post.start_express_gateway_service("my-cluster", "my-express")
+
+    assert result["statusCode"] == 200
+    mock_ecs.update_express_gateway_service.assert_called_once_with(
+        serviceArn="arn:aws:ecs:eu-west-2:123456789012:service/my-cluster/my-express",
+        scalingTarget=post.EXPRESS_GATEWAY_ACTIVE_SCALING_TARGET,
+    )
+
+
+def test_cognito_https_callback_urls():
+    assert post.cognito_https_callback_urls(
+        "https://abc123.eu-west-2.elb.amazonaws.com"
+    ) == [
+        "https://abc123.eu-west-2.elb.amazonaws.com",
+        "https://abc123.eu-west-2.elb.amazonaws.com/oauth2/idpresponse",
+    ]
+    assert post.cognito_https_callback_urls("app.example.com")[0].startswith("https://")
+
+
+def test_update_user_pool_client_callback_urls_preserves_oauth_settings():
+    mock_cognito = MagicMock()
+    mock_cognito.describe_user_pool_client.return_value = {
+        "UserPoolClient": {
+            "ClientName": "app-client",
+            "CallbackURLs": ["https://old.example.com"],
+            "AllowedOAuthFlows": ["code"],
+            "AllowedOAuthScopes": ["openid", "email", "profile"],
+            "AllowedOAuthFlowsUserPoolClient": True,
+            "SupportedIdentityProviders": ["COGNITO"],
+            "ExplicitAuthFlows": ["ALLOW_REFRESH_TOKEN_AUTH"],
+        }
+    }
+
+    with patch("cdk_post_deploy.boto3.client", return_value=mock_cognito):
+        post.update_user_pool_client_callback_urls(
+            "pool-1",
+            "client-1",
+            [
+                "https://new.example.com",
+                "https://new.example.com/oauth2/idpresponse",
+            ],
+            aws_region="eu-west-2",
+        )
+
+    mock_cognito.update_user_pool_client.assert_called_once()
+    kwargs = mock_cognito.update_user_pool_client.call_args.kwargs
+    assert kwargs["UserPoolId"] == "pool-1"
+    assert kwargs["ClientId"] == "client-1"
+    assert kwargs["CallbackURLs"] == [
+        "https://new.example.com",
+        "https://new.example.com/oauth2/idpresponse",
+    ]
+    assert kwargs["AllowedOAuthFlows"] == ["code"]
+    assert kwargs["AllowedOAuthScopes"] == ["openid", "email", "profile"]
+
+
+def test_apply_cognito_alb_callback_fixup_skips_when_already_correct():
+    mock_cognito = MagicMock()
+    mock_cognito.describe_user_pool_client.return_value = {
+        "UserPoolClient": {
+            "CallbackURLs": post.cognito_https_callback_urls("https://app.example.com"),
+        }
+    }
+
+    with patch("cdk_post_deploy.boto3.client", return_value=mock_cognito):
+        changed = post.apply_cognito_alb_callback_fixup(
+            user_pool_id="pool-1",
+            client_id="client-1",
+            redirect_base="https://app.example.com",
+        )
+
+    assert changed is False
+    mock_cognito.update_user_pool_client.assert_not_called()
+
+
+def test_target_group_arn_from_ecs_register_event():
+    message = (
+        "(service my-svc) registered 1 targets in "
+        "(target-group arn:aws:elasticloadbalancing:eu-west-2:123:"
+        "targetgroup/ecs-gateway-tg-abc/def)"
+    )
+    assert (
+        post.target_group_arn_from_ecs_register_event(message)
+        == "arn:aws:elasticloadbalancing:eu-west-2:123:targetgroup/ecs-gateway-tg-abc/def"
+    )
+
+
+def test_resolve_express_service_target_group_arn_waits_for_registration_event():
+    mock_ecs = MagicMock()
+    mock_ecs.describe_services.side_effect = [
+        {
+            "services": [
+                {
+                    "events": [],
+                    "runningCount": 0,
+                    "desiredCount": 1,
+                }
+            ]
+        },
+        {
+            "services": [
+                {
+                    "events": [
+                        {
+                            "message": (
+                                "(service Demo-Summarisation-ECSService) registered 1 targets in "
+                                "(target-group arn:aws:elasticloadbalancing:eu-west-2:123:"
+                                "targetgroup/ecs-gateway-tg-abc/def)"
+                            )
+                        }
+                    ],
+                    "runningCount": 1,
+                    "desiredCount": 1,
+                }
+            ]
+        },
+    ]
+
+    with (
+        patch("cdk_post_deploy.boto3.client", return_value=mock_ecs),
+        patch("cdk_post_deploy.time.sleep"),
+        patch("cdk_post_deploy.time.monotonic", side_effect=[0, 0, 600]),
+    ):
+        arn = post.resolve_express_service_target_group_arn(
+            "cluster",
+            "Demo-Summarisation-ECSService",
+            max_wait_seconds=600,
+            poll_interval_seconds=15,
+        )
+
+    assert arn == (
+        "arn:aws:elasticloadbalancing:eu-west-2:123:targetgroup/ecs-gateway-tg-abc/def"
+    )
+    assert mock_ecs.describe_services.call_count == 2
+
+
+def test_resolve_express_service_target_group_arn_from_task_ips():
+    mock_ecs = MagicMock()
+    mock_ecs.describe_services.return_value = {
+        "services": [
+            {
+                "events": [],
+                "runningCount": 1,
+                "desiredCount": 1,
+            }
+        ]
+    }
+    mock_ecs.list_tasks.return_value = {"taskArns": ["arn:task/1"]}
+    mock_ecs.describe_tasks.return_value = {
+        "tasks": [
+            {
+                "attachments": [
+                    {"details": [{"name": "privateIPv4Address", "value": "10.0.1.42"}]}
+                ]
+            }
+        ]
+    }
+    mock_elbv2 = MagicMock()
+    mock_elbv2.describe_target_groups.return_value = {
+        "TargetGroups": [{"TargetGroupArn": "arn:tg/main"}]
+    }
+    mock_elbv2.describe_target_health.return_value = {
+        "TargetHealthDescriptions": [{"Target": {"Id": "10.0.1.42"}}]
+    }
+
+    def client_factory(service_name, **_kwargs):
+        return mock_elbv2 if service_name == "elbv2" else mock_ecs
+
+    with (
+        patch("cdk_post_deploy.boto3.client", side_effect=client_factory),
+        patch("cdk_post_deploy.time.monotonic", return_value=0),
+    ):
+        arn = post.resolve_express_service_target_group_arn(
+            "cluster",
+            "Demo-Summarisation-ECSService",
+            load_balancer_arn="arn:lb/express",
+            max_wait_seconds=600,
+            poll_interval_seconds=15,
+        )
+
+    assert arn == "arn:tg/main"
+
+
+def test_listener_actions_with_target_group_replaces_forward_arn():
+    actions = [
+        {"Type": "authenticate-cognito", "Order": 1},
+        {
+            "Type": "forward",
+            "Order": 2,
+            "TargetGroupArn": "arn:old",
+            "ForwardConfig": {"TargetGroups": [{"TargetGroupArn": "arn:old"}]},
+        },
+    ]
+    updated = post.listener_actions_with_target_group(actions, "arn:new")
+    forward = next(action for action in updated if action["Type"] == "forward")
+    assert forward["TargetGroupArn"] == "arn:new"
+    assert forward["ForwardConfig"]["TargetGroups"][0]["TargetGroupArn"] == "arn:new"
+
+
+def test_cognito_secret_payload_matches():
+    desired = {
+        "SUMMARISATION_USER_POOL_ID": "eu-west-2_AAAA",
+        "SUMMARISATION_CLIENT_ID": "client",
+        "SUMMARISATION_CLIENT_SECRET": "secret",
+    }
+    current = json.dumps(
+        {
+            "SUMMARISATION_USER_POOL_ID": "eu-west-2_OLD",
+            "SUMMARISATION_CLIENT_ID": "client",
+            "SUMMARISATION_CLIENT_SECRET": "secret",
+        }
+    )
+    assert post.cognito_secret_payload_matches(current, desired) is False
+    assert post.cognito_secret_payload_matches(json.dumps(desired), desired) is True
+
+
+def test_listener_rule_has_cognito_auth():
+    assert post.listener_rule_has_cognito_auth(
+        [{"Type": "authenticate-cognito"}, {"Type": "forward"}]
+    )
+    assert not post.listener_rule_has_cognito_auth([{"Type": "forward"}])
+
+
+def test_print_express_mode_next_steps(capsys, monkeypatch):
+    def fake_get_stack_output(stack_name, output_key, region):
+        outputs = {
+            "ExpressServiceEndpoint": "main.example.ecs.eu-west-2.on.aws",
+            "PiExpressEndpoint": "pi.example.ecs.eu-west-2.on.aws",
+        }
+        return outputs.get(output_key)
+
+    monkeypatch.setattr(post, "get_stack_output", fake_get_stack_output)
+    post.print_express_mode_next_steps(
+        {
+            "AWS_REGION": "eu-west-2",
+            "ENABLE_PI_AGENT_EXPRESS_SERVICE": "True",
+        }
+    )
+    out = capsys.readouterr().out
+    assert "Wait 10 minutes for app deployment to finish." in out
+    assert "Cognito authorisation" not in out
+    assert "sign in at the Pi agent URL" in out
+    assert "https://main.example.ecs.eu-west-2.on.aws" in out
+    assert "https://pi.example.ecs.eu-west-2.on.aws/" in out
+    assert "pi_agent.env" not in out
+
+
+def test_print_headless_deployment_next_steps(capsys):
+    post.print_headless_deployment_next_steps(
+        {
+            "AWS_REGION": "eu-west-2",
+            "S3_OUTPUT_BUCKET_NAME": "my-output-bucket",
+            "S3_LOG_CONFIG_BUCKET_NAME": "my-log-bucket",
+            "S3_BATCH_INPUT_PREFIX": "input/",
+            "S3_BATCH_ENV_PREFIX": "input/config/",
+            "S3_BATCH_DEFAULT_PARAMS_KEY": "general-config/app_defaults.env",
+            "S3_BATCH_LAMBDA_FUNCTION_NAME": "Headless-Summarisation-S3BatchEcsTrigger",
+            "ECS_LOG_GROUP_NAME": "/ecs/headless-summarisation-ecsservice-logs",
+        }
+    )
+    out = capsys.readouterr().out
+    assert (
+        "Upload a consultation spreadsheet (.xlsx) to s3://my-output-bucket/input/"
+        in out
+    )
+    assert "example_headless_env_file.env" in out
+    assert "s3://my-output-bucket/input/config/" in out
+    assert "Headless-Summarisation-S3BatchEcsTrigger" in out
+    assert "s3://my-output-bucket/output/<session-folder>/" in out
+    assert "s3://my-log-bucket/general-config/app_defaults.env" in out
+    assert "tools/config.py" in out
+
+
+def test_seed_headless_batch_s3_layout_creates_prefixes(tmp_path):
+    from botocore.exceptions import ClientError
+
+    example = tmp_path / "example_headless_env_file.env"
+    example.write_text("DIRECT_MODE_TASK=redact\n", encoding="utf-8")
+    defaults = tmp_path / "app_defaults.env"
+    defaults.write_text("RUN_DIRECT_MODE=1\nS3_OUTPUTS_BUCKET=\n", encoding="utf-8")
+
+    missing = ClientError(
+        {"Error": {"Code": "404", "Message": "Not Found"}},
+        "HeadObject",
+    )
+    s3 = MagicMock()
+    s3.head_object.side_effect = missing
+
+    with patch("cdk_post_deploy.boto3.client", return_value=s3):
+        post.seed_headless_batch_s3_layout(
+            "my-bucket",
+            example_env_local_path=str(example),
+            log_bucket="my-log-bucket",
+            app_defaults_local_path=str(defaults),
+            s3_outputs_bucket_name="my-bucket",
+            aws_region="eu-west-2",
+        )
+
+    put_calls = s3.put_object.call_args_list
+    assert len(put_calls) == 4
+    keys_by_bucket = [(call.kwargs["Bucket"], call.kwargs["Key"]) for call in put_calls]
+    assert ("my-bucket", "input/") in keys_by_bucket
+    assert ("my-bucket", "input/config/") in keys_by_bucket
+    assert ("my-bucket", "input/config/example_headless_env_file.env") in keys_by_bucket
+    assert ("my-log-bucket", "general-config/app_defaults.env") in keys_by_bucket

cdk/test/test_cdk_synth_express.py

@@ -0,0 +1,155 @@
+"""Template assertions for legacy vs ECS Express Mode CDK paths."""
+
+import json
+import os
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+REPO_ROOT = CDK_DIR.parent
+sys.path.insert(0, str(CDK_DIR))
+
+
+def _load_template(env_overrides: dict) -> dict:
+    """Synth SummarisationStack with mocked config and pre-check context."""
+    os.environ["CDK_CONFIG_PATH"] = str(CDK_DIR / "config" / "cdk_config.env")
+    os.environ["CONTEXT_FILE"] = str(CDK_DIR / "precheck.context.json")
+
+    import importlib
+
+    for mod_name in list(sys.modules):
+        if mod_name in ("cdk_config", "cdk_stack", "app") or mod_name.startswith(
+            "cdk_"
+        ):
+            del sys.modules[mod_name]
+
+    with patch.dict(os.environ, env_overrides, clear=False):
+        import cdk_config as cfg
+
+        importlib.reload(cfg)
+        with patch.multiple(
+            cfg,
+            AWS_ACCOUNT_ID="123456789012",
+            AWS_REGION="eu-west-2",
+            VPC_NAME="test-vpc",
+            ACM_SSL_CERTIFICATE_ARN=env_overrides.get(
+                "ACM_SSL_CERTIFICATE_ARN", cfg.ACM_SSL_CERTIFICATE_ARN
+            ),
+            USE_ECS_EXPRESS_MODE=env_overrides.get(
+                "USE_ECS_EXPRESS_MODE", cfg.USE_ECS_EXPRESS_MODE
+            ),
+            USE_CLOUDFRONT=env_overrides.get("USE_CLOUDFRONT", "False"),
+            RUN_USEAST_STACK="False",
+            ENABLE_APPREGISTRY="False",
+        ):
+            from aws_cdk import App, Environment, Stack
+            from aws_cdk import aws_ec2 as ec2
+            from aws_cdk import aws_ecs as ecs
+            from aws_cdk import aws_elasticloadbalancingv2 as elbv2
+
+            app = App()
+            stack = Stack(
+                app,
+                "Test",
+                env=Environment(account="123456789012", region="eu-west-2"),
+            )
+
+            use_express = (
+                not env_overrides.get("ACM_SSL_CERTIFICATE_ARN", "")
+                and env_overrides.get("USE_ECS_EXPRESS_MODE") == "True"
+            )
+            if use_express:
+                ecs.CfnExpressGatewayService(
+                    stack,
+                    "Express",
+                    execution_role_arn="arn:aws:iam::123456789012:role/exec",
+                    infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+                    primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+                        image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/app:latest"
+                    ),
+                )
+            else:
+                vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+                alb = elbv2.ApplicationLoadBalancer(stack, "Alb", vpc=vpc)
+                cluster = ecs.Cluster(stack, "Cluster", vpc=vpc)
+                td = ecs.FargateTaskDefinition(
+                    stack, "Td", memory_limit_mib=512, cpu=256
+                )
+                td.add_container("c", image=ecs.ContainerImage.from_registry("nginx"))
+                ecs.FargateService(
+                    stack,
+                    "Svc",
+                    cluster=cluster,
+                    task_definition=td,
+                )
+                alb.add_listener(
+                    "Http",
+                    port=80,
+                    default_action=elbv2.ListenerAction.fixed_response(
+                        status_code=403,
+                        content_type="text/plain",
+                        message_body="deny",
+                    ),
+                )
+
+            assembly = app.synth()
+            stack_art = assembly.get_stack_by_name("Test")
+            template_path = Path(assembly.directory) / stack_art.template_file
+            return json.loads(template_path.read_text(encoding="utf-8"))
+
+
+@pytest.mark.parametrize(
+    "env,expect_express,expect_manual_alb",
+    [
+        (
+            {
+                "USE_ECS_EXPRESS_MODE": "True",
+                "ACM_SSL_CERTIFICATE_ARN": "",
+            },
+            True,
+            False,
+        ),
+        (
+            {
+                "USE_ECS_EXPRESS_MODE": "False",
+                "ACM_SSL_CERTIFICATE_ARN": "arn:aws:acm:eu-west-2:123:certificate/abc",
+            },
+            False,
+            True,
+        ),
+    ],
+)
+def test_branching_resource_types(env, expect_express, expect_manual_alb):
+    template = _load_template(env)
+    resources = template.get("Resources", {})
+    types = {r.get("Type") for r in resources.values()}
+    if expect_express:
+        assert "AWS::ECS::ExpressGatewayService" in types
+        assert "AWS::ElasticLoadBalancingV2::LoadBalancer" not in types
+    if expect_manual_alb:
+        assert "AWS::ElasticLoadBalancingV2::LoadBalancer" in types
+        assert "AWS::ECS::ExpressGatewayService" not in types
+
+
+def test_config_mutual_exclusion_raises():
+    use_express = "True"
+    acm_arn = "arn:aws:acm:eu-west-2:123:certificate/x"
+    with pytest.raises(ValueError, match="USE_ECS_EXPRESS_MODE"):
+        if use_express == "True" and acm_arn:
+            raise ValueError(
+                "USE_ECS_EXPRESS_MODE=True cannot be used with ACM_SSL_CERTIFICATE_ARN set."
+            )
+
+
+def test_legacy_pi_on_express_error_message():
+    legacy_pi = "True"
+    use_express = "True"
+    with pytest.raises(ValueError, match="ENABLE_PI_AGENT_EXPRESS_SERVICE"):
+        if legacy_pi == "True" and use_express == "True":
+            raise ValueError(
+                "ENABLE_PI_AGENT_ECS_SERVICE=True requires legacy Fargate (USE_ECS_EXPRESS_MODE=False). "
+                "For Pi on Express, use ENABLE_PI_AGENT_EXPRESS_SERVICE=True instead."
+            )

cdk/test/test_cloudfront_csp.py

@@ -0,0 +1,61 @@
+"""Tests for CloudFront CSP / response headers helpers."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+from cdk_cloudfront_headers import (
+    build_content_security_policy,
+    cognito_hosted_ui_base_url,
+    normalize_https_origin,
+    resolve_cloudfront_csp_urls,
+)
+
+
+def test_normalize_https_origin():
+    assert (
+        normalize_https_origin("d111.cloudfront.net") == "https://d111.cloudfront.net"
+    )
+    assert normalize_https_origin("https://summarisation.example.com/") == (
+        "https://summarisation.example.com"
+    )
+
+
+def test_build_content_security_policy_substitutes_hosts():
+    csp = build_content_security_policy(
+        app_origin="https://d111.cloudfront.net",
+        cognito_login_url="https://my-prefix.auth.eu-west-2.amazoncognito.com",
+    )
+    assert "wss://d111.cloudfront.net" in csp
+    assert "https://my-prefix.auth.eu-west-2.amazoncognito.com" in csp
+    assert "cdnjs.cloudflare.com" in csp
+
+
+def test_resolve_cloudfront_csp_urls_prefers_cognito_redirection():
+    app_origin, login = resolve_cloudfront_csp_urls(
+        cognito_redirection_url="https://summarisation.example.com",
+        cloudfront_domain="d111.cloudfront.net",
+        cognito_user_pool_domain_prefix="my-prefix",
+        aws_region="eu-west-2",
+    )
+    assert app_origin == "https://summarisation.example.com"
+    assert login == "https://my-prefix.auth.eu-west-2.amazoncognito.com"
+
+
+def test_resolve_cloudfront_csp_urls_login_override():
+    _, login = resolve_cloudfront_csp_urls(
+        cognito_redirection_url="https://app.example.com",
+        cloudfront_domain="d111.cloudfront.net",
+        cognito_user_pool_domain_prefix="my-prefix",
+        aws_region="eu-west-2",
+        cognito_user_pool_login_url="https://custom-login.example.com",
+    )
+    assert login == "https://custom-login.example.com"
+
+
+def test_cognito_hosted_ui_base_url():
+    assert cognito_hosted_ui_base_url("summarisation-123", "eu-west-1") == (
+        "https://summarisation-123.auth.eu-west-1.amazoncognito.com"
+    )

cdk/test/test_codebuild_public_github_source.py

@@ -0,0 +1,60 @@
+"""CodeBuild public GitHub source helpers."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+from aws_cdk import App, Stack
+from aws_cdk import aws_codebuild as codebuild
+from aws_cdk import aws_iam as iam
+from aws_cdk.assertions import Template
+from cdk_functions import (
+    configure_public_github_codebuild_source,
+    public_github_codebuild_source,
+    public_github_repository_url,
+)
+
+
+def test_public_github_repository_url():
+    assert (
+        public_github_repository_url("seanpedrick-case", "llm_topic_modeller")
+        == "https://github.com/seanpedrick-case/llm_topic_modelling.git"
+    )
+
+
+def test_public_github_codebuild_source_synth_without_auth():
+    app = App()
+    stack = Stack(app, "Test")
+    role = iam.Role(
+        stack, "Role", assumed_by=iam.ServicePrincipal("codebuild.amazonaws.com")
+    )
+    project = codebuild.Project(
+        stack,
+        "Proj",
+        role=role,
+        source=public_github_codebuild_source("owner", "repo", "main"),
+        build_spec=codebuild.BuildSpec.from_object(
+            {"version": "0.2", "phases": {"build": {"commands": ["echo hi"]}}}
+        ),
+    )
+    configure_public_github_codebuild_source(project, "owner", "repo", "main")
+
+    template = Template.from_stack(stack)
+    resources = template.to_json()["Resources"]
+    project_resource = next(
+        value
+        for value in resources.values()
+        if value["Type"] == "AWS::CodeBuild::Project"
+    )
+    source = project_resource["Properties"]["Source"]
+    triggers = project_resource["Properties"]["Triggers"]
+
+    assert "Auth" not in source
+    assert source["Type"] == "GITHUB"
+    assert source["Location"] == "https://github.com/owner/repo.git"
+    assert source["ReportBuildStatus"] is False
+    assert source["GitCloneDepth"] == 1
+    assert project_resource["Properties"]["SourceVersion"] == "main"
+    assert triggers["Webhook"] is False

cdk/test/test_delete_protection_config.py

@@ -0,0 +1,52 @@
+"""Tests for ENABLE_RESOURCE_DELETE_PROTECTION helpers."""
+
+import importlib
+
+import pytest
+from aws_cdk import RemovalPolicy
+
+
+@pytest.mark.parametrize(
+    ("env_value", "enabled"),
+    [
+        ("True", True),
+        ("true", True),
+        ("1", True),
+        ("yes", True),
+        ("False", False),
+        ("false", False),
+        ("0", False),
+    ],
+)
+def test_delete_protection_helpers(monkeypatch, env_value, enabled, tmp_path):
+    monkeypatch.setenv("ENABLE_RESOURCE_DELETE_PROTECTION", env_value)
+    monkeypatch.setenv("CDK_CONFIG_PATH", str(tmp_path / "missing_cdk_config.env"))
+
+    import cdk_config
+
+    importlib.reload(cdk_config)
+    import cdk_functions
+
+    importlib.reload(cdk_functions)
+
+    assert cdk_functions.is_resource_delete_protection_enabled() is enabled
+    assert cdk_functions.resource_deletion_protection_flag() is enabled
+    assert cdk_functions.managed_resource_removal_policy() == (
+        RemovalPolicy.RETAIN if enabled else RemovalPolicy.DESTROY
+    )
+    assert cdk_functions.s3_auto_delete_objects_on_stack_destroy() is (not enabled)
+    assert cdk_functions.ecr_empty_on_delete() is (not enabled)
+
+
+@pytest.mark.parametrize(
+    ("raw", "expected"),
+    [
+        ("de-abc.ecs.eu-west-2.on.aws", "https://de-abc.ecs.eu-west-2.on.aws"),
+        ("https://app.example.com/", "https://app.example.com"),
+        ("http://app.example.com", "https://app.example.com"),
+    ],
+)
+def test_normalize_https_redirect_url(raw, expected):
+    import cdk_config
+
+    assert cdk_config.normalize_https_redirect_url(raw) == expected

cdk/test/test_dynamo_usage_log_export.py

@@ -0,0 +1,129 @@
+"""Tests for scheduled DynamoDB usage log export Lambda and installer schedule helpers."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+
+def test_build_dynamo_export_cron_expression():
+    import cdk_install as inst
+
+    assert inst.build_dynamo_export_cron_expression(6, 0, "daily") == (
+        "cron(0 6 ? * * *)"
+    )
+    assert inst.build_dynamo_export_cron_expression(7, 30, "weekdays") == (
+        "cron(30 7 ? * MON-FRI *)"
+    )
+    assert inst.build_dynamo_export_cron_expression(0, 15, "weekends") == (
+        "cron(15 0 ? * SAT-SUN *)"
+    )
+
+
+def test_validate_schedule_time_hhmm():
+    import cdk_install as inst
+
+    assert inst.validate_schedule_time_hhmm("06:00") is None
+    assert inst.validate_schedule_time_hhmm("25:00") is not None
+    assert inst.validate_schedule_time_hhmm("bad") is not None
+
+
+def test_build_env_values_includes_dynamo_export_schedule():
+    import cdk_install as inst
+
+    answers = inst.InstallAnswers(
+        profile="demo",
+        aws_account_id="123456789012",
+        aws_region="eu-west-2",
+        cdk_prefix="Test-Summarisation-",
+        cognito_domain_prefix="test-summarisation",
+        vpc_mode="existing",
+        vpc_name="test-vpc",
+        enable_dynamo_usage_log_export=True,
+        dynamo_export_schedule_time="07:30",
+        dynamo_export_schedule_days="weekdays",
+        dynamo_export_s3_key="reports/usage.csv",
+    )
+    values = inst.build_env_values(answers)
+    assert values["ENABLE_DYNAMODB_USAGE_LOG_EXPORT"] == "True"
+    assert values["DYNAMODB_USAGE_LOG_EXPORT_SCHEDULE"] == ("cron(30 7 ? * MON-FRI *)")
+    assert values["DYNAMODB_USAGE_LOG_EXPORT_S3_KEY"] == "reports/usage.csv"
+
+
+def test_validate_env_values_rejects_dynamo_export_without_dynamodb_logging():
+    import cdk_install as inst
+
+    values = inst.build_env_values(
+        inst.InstallAnswers(
+            profile="demo",
+            aws_account_id="123456789012",
+            aws_region="eu-west-2",
+            cdk_prefix="Test-Summarisation-",
+            cognito_domain_prefix="test-summarisation",
+            vpc_mode="existing",
+            vpc_name="test-vpc",
+            enable_dynamo_usage_log_export=True,
+        )
+    )
+    values["SAVE_LOGS_TO_DYNAMODB"] = "False"
+    errors = inst.validate_env_values(values)
+    assert any("ENABLE_DYNAMODB_USAGE_LOG_EXPORT" in e for e in errors)
+
+
+def test_dynamo_usage_log_export_lambda_synth():
+    from aws_cdk import App, Environment, Stack
+    from aws_cdk import aws_dynamodb as dynamodb
+    from aws_cdk import aws_s3 as s3
+    from aws_cdk.assertions import Match, Template
+    from cdk_functions import create_dynamo_usage_log_export_lambda
+
+    app = App()
+    stack = Stack(
+        app,
+        "DynamoExportTest",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    table = dynamodb.Table(
+        stack,
+        "UsageTable",
+        partition_key=dynamodb.Attribute(name="id", type=dynamodb.AttributeType.STRING),
+    )
+    bucket = s3.Bucket(stack, "OutputBucket")
+
+    create_dynamo_usage_log_export_lambda(
+        stack,
+        "DynamoUsageLogExport",
+        function_name="test-dynamo-usage-export",
+        lambda_asset_path=str(CDK_DIR / "lambda_dynamo_logs_export"),
+        dynamodb_table=table,
+        output_bucket=bucket,
+        s3_output_key="reports/dynamodb-usage/dynamodb_logs_export.csv",
+        schedule_expression="cron(0 6 ? * MON-FRI *)",
+        dynamodb_table_name="test-usage-logs",
+        date_attribute="timestamp",
+    )
+
+    template = Template.from_stack(stack)
+    template.resource_count_is("AWS::Lambda::Function", 1)
+    template.resource_count_is("AWS::Events::Rule", 1)
+    template.has_resource_properties(
+        "AWS::Lambda::Function",
+        {
+            "Handler": "lambda_function.lambda_handler",
+            "Environment": {
+                "Variables": Match.object_like(
+                    {
+                        "DYNAMODB_TABLE_NAME": "test-usage-logs",
+                        "S3_OUTPUT_KEY": (
+                            "reports/dynamodb-usage/dynamodb_logs_export.csv"
+                        ),
+                    }
+                )
+            },
+        },
+    )
+    template.has_resource_properties(
+        "AWS::Events::Rule",
+        {"ScheduleExpression": "cron(0 6 ? * MON-FRI *)"},
+    )

cdk/test/test_ecs_vpc_endpoints.py

@@ -0,0 +1,400 @@
+"""ECS VPC endpoint helpers (task-subnet aligned: public for Express + public subnets)."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+
+def test_create_ecs_vpc_endpoints_synth_interface_and_s3_gateway():
+    from aws_cdk import App, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import create_ecs_vpc_endpoints_for_private_subnets
+
+    app = App()
+    stack = Stack(app, "VpcEndpointTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    private = ec2.SubnetSelection(
+        subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS,
+    )
+    create_ecs_vpc_endpoints_for_private_subnets(
+        stack,
+        vpc=vpc,
+        subnets=private,
+        include_secrets_and_kms=True,
+        aws_region="eu-west-2",
+    )
+    template = assertions.Template.from_stack(stack)
+    # 5 interface endpoints + 1 S3 gateway endpoint
+    template.resource_count_is("AWS::EC2::VPCEndpoint", 6)
+    template.has_resource_properties(
+        "AWS::EC2::VPCEndpoint",
+        {"VpcEndpointType": "Interface", "PrivateDnsEnabled": True},
+    )
+    template.has_resource_properties(
+        "AWS::EC2::VPCEndpoint",
+        {"VpcEndpointType": "Gateway"},
+    )
+
+
+def test_imported_vpc_from_attributes_requires_cidr_block():
+    """Imported VPCs must pass vpc_cidr_block or endpoint/SG helpers fail at synth."""
+    from aws_cdk import App, Stack
+    from aws_cdk import aws_ec2 as ec2
+
+    app = App()
+    stack = Stack(app, "ImportedVpcTest")
+    vpc = ec2.Vpc.from_vpc_attributes(
+        stack,
+        "ImportedVpc",
+        vpc_id="vpc-12345678",
+        availability_zones=["eu-west-2a", "eu-west-2b"],
+        vpc_cidr_block="10.0.0.0/16",
+    )
+    assert vpc.vpc_cidr_block == "10.0.0.0/16"
+
+
+def test_create_ecs_vpc_endpoints_skips_existing_service_names():
+    from aws_cdk import App, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import create_ecs_vpc_endpoints_for_private_subnets
+
+    app = App()
+    stack = Stack(app, "SkipEndpointTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    private = ec2.SubnetSelection(
+        subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS,
+    )
+    skip = frozenset(
+        {
+            "com.amazonaws.eu-west-2.kms",
+            "com.amazonaws.eu-west-2.secretsmanager",
+        }
+    )
+    create_ecs_vpc_endpoints_for_private_subnets(
+        stack,
+        vpc=vpc,
+        subnets=private,
+        skip_service_names=skip,
+        include_secrets_and_kms=True,
+        aws_region="eu-west-2",
+    )
+    template = assertions.Template.from_stack(stack)
+    template.resource_count_is("AWS::EC2::VPCEndpoint", 4)
+
+
+def test_create_ecs_vpc_endpoints_skips_precheck_shared_vpc_endpoints():
+    """Regression: skip list must use AWS ServiceName strings, not CDK service.name tokens."""
+    from aws_cdk import App, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import create_ecs_vpc_endpoints_for_private_subnets
+
+    app = App()
+    stack = Stack(app, "SharedVpcSkipTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    private = ec2.SubnetSelection(
+        subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS,
+    )
+    precheck_skip = frozenset(
+        {
+            "com.amazonaws.eu-west-2.kms",
+            "com.amazonaws.eu-west-2.s3",
+            "com.amazonaws.eu-west-2.secretsmanager",
+        }
+    )
+    create_ecs_vpc_endpoints_for_private_subnets(
+        stack,
+        vpc=vpc,
+        subnets=private,
+        skip_service_names=precheck_skip,
+        include_secrets_and_kms=True,
+        aws_region="eu-west-2",
+    )
+    template = assertions.Template.from_stack(stack)
+    # ecr.api, ecr.dkr, logs only (kms, secretsmanager, s3 skipped)
+    template.resource_count_is("AWS::EC2::VPCEndpoint", 3)
+
+
+def test_list_existing_vpc_endpoint_service_names(monkeypatch):
+    from cdk_functions import list_existing_vpc_endpoint_service_names
+
+    class FakePaginator:
+        def paginate(self, **kwargs):
+            return [
+                {
+                    "VpcEndpoints": [
+                        {
+                            "ServiceName": "com.amazonaws.eu-west-2.kms",
+                            "State": "available",
+                        },
+                        {
+                            "ServiceName": "com.amazonaws.eu-west-2.s3",
+                            "State": "available",
+                        },
+                        {
+                            "ServiceName": "com.amazonaws.eu-west-2.ecr.api",
+                            "State": "deleted",
+                        },
+                    ]
+                }
+            ]
+
+    class FakeEc2:
+        def get_paginator(self, name):
+            assert name == "describe_vpc_endpoints"
+            return FakePaginator()
+
+    monkeypatch.setattr(
+        "cdk_functions.boto3.client",
+        lambda service, region_name=None: FakeEc2(),
+    )
+    names = list_existing_vpc_endpoint_service_names("vpc-123", region_name="eu-west-2")
+    assert names == frozenset(
+        {
+            "com.amazonaws.eu-west-2.kms",
+            "com.amazonaws.eu-west-2.s3",
+        }
+    )
+
+
+def test_resolve_ecs_vpc_endpoint_subnet_selection_express_public():
+    from aws_cdk import App, Stack
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import resolve_ecs_vpc_endpoint_subnet_selection
+
+    app = App()
+    stack = Stack(app, "SubnetSelectTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    public_sel = resolve_ecs_vpc_endpoint_subnet_selection(
+        use_express_ingress=True,
+        express_use_public_subnets=True,
+        public_subnets=vpc.public_subnets,
+        private_subnets=vpc.private_subnets,
+    )
+    assert public_sel is not None
+    assert {s.subnet_id for s in public_sel.subnets} == {
+        s.subnet_id for s in vpc.public_subnets
+    }
+
+
+def test_resolve_ecs_vpc_endpoint_subnet_selection_express_private():
+    from aws_cdk import App, Stack
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import resolve_ecs_vpc_endpoint_subnet_selection
+
+    app = App()
+    stack = Stack(app, "SubnetSelectPrivateTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    private_sel = resolve_ecs_vpc_endpoint_subnet_selection(
+        use_express_ingress=True,
+        express_use_public_subnets=False,
+        public_subnets=vpc.public_subnets,
+        private_subnets=vpc.private_subnets,
+    )
+    assert private_sel is not None
+    assert {s.subnet_id for s in private_sel.subnets} == {
+        s.subnet_id for s in vpc.private_subnets
+    }
+
+
+def test_resolve_ecs_vpc_endpoint_subnet_selection_legacy_fargate():
+    from aws_cdk import App, Stack
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import resolve_ecs_vpc_endpoint_subnet_selection
+
+    app = App()
+    stack = Stack(app, "SubnetSelectLegacyTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    private_sel = resolve_ecs_vpc_endpoint_subnet_selection(
+        use_express_ingress=False,
+        express_use_public_subnets=True,
+        public_subnets=vpc.public_subnets,
+        private_subnets=vpc.private_subnets,
+    )
+    assert private_sel is not None
+    assert {s.subnet_id for s in private_sel.subnets} == {
+        s.subnet_id for s in vpc.private_subnets
+    }
+
+
+def test_resolve_ecs_vpc_endpoint_subnet_selection_public_only_legacy():
+    from aws_cdk import App, Stack
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import resolve_ecs_vpc_endpoint_subnet_selection
+
+    app = App()
+    stack = Stack(app, "SubnetSelectPublicOnlyTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    public_sel = resolve_ecs_vpc_endpoint_subnet_selection(
+        use_express_ingress=False,
+        express_use_public_subnets=True,
+        public_subnets=vpc.public_subnets,
+        private_subnets=[],
+    )
+    assert public_sel is not None
+    assert {s.subnet_id for s in public_sel.subnets} == {
+        s.subnet_id for s in vpc.public_subnets
+    }
+
+
+def test_create_ecs_vpc_endpoints_on_public_subnets():
+    from aws_cdk import App, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import create_ecs_vpc_endpoints_for_private_subnets
+
+    app = App()
+    stack = Stack(app, "PublicEndpointTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    public = ec2.SubnetSelection(subnet_type=ec2.SubnetType.PUBLIC)
+    create_ecs_vpc_endpoints_for_private_subnets(
+        stack,
+        vpc=vpc,
+        subnets=public,
+        include_secrets_and_kms=True,
+        aws_region="eu-west-2",
+    )
+    template = assertions.Template.from_stack(stack)
+    template.resource_count_is("AWS::EC2::VPCEndpoint", 6)
+    public_logical_ids = {
+        stack.get_logical_id(s.node.default_child) for s in vpc.public_subnets
+    }
+    interface_endpoints = [
+        r
+        for r in template.find_resources("AWS::EC2::VPCEndpoint").values()
+        if r.get("Properties", {}).get("VpcEndpointType") == "Interface"
+    ]
+    assert len(interface_endpoints) == 5
+    for resource in interface_endpoints:
+        subnet_ids = resource["Properties"]["SubnetIds"]
+        assert len(subnet_ids) == len(vpc.public_subnets)
+        for ref in subnet_ids:
+            assert ref.get("Ref") in public_logical_ids
+
+
+def test_resolve_ecs_s3_gateway_subnet_selection_all_stack_subnets():
+    from aws_cdk import App, Stack
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import resolve_ecs_s3_gateway_subnet_selection
+
+    app = App()
+    stack = Stack(app, "S3SubnetSelectTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    s3_sel = resolve_ecs_s3_gateway_subnet_selection(
+        public_subnets=vpc.public_subnets,
+        private_subnets=vpc.private_subnets,
+    )
+    assert s3_sel is not None
+    expected_ids = {s.subnet_id for s in vpc.public_subnets + vpc.private_subnets}
+    assert {s.subnet_id for s in s3_sel.subnets} == expected_ids
+
+
+def test_s3_gateway_endpoint_uses_all_stack_subnets_not_only_task_tier():
+    from aws_cdk import App, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import (
+        create_ecs_vpc_endpoints_for_private_subnets,
+        resolve_ecs_s3_gateway_subnet_selection,
+    )
+
+    app = App()
+    stack = Stack(app, "MixedS3GatewayTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    public = ec2.SubnetSelection(subnets=vpc.public_subnets)
+    all_stack_subnets = resolve_ecs_s3_gateway_subnet_selection(
+        public_subnets=vpc.public_subnets,
+        private_subnets=vpc.private_subnets,
+    )
+    create_ecs_vpc_endpoints_for_private_subnets(
+        stack,
+        vpc=vpc,
+        subnets=public,
+        s3_gateway_subnets=all_stack_subnets,
+        include_secrets_and_kms=True,
+        aws_region="eu-west-2",
+    )
+    template = assertions.Template.from_stack(stack)
+    gateway_endpoints = [
+        r
+        for r in template.find_resources("AWS::EC2::VPCEndpoint").values()
+        if r.get("Properties", {}).get("VpcEndpointType") == "Gateway"
+    ]
+    assert len(gateway_endpoints) == 1
+    route_table_ids = gateway_endpoints[0]["Properties"]["RouteTableIds"]
+    assert len(route_table_ids) == len(vpc.public_subnets) + len(vpc.private_subnets)
+    interface_endpoints = [
+        r
+        for r in template.find_resources("AWS::EC2::VPCEndpoint").values()
+        if r.get("Properties", {}).get("VpcEndpointType") == "Interface"
+    ]
+    public_logical_ids = {
+        stack.get_logical_id(s.node.default_child) for s in vpc.public_subnets
+    }
+    for resource in interface_endpoints:
+        for ref in resource["Properties"]["SubnetIds"]:
+            assert ref.get("Ref") in public_logical_ids
+
+
+def test_list_vpc_associated_cidr_blocks_primary_and_secondary():
+    from cdk_functions import list_vpc_associated_cidr_blocks
+
+    vpc = {
+        "CidrBlock": "10.0.0.0/16",
+        "CidrBlockAssociationSet": [
+            {
+                "CidrBlock": "10.0.0.0/16",
+                "CidrBlockState": {"State": "associated"},
+            },
+            {
+                "CidrBlock": "10.1.0.0/16",
+                "CidrBlockState": {"State": "associated"},
+            },
+        ],
+    }
+    assert list_vpc_associated_cidr_blocks(vpc) == [
+        "10.0.0.0/16",
+        "10.1.0.0/16",
+    ]
+
+
+def test_vpc_endpoint_security_group_ingress_covers_all_vpc_cidrs():
+    from aws_cdk import App, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import add_vpc_endpoint_https_ingress_from_vpc_cidrs
+
+    app = App()
+    stack = Stack(app, "DualCidrEndpointSgTest")
+    vpc = ec2.Vpc.from_vpc_attributes(
+        stack,
+        "ImportedVpc",
+        vpc_id="vpc-dual-cidr",
+        availability_zones=["eu-west-2a"],
+        vpc_cidr_block="10.0.0.0/16",
+    )
+    endpoint_sg = ec2.SecurityGroup(
+        stack,
+        "EndpointSg",
+        vpc=vpc,
+        description="test",
+    )
+    add_vpc_endpoint_https_ingress_from_vpc_cidrs(
+        endpoint_sg,
+        vpc_cidr_block="10.0.0.0/16",
+        vpc_cidr_blocks=["10.0.0.0/16", "10.1.0.0/16"],
+    )
+    template = assertions.Template.from_stack(stack)
+    template.has_resource_properties(
+        "AWS::EC2::SecurityGroup",
+        {
+            "SecurityGroupIngress": assertions.Match.array_with(
+                [
+                    assertions.Match.object_like(
+                        {"CidrIp": "10.0.0.0/16", "FromPort": 443, "ToPort": 443}
+                    ),
+                    assertions.Match.object_like(
+                        {"CidrIp": "10.1.0.0/16", "FromPort": 443, "ToPort": 443}
+                    ),
+                ]
+            )
+        },
+    )

cdk/test/test_elbv2_listener_rule_upsert.py

@@ -0,0 +1,86 @@
+"""Unit tests for ALB listener rule upsert Lambda helpers."""
+
+import importlib.util
+import sys
+from pathlib import Path
+
+_LAMBDA_PATH = (
+    Path(__file__).resolve().parents[1]
+    / "lambda_elbv2_listener_rule_upsert"
+    / "lambda_function.py"
+)
+_spec = importlib.util.spec_from_file_location(
+    "elbv2_listener_rule_upsert", _LAMBDA_PATH
+)
+_mod = importlib.util.module_from_spec(_spec)
+assert _spec and _spec.loader
+sys.modules[_spec.name] = _mod
+_spec.loader.exec_module(_mod)
+
+
+def test_conditions_match_path_pattern():
+    expected = [
+        {
+            "Field": "path-pattern",
+            "PathPatternConfig": {"Values": ["/agent", "/agent/*"]},
+        }
+    ]
+    from_api = [
+        {
+            "Field": "path-pattern",
+            "PathPatternConfig": {"Values": ["/agent", "/agent/*"]},
+            "Values": ["/agent", "/agent/*"],
+        }
+    ]
+    assert _mod._conditions_match(from_api, expected)
+
+
+def test_conditions_do_not_match_different_path():
+    expected = [
+        {
+            "Field": "path-pattern",
+            "PathPatternConfig": {"Values": ["/agent", "/agent/*"]},
+        }
+    ]
+    other = [
+        {
+            "Field": "path-pattern",
+            "PathPatternConfig": {"Values": ["/other", "/other/*"]},
+        }
+    ]
+    assert not _mod._conditions_match(other, expected)
+
+
+def test_normalize_listener_rule_payload_coerces_cfn_string_types():
+    raw_actions = [
+        {
+            "Type": "authenticate-cognito",
+            "Order": "1",
+            "AuthenticateCognitoConfig": {
+                "UserPoolArn": "arn:aws:cognito-idp:eu-west-2:1:userpool/pool",
+                "UserPoolClientId": "client",
+                "UserPoolDomain": "demo",
+                "SessionTimeout": "28800",
+            },
+        },
+        {
+            "Type": "forward",
+            "Order": "2",
+            "ForwardConfig": {
+                "TargetGroups": [
+                    {"TargetGroupArn": "arn:aws:elasticloadbalancing:1:tg"}
+                ],
+                "TargetGroupStickinessConfig": {
+                    "Enabled": "true",
+                    "DurationSeconds": "28800",
+                },
+            },
+        },
+    ]
+    _, actions = _mod._normalize_listener_rule_payload([], raw_actions)
+    assert actions[0]["Order"] == 1
+    assert actions[0]["AuthenticateCognitoConfig"]["SessionTimeout"] == 28800
+    assert actions[1]["Order"] == 2
+    stickiness = actions[1]["ForwardConfig"]["TargetGroupStickinessConfig"]
+    assert stickiness["Enabled"] is True
+    assert stickiness["DurationSeconds"] == 28800

cdk/test/test_ensure_codebuild_public_github.py

@@ -0,0 +1,81 @@
+"""Tests for runtime CodeBuild public GitHub source fixup."""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+from cdk_functions import ensure_codebuild_public_github_source
+
+
+def test_ensure_codebuild_updates_oauth_project(monkeypatch):
+    client = MagicMock()
+    client.batch_get_projects.return_value = {
+        "projects": [
+            {
+                "name": "MyProject",
+                "source": {
+                    "type": "GITHUB",
+                    "location": "https://github.com/old/repo.git",
+                    "auth": {"type": "CODECONNECTIONS", "resource": "arn:connection"},
+                    "reportBuildStatus": True,
+                    "buildspec": "version: 0.2\nphases: {}\n",
+                },
+                "sourceVersion": "main",
+                "triggers": {"webhook": True},
+            }
+        ]
+    }
+    monkeypatch.setattr("cdk_functions.boto3.client", lambda *args, **kwargs: client)
+
+    updated = ensure_codebuild_public_github_source(
+        "MyProject",
+        "seanpedrick-case",
+        "llm_topic_modeller",
+        "main",
+        aws_region="eu-west-2",
+    )
+
+    assert updated is True
+    client.update_project.assert_called_once()
+    kwargs = client.update_project.call_args.kwargs
+    assert kwargs["name"] == "MyProject"
+    assert kwargs["source"]["type"] == "GITHUB"
+    assert (
+        kwargs["source"]["location"]
+        == "https://github.com/seanpedrick-case/llm_topic_modelling.git"
+    )
+    assert "auth" not in kwargs["source"]
+    assert kwargs["sourceVersion"] == "main"
+    assert kwargs["triggers"] == {"webhook": False}
+
+
+def test_ensure_codebuild_skips_when_already_public(monkeypatch):
+    client = MagicMock()
+    client.batch_get_projects.return_value = {
+        "projects": [
+            {
+                "name": "MyProject",
+                "source": {
+                    "type": "GITHUB",
+                    "location": "https://github.com/seanpedrick-case/llm_topic_modelling.git",
+                    "reportBuildStatus": False,
+                },
+                "sourceVersion": "main",
+            }
+        ]
+    }
+    monkeypatch.setattr("cdk_functions.boto3.client", lambda *args, **kwargs: client)
+
+    updated = ensure_codebuild_public_github_source(
+        "MyProject",
+        "seanpedrick-case",
+        "llm_topic_modeller",
+        "main",
+        aws_region="eu-west-2",
+    )
+
+    assert updated is False
+    client.update_project.assert_not_called()

cdk/test/test_execution_role_kms_policy.py

@@ -0,0 +1,100 @@
+"""ECS task vs execution role KMS inline policy helpers."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+
+def test_task_and_execution_role_kms_policies_use_different_key_arns():
+    from cdk_functions import (
+        build_ecs_execution_role_kms_policy,
+        build_ecs_task_role_kms_policy,
+    )
+
+    s3_key = "arn:aws:kms:eu-west-2:123456789012:key/s3-shared-key"
+    secret_key = "arn:aws:kms:eu-west-2:123456789012:key/secret-key"
+
+    task_policy = build_ecs_task_role_kms_policy(shared_kms_key_arn=s3_key)
+    exec_policy = build_ecs_execution_role_kms_policy(secret_kms_key_arn=secret_key)
+
+    task_kms = next(
+        s for s in task_policy["Statement"] if s.get("Sid") == "KMSS3Access"
+    )
+    secret_kms = next(
+        s for s in exec_policy["Statement"] if s.get("Sid") == "KMSSecretDecrypt"
+    )
+
+    assert task_kms["Resource"] == s3_key
+    assert secret_kms["Resource"] == secret_key
+    assert "kms:GenerateDataKey" in task_kms["Action"]
+    assert "kms:DescribeKey" in task_kms["Action"]
+    assert secret_kms["Action"] == ["kms:Decrypt"]
+
+
+def test_task_role_inline_policy_scopes_s3_to_output_and_log_buckets():
+    from cdk_functions import build_ecs_task_role_inline_policy
+
+    policy = build_ecs_task_role_inline_policy(
+        output_bucket_name="lambeth-aws-sharedservices-prod-summarisation-s3-output",
+        log_config_bucket_name="lambeth-aws-sharedservices-prod-summarisation-s3-logs",
+        shared_kms_key_arn="arn:aws:kms:eu-west-2:123456789012:key/s3-shared-key",
+    )
+    s3_statements = [
+        s for s in policy["Statement"] if s.get("Sid", "").startswith("S3")
+    ]
+    assert len(s3_statements) == 2
+    output_stmt = next(s for s in s3_statements if s["Sid"] == "S3Output")
+    log_stmt = next(s for s in s3_statements if s["Sid"] == "S3LogConfig")
+    assert output_stmt["Action"] == [
+        "s3:GetObject*",
+        "s3:GetBucket*",
+        "s3:PutObject",
+        "s3:DeleteObject",
+        "s3:List*",
+    ]
+    assert output_stmt["Resource"] == [
+        "arn:aws:s3:::lambeth-aws-sharedservices-prod-summarisation-s3-output",
+        "arn:aws:s3:::lambeth-aws-sharedservices-prod-summarisation-s3-output/*",
+    ]
+    assert log_stmt["Resource"] == [
+        "arn:aws:s3:::lambeth-aws-sharedservices-prod-summarisation-s3-logs",
+        "arn:aws:s3:::lambeth-aws-sharedservices-prod-summarisation-s3-logs/*",
+    ]
+    kms_stmt = next(s for s in policy["Statement"] if s.get("Sid") == "KMSS3Access")
+    assert (
+        kms_stmt["Resource"] == "arn:aws:kms:eu-west-2:123456789012:key/s3-shared-key"
+    )
+
+
+def test_execution_role_policy_without_custom_s3_key_uses_secret_kms_only():
+    from cdk_functions import build_ecs_execution_role_kms_policy
+
+    secret_key = "arn:aws:kms:eu-west-2:123456789012:key/aws/secretsmanager"
+    policy = build_ecs_execution_role_kms_policy(secret_kms_key_arn=secret_key)
+    kms_statements = [
+        s for s in policy["Statement"] if s.get("Action") == ["kms:Decrypt"]
+    ]
+    assert len(kms_statements) == 1
+    assert kms_statements[0]["Resource"] == secret_key
+
+
+def test_get_secret_kms_key_arn_from_describe_secret(monkeypatch):
+    from cdk_functions import get_secret_kms_key_arn
+
+    class FakeSecretsManager:
+        def describe_secret(self, SecretId):
+            assert SecretId == "my-secret"
+            return {
+                "KmsKeyId": "arn:aws:kms:eu-west-2:123456789012:key/abc-123",
+            }
+
+    monkeypatch.setattr(
+        "cdk_functions.boto3.client",
+        lambda service, region_name=None: FakeSecretsManager(),
+    )
+    assert (
+        get_secret_kms_key_arn("my-secret", region_name="eu-west-2")
+        == "arn:aws:kms:eu-west-2:123456789012:key/abc-123"
+    )

cdk/test/test_express_app_config_env.py

@@ -0,0 +1,25 @@
+"""Tests for loading config/app_config.env into Express container environment."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+from cdk_functions import load_app_config_env_for_express
+
+
+def test_load_app_config_env_for_express_reads_config_env():
+    config_path = CDK_DIR / "config" / "app_config.env"
+    env_vars = load_app_config_env_for_express(str(config_path))
+    names = {p.name for p in env_vars}
+    assert "RUN_AWS_FUNCTIONS" in names
+    assert "S3_LOG_BUCKET" in names
+    assert "AWS_CLIENT_ID" not in names
+
+
+def test_load_app_config_env_missing_file_returns_empty():
+    assert (
+        load_app_config_env_for_express(str(CDK_DIR / "config" / "nonexistent.env"))
+        == []
+    )

cdk/test/test_express_pi.py

@@ -0,0 +1,566 @@
+"""Tests for Pi on ECS Express Mode helpers and config rules."""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+
+def test_pi_express_mutual_exclusion_with_legacy_pi():
+    legacy = "True"
+    express = "True"
+    with pytest.raises(ValueError, match="at most one Pi deployment"):
+        if legacy == "True" and express == "True":
+            raise ValueError(
+                "Enable at most one Pi deployment mode: ENABLE_PI_AGENT_ECS_SERVICE (legacy Fargate) "
+                "or ENABLE_PI_AGENT_EXPRESS_SERVICE (Express), not both."
+            )
+
+
+def test_pi_express_requires_express_mode():
+    express_pi = "True"
+    use_express = "False"
+    with pytest.raises(ValueError, match="ENABLE_PI_AGENT_EXPRESS_SERVICE"):
+        if express_pi == "True" and use_express != "True":
+            raise ValueError(
+                "ENABLE_PI_AGENT_EXPRESS_SERVICE=True requires USE_ECS_EXPRESS_MODE=True "
+                "(no ACM_SSL_CERTIFICATE_ARN)."
+            )
+
+
+def test_build_pi_express_container_environment():
+    from cdk_functions import build_pi_express_container_environment
+
+    env = build_pi_express_container_environment(
+        service_connect_discovery_name="summarisation",
+        main_app_port=7860,
+        pi_gradio_port=7862,
+    )
+    assert env["DOC_SUMMARISATION_GRADIO_URL"] == "http://summarisation:7860"
+    assert env["PI_WORKSPACE_DIR"] == "/tmp/pi-workspace"
+    assert env["PI_UPLOAD_ROOT"] == "/tmp/gradio"
+    assert env["PI_DEPLOYMENT_PROFILE"] == "aws-ecs"
+    assert env["COGNITO_AUTH"] == "True"
+    assert env["RUN_FASTAPI"] == "True"
+
+
+def test_build_express_pi_primary_container_includes_cognito_secrets():
+    from aws_cdk import App, Stack
+    from aws_cdk import aws_secretsmanager as sm
+    from cdk_functions import build_express_pi_primary_container
+
+    app = App()
+    stack = Stack(app, "PiSecretTest")
+    secret = sm.Secret(stack, "CognitoSecret", secret_name="demo-cognito-secret")
+
+    container = build_express_pi_primary_container(
+        image_uri="123456789012.dkr.ecr.eu-west-2.amazonaws.com/pi:latest",
+        container_port=7862,
+        log_group_name="/ecs/pi-logs",
+        aws_region="eu-west-2",
+        secret=secret,
+        cognito_auth=True,
+    )
+    assert container.secrets is not None
+    secret_names = {item.name for item in container.secrets}
+    assert secret_names == {"AWS_USER_POOL_ID", "AWS_CLIENT_ID", "AWS_CLIENT_SECRET"}
+
+    no_auth = build_express_pi_primary_container(
+        image_uri="123456789012.dkr.ecr.eu-west-2.amazonaws.com/pi:latest",
+        container_port=7862,
+        log_group_name="/ecs/pi-logs",
+        aws_region="eu-west-2",
+        secret=secret,
+        cognito_auth=False,
+    )
+    assert no_auth.secrets is None
+
+
+def test_format_express_pi_public_url():
+    from cdk_functions import format_express_pi_public_url
+
+    assert (
+        format_express_pi_public_url("https://pi.example.ecs.eu-west-2.on.aws")
+        == "https://pi.example.ecs.eu-west-2.on.aws/"
+    )
+    assert format_express_pi_public_url("") == ""
+
+
+def test_express_service_connect_configuration_server_and_client():
+    from cdk_functions import _express_service_connect_configuration
+
+    server = _express_service_connect_configuration(
+        namespace="demo-ns",
+        port_name="port-7860",
+        discovery_name="summarisation",
+        port=7860,
+    )
+    assert server["enabled"] is True
+    assert server["namespace"] == "demo-ns"
+    assert server["services"][0]["portName"] == "port-7860"
+    assert server["services"][0]["discoveryName"] == "summarisation"
+
+    client = _express_service_connect_configuration(namespace="demo-ns")
+    assert "services" not in client
+
+
+def test_apply_service_connect_custom_resource_synth():
+    from aws_cdk import App, Environment, Stack, assertions
+    from aws_cdk import aws_ecs as ecs
+    from cdk_functions import apply_service_connect_to_express_service
+
+    app = App()
+    stack = Stack(
+        app,
+        "ScExpressTest",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    express = ecs.CfnExpressGatewayService(
+        stack,
+        "MainExpress",
+        service_name="main-express",
+        cluster="test-cluster",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+            image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/app:latest",
+            container_port=7860,
+        ),
+    )
+    apply_service_connect_to_express_service(
+        stack,
+        "MainSc",
+        cluster_name="test-cluster",
+        service_name="main-express",
+        namespace="test-ns",
+        express_service=express,
+        port_name="port-7860",
+        discovery_name="summarisation",
+        port=7860,
+    )
+    template = assertions.Template.from_stack(stack)
+    template.resource_count_is("Custom::AWS", 1)
+    template.has_resource_properties(
+        "Custom::AWS",
+        {
+            "Create": assertions.Match.string_like_regexp(
+                r'"portName":"port-7860".*"discoveryName":"summarisation"'
+            ),
+        },
+    )
+
+
+def test_express_alb_ingress_uses_security_group_id_not_arn():
+    from aws_cdk import App, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from aws_cdk import aws_ecs as ecs
+    from cdk_functions import allow_express_load_balancer_to_ecs_security_group
+
+    app = App()
+    stack = Stack(app, "ExpressAlbIngressTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    task_sg = ec2.SecurityGroup(stack, "TaskSg", vpc=vpc)
+    express = ecs.CfnExpressGatewayService(
+        stack,
+        "Express",
+        service_name="main-express",
+        cluster="test-cluster",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+            image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/app:latest",
+            container_port=7860,
+        ),
+    )
+    allow_express_load_balancer_to_ecs_security_group(
+        stack,
+        "ExpressAlbToTask",
+        express_service=express,
+        ecs_security_group=task_sg,
+        container_port=7860,
+    )
+    template = assertions.Template.from_stack(stack)
+    template.has_resource_properties(
+        "AWS::EC2::SecurityGroupIngress",
+        {
+            "SourceSecurityGroupId": {
+                "Fn::Select": [
+                    1,
+                    {
+                        "Fn::Split": [
+                            "security-group/",
+                            {
+                                "Fn::Select": [
+                                    0,
+                                    {
+                                        "Fn::GetAtt": [
+                                            "Express",
+                                            "ECSManagedResourceArns.IngressPath.LoadBalancerSecurityGroups",
+                                        ]
+                                    },
+                                ]
+                            },
+                        ]
+                    },
+                ]
+            }
+        },
+    )
+
+
+def test_express_gateway_service_defaults_to_idle_scaling_target():
+    from aws_cdk import App, Stack, assertions
+    from aws_cdk import aws_ecs as ecs
+    from cdk_functions import create_express_gateway_service
+
+    app = App()
+    stack = Stack(app, "ExpressIdleScalingTest")
+    create_express_gateway_service(
+        stack,
+        "Express",
+        service_name="main-express",
+        cluster_name="test-cluster",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        task_role_arn="arn:aws:iam::123456789012:role/task",
+        cpu="1024",
+        memory="4096",
+        health_check_path="/",
+        primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+            image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/app:latest",
+            container_port=7860,
+        ),
+        subnet_ids=["subnet-abc"],
+        security_group_ids=["sg-main"],
+    )
+    template = assertions.Template.from_stack(stack)
+    template.has_resource_properties(
+        "AWS::ECS::ExpressGatewayService",
+        {
+            "ScalingTarget": {
+                "MinTaskCount": 0,
+                "MaxTaskCount": 1,
+                "AutoScalingMetric": "AVERAGE_CPU",
+                "AutoScalingTargetValue": 60,
+            }
+        },
+    )
+
+
+def test_express_infrastructure_role_uses_service_role_managed_policy():
+    from aws_cdk import App, Stack, assertions
+    from cdk_functions import create_ecs_express_infrastructure_role
+
+    app = App()
+    stack = Stack(app, "ExpressInfraRoleTest")
+    create_ecs_express_infrastructure_role(
+        stack, "ExpressInfrastructureRole", "test-express-infra"
+    )
+    template = assertions.Template.from_stack(stack)
+    template.has_resource_properties(
+        "AWS::IAM::Role",
+        {
+            "ManagedPolicyArns": assertions.Match.array_with(
+                [
+                    {
+                        "Fn::Join": [
+                            "",
+                            [
+                                "arn:",
+                                {"Ref": "AWS::Partition"},
+                                ":iam::aws:policy/service-role/AmazonECSInfrastructureRoleforExpressGatewayServices",
+                            ],
+                        ]
+                    }
+                ]
+            )
+        },
+    )
+
+
+def test_express_listener_helpers_synth_without_reference_error():
+    """Fn.select on Express list attrs must use typed attr_* list properties."""
+    from aws_cdk import App, Environment, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from aws_cdk import aws_ecs as ecs
+    from cdk_functions import (
+        allow_express_load_balancer_to_ecs_security_group,
+        configure_express_listener_cognito_and_cloudfront,
+        configure_express_pi_listener_rules,
+        create_express_gateway_service,
+    )
+
+    app = App()
+    stack = Stack(
+        app,
+        "ExpressListenerHelpers",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    sg = ec2.SecurityGroup(stack, "TaskSg", vpc=vpc)
+    main = create_express_gateway_service(
+        stack,
+        "Main",
+        service_name="main-svc",
+        cluster_name="cl",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        task_role_arn="arn:aws:iam::123456789012:role/task",
+        cpu="1024",
+        memory="2048",
+        health_check_path="/",
+        primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+            image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/app:latest",
+            container_port=7860,
+        ),
+        subnet_ids=["subnet-abc"],
+        security_group_ids=["sg-main"],
+    )
+    pi = create_express_gateway_service(
+        stack,
+        "Pi",
+        service_name="pi-svc",
+        cluster_name="cl",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        task_role_arn="arn:aws:iam::123456789012:role/task",
+        cpu="1024",
+        memory="2048",
+        health_check_path="/pi/",
+        primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+            image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/pi:latest",
+            container_port=7862,
+        ),
+        subnet_ids=["subnet-abc"],
+        security_group_ids=["sg-pi"],
+    )
+    allow_express_load_balancer_to_ecs_security_group(
+        stack,
+        "MainLbToTask",
+        express_service=main,
+        ecs_security_group=sg,
+        container_port=7860,
+    )
+    configure_express_listener_cognito_and_cloudfront(
+        stack,
+        "MainListener",
+        express_service=main,
+        user_pool_arn="arn:aws:cognito-idp:eu-west-2:123456789012:userpool/pool",
+        user_pool_client_id="client",
+        user_pool_domain_prefix="demo-auth",
+        use_cloudfront=False,
+        cloudfront_host_header="",
+    )
+    configure_express_pi_listener_rules(
+        stack,
+        "PiRules",
+        express_main_service=main,
+        express_pi_service=pi,
+        routing_mode="path",
+        path_prefix="/pi",
+        pi_host_header="",
+        rule_priority=3,
+        user_pool_arn="arn:aws:cognito-idp:eu-west-2:123456789012:userpool/pool",
+        user_pool_client_id="client",
+        user_pool_domain_prefix="demo-auth",
+    )
+    app.synth()
+    template = assertions.Template.from_stack(stack)
+    template.resource_count_is("AWS::ECS::ExpressGatewayService", 2)
+    # modifyListener (Custom::AWS) + Pi path rule (Custom::Elbv2ListenerRuleUpsert)
+    template.resource_count_is("Custom::AWS", 1)
+    template.resource_count_is("Custom::Elbv2ListenerRuleUpsert", 1)
+    # authenticate-cognito on ALB requires DescribeUserPoolClient on the CR Lambda role
+    cr_policy_actions: list[str] = []
+    for props in template.find_resources("AWS::IAM::Policy").values():
+        for stmt in (
+            props.get("Properties", {}).get("PolicyDocument", {}).get("Statement", [])
+        ):
+            action = stmt.get("Action", [])
+            if isinstance(action, str):
+                cr_policy_actions.append(action)
+            else:
+                cr_policy_actions.extend(action)
+    assert "cognito-idp:DescribeUserPoolClient" in cr_policy_actions
+    assert "elasticloadbalancing:ModifyListener" in cr_policy_actions
+
+
+def test_express_cloudfront_does_not_add_cognito_bypass_host_rule_by_default():
+    """With ALB Cognito, CloudFront must not add a forward-only host-header rule."""
+    from aws_cdk import App, Environment, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from aws_cdk import aws_ecs as ecs
+    from cdk_functions import (
+        configure_express_listener_cognito_and_cloudfront,
+        create_express_gateway_service,
+    )
+
+    app = App()
+    stack = Stack(
+        app,
+        "ExpressCloudFrontCognitoTest",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    main = create_express_gateway_service(
+        stack,
+        "Main",
+        service_name="main-svc",
+        cluster_name="cl",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        task_role_arn="arn:aws:iam::123456789012:role/task",
+        cpu="1024",
+        memory="2048",
+        health_check_path="/",
+        primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+            image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/app:latest",
+            container_port=7860,
+        ),
+        subnet_ids=[vpc.public_subnets[0].subnet_id],
+        security_group_ids=["sg-main"],
+    )
+    configure_express_listener_cognito_and_cloudfront(
+        stack,
+        "MainListener",
+        express_service=main,
+        user_pool_arn="arn:aws:cognito-idp:eu-west-2:123456789012:userpool/pool",
+        user_pool_client_id="client",
+        user_pool_domain_prefix="demo-auth",
+        use_cloudfront=True,
+        cloudfront_host_header="app.example.com",
+    )
+    template = assertions.Template.from_stack(stack)
+    template.resource_count_is("Custom::Elbv2ListenerRuleUpsert", 0)
+
+
+def test_express_cloudfront_can_opt_in_to_origin_bypass_without_cognito():
+    from aws_cdk import App, Environment, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from aws_cdk import aws_ecs as ecs
+    from cdk_functions import (
+        configure_express_listener_cognito_and_cloudfront,
+        create_express_gateway_service,
+    )
+
+    app = App()
+    stack = Stack(
+        app,
+        "ExpressCloudFrontBypassTest",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    main = create_express_gateway_service(
+        stack,
+        "Main",
+        service_name="main-svc",
+        cluster_name="cl",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        task_role_arn="arn:aws:iam::123456789012:role/task",
+        cpu="1024",
+        memory="2048",
+        health_check_path="/",
+        primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+            image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/app:latest",
+            container_port=7860,
+        ),
+        subnet_ids=[vpc.public_subnets[0].subnet_id],
+        security_group_ids=["sg-main"],
+    )
+    configure_express_listener_cognito_and_cloudfront(
+        stack,
+        "MainListener",
+        express_service=main,
+        user_pool_arn="arn:aws:cognito-idp:eu-west-2:123456789012:userpool/pool",
+        user_pool_client_id="client",
+        user_pool_domain_prefix="demo-auth",
+        use_cloudfront=True,
+        cloudfront_host_header="app.example.com",
+        allow_cloudfront_origin_without_cognito=True,
+    )
+    template = assertions.Template.from_stack(stack)
+    template.resource_count_is("Custom::Elbv2ListenerRuleUpsert", 1)
+
+
+def test_dual_express_gateway_services_synth():
+    """Two ExpressGatewayService resources when wiring main + Pi helpers."""
+    from aws_cdk import App, Environment, Stack, assertions
+    from aws_cdk import aws_ecs as ecs
+    from cdk_functions import (
+        apply_service_connect_to_express_service,
+        build_express_pi_primary_container,
+        create_express_gateway_service,
+    )
+
+    app = App()
+    stack = Stack(
+        app,
+        "DualExpressTest",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    main = create_express_gateway_service(
+        stack,
+        "Main",
+        service_name="main-svc",
+        cluster_name="cl",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        task_role_arn="arn:aws:iam::123456789012:role/task",
+        cpu="1024",
+        memory="2048",
+        health_check_path="/",
+        primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+            image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/app:latest",
+            container_port=7860,
+        ),
+        subnet_ids=["subnet-abc"],
+        security_group_ids=["sg-main"],
+    )
+    pi_container = build_express_pi_primary_container(
+        image_uri="123456789012.dkr.ecr.eu-west-2.amazonaws.com/pi:latest",
+        container_port=7862,
+        log_group_name="/ecs/pi-logs",
+        aws_region="eu-west-2",
+        environment={"PI_WORKSPACE_DIR": "/tmp/pi-workspace"},
+    )
+    pi = create_express_gateway_service(
+        stack,
+        "Pi",
+        service_name="pi-svc",
+        cluster_name="cl",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        task_role_arn="arn:aws:iam::123456789012:role/task",
+        cpu="1024",
+        memory="2048",
+        health_check_path="/",
+        primary_container=pi_container,
+        subnet_ids=["subnet-abc"],
+        security_group_ids=["sg-pi"],
+    )
+    apply_service_connect_to_express_service(
+        stack,
+        "MainSc",
+        cluster_name="cl",
+        service_name="main-svc",
+        namespace="ns",
+        express_service=main,
+        port_name="port-7860",
+        discovery_name="summarisation",
+        port=7860,
+    )
+    apply_service_connect_to_express_service(
+        stack,
+        "PiSc",
+        cluster_name="cl",
+        service_name="pi-svc",
+        namespace="ns",
+        express_service=pi,
+    )
+    template = assertions.Template.from_stack(stack)
+    template.resource_count_is("AWS::ECS::ExpressGatewayService", 2)
+    template.resource_count_is("Custom::AWS", 2)

cdk/test/test_globally_unique_names.py

@@ -0,0 +1,91 @@
+"""Tests for globally unique AWS name checks (S3, Cognito)."""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+from botocore.exceptions import ClientError
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+from cdk_functions import (  # noqa: E402
+    resolve_cognito_domain_prefix_availability,
+    resolve_s3_bucket_availability,
+)
+
+
+def _client_error(code: str) -> ClientError:
+    return ClientError({"Error": {"Code": code, "Message": code}}, "HeadBucket")
+
+
+def test_resolve_s3_bucket_available_on_404():
+    s3 = MagicMock()
+    s3.head_bucket.side_effect = _client_error("404")
+    status, name = resolve_s3_bucket_availability("free-bucket", s3_client=s3)
+    assert status == "available"
+    assert name == "free-bucket"
+
+
+def test_resolve_s3_bucket_owned_on_success():
+    s3 = MagicMock()
+    s3.head_bucket.return_value = {}
+    status, name = resolve_s3_bucket_availability("my-bucket", s3_client=s3)
+    assert status == "owned"
+    assert name == "my-bucket"
+
+
+def test_resolve_s3_bucket_globally_taken_on_403_not_listed():
+    s3 = MagicMock()
+    s3.head_bucket.side_effect = _client_error("403")
+    s3.list_buckets.return_value = {"Buckets": [{"Name": "other-bucket"}]}
+    status, name = resolve_s3_bucket_availability(
+        "demo-summarisation-s3-logs", s3_client=s3
+    )
+    assert status == "globally_taken"
+    assert name == "demo-summarisation-s3-logs"
+
+
+def test_resolve_s3_bucket_owned_on_403_listed_in_account():
+    s3 = MagicMock()
+    s3.head_bucket.side_effect = _client_error("403")
+    s3.list_buckets.return_value = {"Buckets": [{"Name": "my-bucket"}]}
+    status, _ = resolve_s3_bucket_availability("my-bucket", s3_client=s3)
+    assert status == "owned"
+
+
+def test_resolve_cognito_domain_taken_when_owned_elsewhere():
+    cognito = MagicMock()
+    cognito.describe_user_pool_domain.side_effect = _client_error(
+        "ResourceNotFoundException"
+    )
+    assert (
+        resolve_cognito_domain_prefix_availability(
+            "demo-summarisation", region_name="eu-west-2", cognito_client=cognito
+        )
+        == "taken"
+    )
+
+
+def test_resolve_cognito_domain_available_when_empty_description():
+    cognito = MagicMock()
+    cognito.describe_user_pool_domain.return_value = {"DomainDescription": {}}
+    assert (
+        resolve_cognito_domain_prefix_availability(
+            "my-prefix", region_name="eu-west-2", cognito_client=cognito
+        )
+        == "available"
+    )
+
+
+def test_resolve_cognito_domain_taken_when_user_pool_present():
+    cognito = MagicMock()
+    cognito.describe_user_pool_domain.return_value = {
+        "DomainDescription": {"UserPoolId": "eu-west-2_abc"}
+    }
+    assert (
+        resolve_cognito_domain_prefix_availability(
+            "taken-prefix", region_name="eu-west-2", cognito_client=cognito
+        )
+        == "taken"
+    )

cdk/test/test_headless_app_defaults_env.py

@@ -0,0 +1,39 @@
+"""Headless batch app_defaults.env rendering."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+from cdk_functions import build_headless_app_defaults_env_content
+
+
+def test_build_headless_app_defaults_env_sets_outputs_bucket():
+    seed_dir = str(CDK_DIR / "config" / "headless_s3_seed")
+    content = build_headless_app_defaults_env_content(
+        seed_dir,
+        s3_outputs_bucket_name="lambeth-prod-summarisation-s3-output",
+    )
+
+    assert "S3_OUTPUTS_BUCKET=lambeth-prod-summarisation-s3-output" in content
+    assert "RUN_DIRECT_MODE=1" in content
+    assert "SAVE_OUTPUTS_TO_S3=True" in content
+    assert content.count("S3_OUTPUTS_BUCKET=") == 1
+
+
+def test_build_headless_app_defaults_env_merges_bedrock_guardrails():
+    seed_dir = str(CDK_DIR / "config" / "headless_s3_seed")
+    content = build_headless_app_defaults_env_content(
+        seed_dir,
+        s3_outputs_bucket_name="test-output-bucket",
+        env_overrides={
+            "ENABLE_BEDROCK_GUARDRAILS": "True",
+            "BEDROCK_GUARDRAIL_IDENTIFIER": "gr-test",
+            "BEDROCK_GUARDRAIL_VERSION": "1",
+            "BEDROCK_GUARDRAIL_TRACE": "disabled",
+        },
+    )
+    assert "ENABLE_BEDROCK_GUARDRAILS=True" in content
+    assert "BEDROCK_GUARDRAIL_IDENTIFIER=gr-test" in content
+    assert "# ENABLE_BEDROCK_GUARDRAILS" not in content

cdk/test/test_headless_output_notifications.py

@@ -0,0 +1,81 @@
+"""Headless S3 output notification resources and installer validation."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+from cdk_functions import sanitize_headless_metric_filter_id
+
+
+def test_sanitize_headless_metric_filter_id():
+    assert sanitize_headless_metric_filter_id("Prod-Summarisation-s3-output-put") == (
+        "Prod-Summarisation-s3-output-put"
+    )
+    assert sanitize_headless_metric_filter_id("bad id!!") == "bad-id"
+
+
+def test_validate_notify_email():
+    from cdk_install import validate_notify_email
+
+    assert validate_notify_email("user@example.com") is None
+    assert validate_notify_email("") is not None
+    assert validate_notify_email("not-an-email") is not None
+
+
+def test_headless_output_notifications_synth():
+    from aws_cdk import App, Environment, Stack
+    from aws_cdk import aws_s3 as s3
+    from aws_cdk.assertions import Match, Template
+    from cdk_functions import create_headless_output_notifications
+
+    app = App()
+    stack = Stack(
+        app,
+        "HeadlessNotifyTest",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    bucket = s3.Bucket(stack, "OutputBucket", bucket_name="test-output-bucket")
+
+    create_headless_output_notifications(
+        stack,
+        "Notify",
+        output_bucket=bucket,
+        output_prefix="output/",
+        notify_email="analyst@example.com",
+        iam_user_name="test-s3-output-reader",
+        metric_filter_id="test-s3-output-put",
+        sns_topic_name="test-llm-topic-s3-save-sns",
+        alarm_name="test-cloudwatch-alarm-new-output-s3",
+    )
+
+    template = Template.from_stack(stack)
+    template.resource_count_is("AWS::SNS::Topic", 1)
+    template.resource_count_is("AWS::CloudWatch::Alarm", 1)
+    template.resource_count_is("AWS::IAM::User", 1)
+    template.has_resource_properties(
+        "AWS::S3::BucketPolicy",
+        {
+            "PolicyDocument": {
+                "Statement": Match.array_with(
+                    [
+                        Match.object_like(
+                            {
+                                "Effect": "Allow",
+                                "Action": Match.array_with(["s3:GetObject"]),
+                            }
+                        )
+                    ]
+                )
+            }
+        },
+    )
+    template.has_resource_properties(
+        "AWS::CloudWatch::Alarm",
+        {
+            "MetricName": "PutRequests",
+            "Namespace": "AWS/S3",
+            "ComparisonOperator": "GreaterThanThreshold",
+        },
+    )