feat(docker): add script to run Docker container for calminer application

Reviewed-on: #13

.env.development

@@ -0,0 +1,25 @@
+# Development Environment Configuration
+ENVIRONMENT=development
+DEBUG=true
+LOG_LEVEL=DEBUG
+
+# Database Configuration
+DATABASE_HOST=postgres
+DATABASE_PORT=5432
+DATABASE_USER=calminer
+DATABASE_PASSWORD=calminer_password
+DATABASE_NAME=calminer_db
+DATABASE_DRIVER=postgresql
+
+# Application Settings
+CALMINER_EXPORT_MAX_ROWS=1000
+CALMINER_IMPORT_MAX_ROWS=10000
+CALMINER_EXPORT_METADATA=true
+CALMINER_IMPORT_STAGING_TTL=300
+
+# Admin Seeding (for development)
+CALMINER_SEED_ADMIN_EMAIL=admin@calminer.local
+CALMINER_SEED_ADMIN_USERNAME=admin
+CALMINER_SEED_ADMIN_PASSWORD=ChangeMe123!
+CALMINER_SEED_ADMIN_ROLES=admin
+CALMINER_SEED_FORCE=false

.env.production

@@ -0,0 +1,25 @@
+# Production Environment Configuration
+ENVIRONMENT=production
+DEBUG=false
+LOG_LEVEL=WARNING
+
+# Database Configuration (MUST be set externally - no defaults)
+DATABASE_HOST=
+DATABASE_PORT=5432
+DATABASE_USER=
+DATABASE_PASSWORD=
+DATABASE_NAME=
+DATABASE_DRIVER=postgresql
+
+# Application Settings
+CALMINER_EXPORT_MAX_ROWS=100000
+CALMINER_IMPORT_MAX_ROWS=100000
+CALMINER_EXPORT_METADATA=true
+CALMINER_IMPORT_STAGING_TTL=3600
+
+# Admin Seeding (for production - set strong password)
+CALMINER_SEED_ADMIN_EMAIL=admin@calminer.com
+CALMINER_SEED_ADMIN_USERNAME=admin
+CALMINER_SEED_ADMIN_PASSWORD=CHANGE_THIS_VERY_STRONG_PASSWORD
+CALMINER_SEED_ADMIN_ROLES=admin
+CALMINER_SEED_FORCE=false

.env.staging

@@ -0,0 +1,25 @@
+# Staging Environment Configuration
+ENVIRONMENT=staging
+DEBUG=false
+LOG_LEVEL=INFO
+
+# Database Configuration (override with actual staging values)
+DATABASE_HOST=postgres
+DATABASE_PORT=5432
+DATABASE_USER=calminer_staging
+DATABASE_PASSWORD=CHANGE_THIS_STRONG_PASSWORD
+DATABASE_NAME=calminer_staging_db
+DATABASE_DRIVER=postgresql
+
+# Application Settings
+CALMINER_EXPORT_MAX_ROWS=50000
+CALMINER_IMPORT_MAX_ROWS=50000
+CALMINER_EXPORT_METADATA=true
+CALMINER_IMPORT_STAGING_TTL=600
+
+# Admin Seeding (for staging)
+CALMINER_SEED_ADMIN_EMAIL=admin@staging.calminer.com
+CALMINER_SEED_ADMIN_USERNAME=admin
+CALMINER_SEED_ADMIN_PASSWORD=CHANGE_THIS_STRONG_PASSWORD
+CALMINER_SEED_ADMIN_ROLES=admin
+CALMINER_SEED_FORCE=false

.gitattributes

@@ -0,0 +1,3 @@
+* text=auto
+
+Dockerfile text eol=lf

.gitea/workflows/ci-build.yml

@@ -0,0 +1,232 @@
+name: CI - Build
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  build:
+    outputs:
+      allow_push: ${{ steps.meta.outputs.allow_push }}
+      ref_name: ${{ steps.meta.outputs.ref_name }}
+      event_name: ${{ steps.meta.outputs.event_name }}
+      sha: ${{ steps.meta.outputs.sha }}
+    runs-on: ubuntu-latest
+    env:
+      DEFAULT_BRANCH: main
+      REGISTRY_URL: ${{ secrets.REGISTRY_URL }}
+      REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
+      REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
+      REGISTRY_CONTAINER_NAME: calminer
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Collect workflow metadata
+        id: meta
+        shell: bash
+        env:
+          DEFAULT_BRANCH: ${{ env.DEFAULT_BRANCH }}
+        run: |
+          git_ref="${GITEA_REF:-${GITHUB_REF:-}}"
+          ref_name="${GITEA_REF_NAME:-${GITHUB_REF_NAME:-}}"
+          if [ -z "$ref_name" ] && [ -n "$git_ref" ]; then
+            ref_name="${git_ref##*/}"
+          fi
+          event_name="${GITEA_EVENT_NAME:-${GITHUB_EVENT_NAME:-}}"
+          sha="${GITEA_SHA:-${GITHUB_SHA:-}}"
+          if [ -z "$sha" ]; then
+            sha="$(git rev-parse HEAD)"
+          fi
+
+          if [ "$ref_name" = "${DEFAULT_BRANCH:-main}" ] && [ "$event_name" != "pull_request" ]; then
+            echo "allow_push=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "allow_push=false" >> "$GITHUB_OUTPUT"
+          fi
+
+          echo "ref_name=$ref_name" >> "$GITHUB_OUTPUT"
+          echo "event_name=$event_name" >> "$GITHUB_OUTPUT"
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+
+      - name: Validate registry configuration
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [ -z "${REGISTRY_URL}" ]; then
+            echo "::error::REGISTRY_URL secret not configured. Configure it with your Gitea container registry host." >&2
+            exit 1
+          fi
+          server_url="${GITEA_SERVER_URL:-${GITHUB_SERVER_URL:-}}"
+          server_host="${server_url#http://}"
+          server_host="${server_host#https://}"
+          server_host="${server_host%%/*}"
+          server_host="${server_host%%:*}"
+          registry_host="${REGISTRY_URL#http://}"
+          registry_host="${registry_host#https://}"
+          registry_host="${registry_host%%/*}"
+          registry_host="${registry_host%%:*}"
+          if [ -n "${server_host}" ] && ! printf '%s' "${registry_host}" | grep -qi "${server_host}"; then
+            echo "::warning::REGISTRY_URL (${REGISTRY_URL}) does not match current Gitea host (${server_host}). Ensure this registry endpoint is managed by Gitea." >&2
+          fi
+          registry_repository="${registry_host}/allucanget/${REGISTRY_CONTAINER_NAME}"
+          echo "REGISTRY_HOST=${registry_host}" >> "$GITHUB_ENV"
+          echo "REGISTRY_REPOSITORY=${registry_repository}" >> "$GITHUB_ENV"
+
+      - name: Set up QEMU and Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to gitea registry
+        if: ${{ steps.meta.outputs.allow_push == 'true' }}
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY_HOST }}
+          username: ${{ env.REGISTRY_USERNAME }}
+          password: ${{ env.REGISTRY_PASSWORD }}
+
+      - name: Build image
+        id: build-image
+        env:
+          REGISTRY_REPOSITORY: ${{ env.REGISTRY_REPOSITORY }}
+          REGISTRY_CONTAINER_NAME: ${{ env.REGISTRY_CONTAINER_NAME }}
+          SHA_TAG: ${{ steps.meta.outputs.sha }}
+          PUSH_IMAGE: ${{ steps.meta.outputs.allow_push == 'true' && env.REGISTRY_HOST != '' && env.REGISTRY_USERNAME != '' && env.REGISTRY_PASSWORD != '' }}
+        run: |
+          set -eo pipefail
+          LOG_FILE=build.log
+          if [ "${PUSH_IMAGE}" = "true" ]; then
+            docker buildx build \
+              --load \
+              --tag "${REGISTRY_REPOSITORY}:latest" \
+              --tag "${REGISTRY_REPOSITORY}:${SHA_TAG}" \
+              --file Dockerfile \
+              . 2>&1 | tee "${LOG_FILE}"
+          else
+            docker buildx build \
+              --load \
+              --tag "${REGISTRY_CONTAINER_NAME}:ci" \
+              --file Dockerfile \
+              . 2>&1 | tee "${LOG_FILE}"
+          fi
+
+      - name: Push image
+        if: ${{ steps.meta.outputs.allow_push == 'true' }}
+        env:
+          REGISTRY_REPOSITORY: ${{ env.REGISTRY_REPOSITORY }}
+          SHA_TAG: ${{ steps.meta.outputs.sha }}
+        run: |
+          set -euo pipefail
+          if [ -z "${REGISTRY_REPOSITORY}" ]; then
+            echo "::error::REGISTRY_REPOSITORY not defined; cannot push image" >&2
+            exit 1
+          fi
+          docker push "${REGISTRY_REPOSITORY}:${SHA_TAG}"
+          docker push "${REGISTRY_REPOSITORY}:latest"
+
+      - name: Upload docker build logs
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docker-build-logs
+          path: build.log
+
+  deploy:
+    needs: build
+    if: needs.build.outputs.allow_push == 'true'
+    runs-on: ubuntu-latest
+    env:
+      REGISTRY_URL: ${{ secrets.REGISTRY_URL }}
+      REGISTRY_CONTAINER_NAME: calminer
+      KUBE_CONFIG: ${{ secrets.KUBE_CONFIG }}
+      STAGING_KUBE_CONFIG: ${{ secrets.STAGING_KUBE_CONFIG }}
+      PROD_KUBE_CONFIG: ${{ secrets.PROD_KUBE_CONFIG }}
+      K8S_DEPLOY_ENABLED: ${{ secrets.K8S_DEPLOY_ENABLED }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Resolve registry repository
+        run: |
+          set -euo pipefail
+          if [ -z "${REGISTRY_URL}" ]; then
+            echo "::error::REGISTRY_URL secret not configured. Configure it with your Gitea container registry host." >&2
+            exit 1
+          fi
+          registry_host="${REGISTRY_URL#http://}"
+          registry_host="${registry_host#https://}"
+          registry_host="${registry_host%%/*}"
+          registry_host="${registry_host%%:*}"
+          registry_repository="${registry_host}/allucanget/${REGISTRY_CONTAINER_NAME}"
+          echo "REGISTRY_HOST=${registry_host}" >> "$GITHUB_ENV"
+          echo "REGISTRY_REPOSITORY=${registry_repository}" >> "$GITHUB_ENV"
+
+      - name: Report Kubernetes deployment toggle
+        run: |
+          set -euo pipefail
+          enabled="${K8S_DEPLOY_ENABLED:-}" 
+          if [ "${enabled}" = "true" ]; then
+            echo "Kubernetes deployment is enabled for this run."
+          else
+            echo "::notice::Kubernetes deployment steps are disabled (set secrets.K8S_DEPLOY_ENABLED to 'true' to enable)."
+          fi
+
+      - name: Capture commit metadata
+        id: commit_meta
+        run: |
+          set -euo pipefail
+          message="$(git log -1 --pretty=%B | tr '\n' ' ')"
+          echo "message=$message" >> "$GITHUB_OUTPUT"
+
+      - name: Set up kubectl for staging
+        if: env.K8S_DEPLOY_ENABLED == 'true' && contains(steps.commit_meta.outputs.message, '[deploy staging]')
+        uses: azure/k8s-set-context@v3
+        with:
+          method: kubeconfig
+          kubeconfig: ${{ env.STAGING_KUBE_CONFIG }}
+
+      - name: Set up kubectl for production
+        if: env.K8S_DEPLOY_ENABLED == 'true' && contains(steps.commit_meta.outputs.message, '[deploy production]')
+        uses: azure/k8s-set-context@v3
+        with:
+          method: kubeconfig
+          kubeconfig: ${{ env.PROD_KUBE_CONFIG }}
+
+      - name: Deploy to staging
+        if: env.K8S_DEPLOY_ENABLED == 'true' && contains(steps.commit_meta.outputs.message, '[deploy staging]')
+        run: |
+          kubectl set image deployment/calminer-app calminer=${REGISTRY_REPOSITORY}:latest
+          kubectl apply -f k8s/configmap.yaml
+          kubectl apply -f k8s/secret.yaml
+          kubectl rollout status deployment/calminer-app
+
+      - name: Collect staging deployment logs
+        if: env.K8S_DEPLOY_ENABLED == 'true' && contains(steps.commit_meta.outputs.message, '[deploy staging]')
+        run: |
+          mkdir -p logs/deployment/staging
+          kubectl get pods -o wide > logs/deployment/staging/pods.txt
+          kubectl get deployment calminer-app -o yaml > logs/deployment/staging/deployment.yaml
+          kubectl logs deployment/calminer-app --all-containers=true --tail=500 > logs/deployment/staging/calminer-app.log
+
+      - name: Deploy to production
+        if: env.K8S_DEPLOY_ENABLED == 'true' && contains(steps.commit_meta.outputs.message, '[deploy production]')
+        run: |
+          kubectl set image deployment/calminer-app calminer=${REGISTRY_REPOSITORY}:latest
+          kubectl apply -f k8s/configmap.yaml
+          kubectl apply -f k8s/secret.yaml
+          kubectl rollout status deployment/calminer-app
+
+      - name: Collect production deployment logs
+        if: env.K8S_DEPLOY_ENABLED == 'true' && contains(steps.commit_meta.outputs.message, '[deploy production]')
+        run: |
+          mkdir -p logs/deployment/production
+          kubectl get pods -o wide > logs/deployment/production/pods.txt
+          kubectl get deployment calminer-app -o yaml > logs/deployment/production/deployment.yaml
+          kubectl logs deployment/calminer-app --all-containers=true --tail=500 > logs/deployment/production/calminer-app.log
+
+      - name: Upload deployment logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: deployment-logs
+          path: logs/deployment
+          if-no-files-found: ignore

.gitea/workflows/ci-lint.yml

@@ -0,0 +1,44 @@
+name: CI - Lint
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    env:
+      APT_CACHER_NG: http://192.168.88.14:3142
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+
+      - name: Configure apt proxy
+        run: |
+          if [ -n "${APT_CACHER_NG}" ]; then
+            echo "Acquire::http::Proxy \"${APT_CACHER_NG}\";" | tee /etc/apt/apt.conf.d/01apt-cacher-ng
+          fi
+
+      - name: Install system packages
+        run: |
+          apt-get update
+          apt-get install -y build-essential libpq-dev
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -r requirements-test.txt
+
+      - name: Run Ruff
+        run: ruff check .
+
+      - name: Run Black
+        run: black --check .
+
+      - name: Run Bandit
+        run: bandit -c pyproject.toml -r tests

.gitea/workflows/ci-test.yml

@@ -0,0 +1,73 @@
+name: CI - Test
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      APT_CACHER_NG: http://192.168.88.14:3142
+      DB_DRIVER: postgresql+psycopg2
+      DB_HOST: 192.168.88.35
+      DB_NAME: calminer_test
+      DB_USER: calminer
+      DB_PASSWORD: calminer_password
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_USER: ${{ env.DB_USER }}
+          POSTGRES_PASSWORD: ${{ env.DB_PASSWORD }}
+          POSTGRES_DB: ${{ env.DB_NAME }}
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+
+      - name: Configure apt proxy
+        run: |
+          if [ -n "${APT_CACHER_NG}" ]; then
+            echo "Acquire::http::Proxy \"${APT_CACHER_NG}\";" | tee /etc/apt/apt.conf.d/01apt-cacher-ng
+          fi
+
+      - name: Install system packages
+        run: |
+          apt-get update
+          apt-get install -y build-essential libpq-dev
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -r requirements-test.txt
+
+      - name: Run tests
+        env:
+          DATABASE_DRIVER: ${{ env.DB_DRIVER }}
+          DATABASE_HOST: postgres
+          DATABASE_PORT: 5432
+          DATABASE_USER: ${{ env.DB_USER }}
+          DATABASE_PASSWORD: ${{ env.DB_PASSWORD }}
+          DATABASE_NAME: ${{ env.DB_NAME }}
+        run: |
+          pytest --cov=. --cov-report=term-missing --cov-report=xml --cov-fail-under=80 --junitxml=pytest-report.xml
+
+      - name: Upload test artifacts
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: test-artifacts
+          path: |
+            coverage.xml
+            pytest-report.xml

.gitea/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+      - v2
+  pull_request:
+    branches:
+      - main
+      - develop
+  workflow_dispatch:
+
+jobs:
+  lint:
+    uses: ./.gitea/workflows/ci-lint.yml
+    secrets: inherit
+
+  test:
+    needs: lint
+    uses: ./.gitea/workflows/ci-test.yml
+    secrets: inherit
+
+  build:
+    needs:
+      - lint
+      - test
+    uses: ./.gitea/workflows/ci-build.yml
+    secrets: inherit

.gitea/workflows/cicache.yml

@@ -1,142 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main, develop]
-  pull_request:
-    branches: [main, develop]
-
-jobs:
-  test:
-    env:
-      APT_CACHER_NG: http://192.168.88.14:3142
-      DB_DRIVER: postgresql+psycopg2
-      DB_HOST: 192.168.88.35
-      DB_NAME: calminer_test
-      DB_USER: calminer
-      DB_PASSWORD: calminer_password
-      REGISTRY_CONTAINER_NAME: calminer
-    runs-on: ubuntu-latest
-
-    services:
-      postgres:
-        image: postgres:17
-        env:
-          POSTGRES_USER: ${{ env.DB_USER }}
-          POSTGRES_PASSWORD: ${{ env.DB_PASSWORD }}
-          POSTGRES_DB: ${{ env.DB_NAME }}
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: "3.12"
-
-      - name: Get pip cache dir
-        id: pip-cache
-        run: |
-          echo "path=$(pip cache dir)" >> $GITEA_OUTPUT
-          echo "Pip cache dir: $(pip cache dir)"
-
-      - name: Cache pip dependencies
-        uses: actions/cache@v4
-        with:
-          path: ${{ steps.pip-cache.outputs.path }}
-          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt', 'requirements-test.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-
-
-      - name: Update apt-cacher-ng config
-        run: |-
-          echo 'Acquire::http::Proxy "{{ env.APT_CACHER_NG }}";' | tee /etc/apt/apt.conf.d/01apt-cacher-ng
-          apt-get update
-
-      - name: Update system packages
-        run: apt-get upgrade -y
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
-          pip install -r requirements-test.txt
-
-      - name: Install Playwright system dependencies
-        run: playwright install-deps
-
-      - name: Install Playwright browsers
-        run: playwright install
-
-      - name: Run tests
-        env:
-          DATABASE_DRIVER: ${{ env.DB_DRIVER }}
-          DATABASE_HOST: postgres
-          DATABASE_PORT: 5432
-          DATABASE_USER: ${{ env.DB_USER }}
-          DATABASE_PASSWORD: ${{ env.DB_PASSWORD }}
-          DATABASE_NAME: ${{ env.DB_NAME }}
-        run: |
-          pytest tests/ --cov=.
-
-      - name: Build Docker image
-        run: |
-          docker build -t ${{ env.REGISTRY_CONTAINER_NAME }} .
-
-  build:
-    runs-on: ubuntu-latest
-    needs: test
-    env:
-      DEFAULT_BRANCH: main
-      REGISTRY_URL: ${{ secrets.REGISTRY_URL }}
-      REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
-      REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
-      REGISTRY_CONTAINER_NAME: calminer
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Collect workflow metadata
-        id: meta
-        shell: bash
-        run: |
-          ref_name="${GITHUB_REF_NAME:-${GITHUB_REF##*/}}"
-          event_name="${GITHUB_EVENT_NAME:-}"
-          sha="${GITHUB_SHA:-}"
-
-          if [ "$ref_name" = "${DEFAULT_BRANCH:-main}" ]; then
-            echo "on_default=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "on_default=false" >> "$GITHUB_OUTPUT"
-          fi
-
-          echo "ref_name=$ref_name" >> "$GITHUB_OUTPUT"
-          echo "event_name=$event_name" >> "$GITHUB_OUTPUT"
-          echo "sha=$sha" >> "$GITHUB_OUTPUT"
-
-      - name: Set up QEMU and Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Log in to gitea registry
-        if: ${{ steps.meta.outputs.on_default == 'true' }}
-        uses: docker/login-action@v3
-        continue-on-error: true
-        with:
-          registry: ${{ env.REGISTRY_URL }}
-          username: ${{ env.REGISTRY_USERNAME }}
-          password: ${{ env.REGISTRY_PASSWORD }}
-
-      - name: Build and push image
-        uses: docker/build-push-action@v5
-        with:
-          context: .
-          file: Dockerfile
-          push: ${{ steps.meta.outputs.on_default == 'true' && steps.meta.outputs.event_name != 'pull_request' && (env.REGISTRY_URL != '' && env.REGISTRY_USERNAME != '' && env.REGISTRY_PASSWORD != '') }}
-          tags: |
-            ${{ env.REGISTRY_URL }}/allucanget/${{ env.REGISTRY_CONTAINER_NAME }}:latest
-            ${{ env.REGISTRY_URL }}/allucanget/${{ env.REGISTRY_CONTAINER_NAME }}:${{ steps.meta.outputs.sha }}

.gitea/workflows/deploy-coolify.yml

@@ -0,0 +1,78 @@
+name: Deploy - Coolify
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      COOLIFY_BASE_URL: ${{ secrets.COOLIFY_BASE_URL }}
+      COOLIFY_API_TOKEN: ${{ secrets.COOLIFY_API_TOKEN }}
+      COOLIFY_APPLICATION_ID: ${{ secrets.COOLIFY_APPLICATION_ID }}
+      COOLIFY_DEPLOY_ENV: ${{ secrets.COOLIFY_DEPLOY_ENV }}
+      DOCKER_COMPOSE_PATH: docker-compose.prod.yml
+      ENV_FILE_PATH: deploy/.env
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Prepare compose bundle
+        run: |
+          set -euo pipefail
+          mkdir -p deploy
+          cp "$DOCKER_COMPOSE_PATH" deploy/docker-compose.yml
+          if [ -n "$COOLIFY_DEPLOY_ENV" ]; then
+            printf '%s\n' "$COOLIFY_DEPLOY_ENV" > "$ENV_FILE_PATH"
+          elif [ ! -f "$ENV_FILE_PATH" ]; then
+            echo "::error::COOLIFY_DEPLOY_ENV secret not configured and deploy/.env missing" >&2
+            exit 1
+          fi
+
+      - name: Validate Coolify secrets
+        run: |
+          set -euo pipefail
+          missing=0
+          for var in COOLIFY_BASE_URL COOLIFY_API_TOKEN COOLIFY_APPLICATION_ID; do
+            if [ -z "${!var}" ]; then
+              echo "::error::Missing required secret: $var"
+              missing=1
+            fi
+          done
+          if [ "$missing" -eq 1 ]; then
+            exit 1
+          fi
+
+      - name: Trigger deployment via Coolify API
+        run: |
+          set -euo pipefail
+          api_url="$COOLIFY_BASE_URL/api/v1/deploy"
+          payload=$(jq -n --arg uuid "$COOLIFY_APPLICATION_ID" '{ uuid: $uuid }')
+          response=$(curl -sS -w '\n%{http_code}' \
+            -X POST "$api_url" \
+            -H "Authorization: Bearer $COOLIFY_API_TOKEN" \
+            -H "Content-Type: application/json" \
+            -d "$payload")
+          body=$(echo "$response" | head -n -1)
+          status=$(echo "$response" | tail -n1)
+          echo "Deploy response status: $status"
+          echo "$body"
+          printf '%s' "$body" > deploy/coolify-response.json
+          if [ "$status" -ge 400 ]; then
+            echo "::error::Deployment request failed"
+            exit 1
+          fi
+
+      - name: Upload deployment bundle
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: coolify-deploy-bundle
+          path: |
+            deploy/docker-compose.yml
+            deploy/.env
+            deploy/coolify-response.json
+          if-no-files-found: warn

.gitignore

@@ -17,6 +17,7 @@ env/
 # environment variables
 .env
 *.env
+.env.*
 # except example files
 !config/*.env.example
 
@@ -46,8 +47,14 @@ htmlcov/
 logs/
 
 # SQLite database
+data/
 *.sqlite3
 test*.db
+local*.db
 
 # Act runner files
 .runner
+
+# Devcontainer files
+.devcontainer/devcontainer.json
+.devcontainer/docker-compose.yml

.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.1
+    hooks:
+      - id: ruff
+  - repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 24.8.0
+    hooks:
+      - id: black
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.7.9
+    hooks:
+      - id: bandit

Dockerfile

@@ -41,8 +41,25 @@ if url:
         finally:
             sock.close()
 PY
-apt-get update
-apt-get install -y --no-install-recommends build-essential gcc libpq-dev
+APT_PROXY_CONFIG=/etc/apt/apt.conf.d/01proxy
+
+apt_update_with_fallback() {
+    if ! apt-get update; then
+        rm -f "$APT_PROXY_CONFIG"
+        apt-get update
+    fi
+}
+
+apt_install_with_fallback() {
+    if ! apt-get install -y --no-install-recommends "$@"; then
+        rm -f "$APT_PROXY_CONFIG"
+        apt-get update
+        apt-get install -y --no-install-recommends "$@"
+    fi
+}
+
+apt_update_with_fallback
+apt_install_with_fallback build-essential gcc libpq-dev
 pip install --upgrade pip
 pip wheel --no-deps --wheel-dir /wheels -r requirements.txt
 apt-get purge -y --auto-remove build-essential gcc
@@ -88,8 +105,25 @@ if url:
         finally:
             sock.close()
 PY
-apt-get update
-apt-get install -y --no-install-recommends libpq5
+APT_PROXY_CONFIG=/etc/apt/apt.conf.d/01proxy
+
+apt_update_with_fallback() {
+    if ! apt-get update; then
+        rm -f "$APT_PROXY_CONFIG"
+        apt-get update
+    fi
+}
+
+apt_install_with_fallback() {
+    if ! apt-get install -y --no-install-recommends "$@"; then
+        rm -f "$APT_PROXY_CONFIG"
+        apt-get update
+        apt-get install -y --no-install-recommends "$@"
+    fi
+}
+
+apt_update_with_fallback
+apt_install_with_fallback libpq5
 rm -rf /var/lib/apt/lists/*
 EOF
 
@@ -102,13 +136,12 @@ RUN pip install --upgrade pip \
 
 COPY . /app
 
-RUN chown -R appuser:app /app \
-    && chmod +x /app/scripts/docker-entrypoint.sh
+RUN chown -R appuser:app /app
 
 USER appuser
 
 EXPOSE 8003
 
-ENTRYPOINT ["/app/scripts/docker-entrypoint.sh"]
+ENTRYPOINT ["uvicorn"]
 
-CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8003", "--workers", "4"]
+CMD ["main:app", "--host", "0.0.0.0", "--port", "8003", "--workers", "4"]

README.md

@@ -8,4 +8,6 @@ The system is designed to help mining companies make informed decisions by simul
 
 ## Documentation & quickstart
 
-This repository contains only code. See detailed developer and architecture documentation in the [Docs](https://git.allucanget.biz/allucanget/calminer-docs) repository.
+- Detailed developer, architecture, and operations guides live in the companion [calminer-docs](../calminer-docs/) repository. Please see the [README](../calminer-docs/README.md) there for instructions.
+- For a local run, create a `.env` (see `.env.example`), install requirements, then execute `python -m scripts.init_db` followed by `uvicorn main:app --reload`. The initializer is safe to rerun and seeds demo data automatically.
+- To wipe and recreate the schema in development, run `CALMINER_ENV=development python -m scripts.reset_db` before invoking the initializer again.

alembic.ini

@@ -1,35 +0,0 @@
-[alembic]
-script_location = alembic
-sqlalchemy.url = %(DATABASE_URL)s
-
-[loggers]
-keys = root,sqlalchemy,alembic
-
-[handlers]
-keys = console
-
-[formatters]
-keys = generic
-
-[logger_root]
-level = WARN
-handlers = console
-
-[logger_sqlalchemy]
-level = WARN
-handlers =
-qualname = sqlalchemy.engine
-
-[logger_alembic]
-level = INFO
-handlers =
-qualname = alembic
-
-[handler_console]
-class = StreamHandler
-args = (sys.stderr,)
-level = NOTSET
-formatter = generic
-
-[formatter_generic]
-format = %(levelname)-5.5s [%(name)s] %(message)s

alembic/env.py

@@ -1,63 +0,0 @@
-from __future__ import annotations
-
-from logging.config import fileConfig
-from typing import Iterable
-
-from alembic import context
-from sqlalchemy import engine_from_config, pool
-
-from config.database import Base, DATABASE_URL
-from models import *  # noqa: F401,F403 - ensure models are imported for metadata registration
-
-# this is the Alembic Config object, which provides access to the values within the .ini file.
-config = context.config
-
-if config.config_file_name is not None:
-    fileConfig(config.config_file_name)
-
-# Interpret the config file for Python logging.
-# This line sets up loggers basically.
-config.set_main_option("sqlalchemy.url", DATABASE_URL)
-
-target_metadata = Base.metadata
-
-
-def run_migrations_offline() -> None:
-    """Run migrations in 'offline' mode."""
-
-    url = config.get_main_option("sqlalchemy.url")
-    context.configure(
-        url=url,
-        target_metadata=target_metadata,
-        literal_binds=True,
-        dialect_opts={"paramstyle": "named"},
-    )
-
-    with context.begin_transaction():
-        context.run_migrations()
-
-
-def run_migrations_online() -> None:
-    """Run migrations in 'online' mode."""
-
-    connectable = engine_from_config(
-        config.get_section(config.config_ini_section, {}),
-        prefix="sqlalchemy.",
-        poolclass=pool.NullPool,
-    )
-
-    with connectable.connect() as connection:
-        context.configure(connection=connection, target_metadata=target_metadata)
-
-        with context.begin_transaction():
-            context.run_migrations()
-
-
-def run_migrations() -> None:
-    if context.is_offline_mode():
-        run_migrations_offline()
-    else:
-        run_migrations_online()
-
-
-run_migrations()

alembic/script.py.mako

@@ -1,17 +0,0 @@
-"""${message}"""
-
-revision = ${repr(revision)}
-down_revision = ${repr(down_revision)}
-branch_labels = ${repr(branch_labels)}
-depends_on = ${repr(depends_on)}
-
-from alembic import op
-import sqlalchemy as sa
-
-
-def upgrade() -> None:
-    ${upgrades if upgrades else "pass"}
-
-
-def downgrade() -> None:
-    ${downgrades if downgrades else "pass"}

alembic/versions/20251111_00_initial_schema.py

@@ -1,718 +0,0 @@
-"""Combined initial schema"""
-
-from __future__ import annotations
-
-from datetime import datetime, timezone
-
-from alembic import op
-import sqlalchemy as sa
-from passlib.context import CryptContext
-from sqlalchemy.sql import column, table
-
-# revision identifiers, used by Alembic.
-revision = "20251111_00"
-down_revision = None
-branch_labels = None
-depends_on = None
-
-password_context = CryptContext(schemes=["argon2"], deprecated="auto")
-
-mining_operation_type = sa.Enum(
-    "open_pit",
-    "underground",
-    "in_situ_leach",
-    "placer",
-    "quarry",
-    "mountaintop_removal",
-    "other",
-    name="miningoperationtype",
-)
-
-scenario_status = sa.Enum(
-    "draft",
-    "active",
-    "archived",
-    name="scenariostatus",
-)
-
-financial_category = sa.Enum(
-    "capex",
-    "opex",
-    "revenue",
-    "contingency",
-    "other",
-    name="financialcategory",
-)
-
-cost_bucket = sa.Enum(
-    "capital_initial",
-    "capital_sustaining",
-    "operating_fixed",
-    "operating_variable",
-    "maintenance",
-    "reclamation",
-    "royalties",
-    "general_admin",
-    name="costbucket",
-)
-
-distribution_type = sa.Enum(
-    "normal",
-    "triangular",
-    "uniform",
-    "lognormal",
-    "custom",
-    name="distributiontype",
-)
-
-stochastic_variable = sa.Enum(
-    "ore_grade",
-    "recovery_rate",
-    "metal_price",
-    "operating_cost",
-    "capital_cost",
-    "discount_rate",
-    "throughput",
-    name="stochasticvariable",
-)
-
-resource_type = sa.Enum(
-    "diesel",
-    "electricity",
-    "water",
-    "explosives",
-    "reagents",
-    "labor",
-    "equipment_hours",
-    "tailings_capacity",
-    name="resourcetype",
-)
-
-
-DEFAULT_PRICING_SLUG = "default"
-
-
-def _ensure_default_pricing_settings(connection) -> int:
-    settings_table = table(
-        "pricing_settings",
-        column("id", sa.Integer()),
-        column("slug", sa.String()),
-        column("name", sa.String()),
-        column("description", sa.Text()),
-        column("default_currency", sa.String()),
-        column("default_payable_pct", sa.Numeric()),
-        column("moisture_threshold_pct", sa.Numeric()),
-        column("moisture_penalty_per_pct", sa.Numeric()),
-        column("created_at", sa.DateTime(timezone=True)),
-        column("updated_at", sa.DateTime(timezone=True)),
-    )
-
-    existing = connection.execute(
-        sa.select(settings_table.c.id).where(
-            settings_table.c.slug == DEFAULT_PRICING_SLUG
-        )
-    ).scalar_one_or_none()
-    if existing is not None:
-        return existing
-
-    now = datetime.now(timezone.utc)
-    insert_stmt = settings_table.insert().values(
-        slug=DEFAULT_PRICING_SLUG,
-        name="Default Pricing",
-        description="Automatically generated default pricing settings.",
-        default_currency="USD",
-        default_payable_pct=100.0,
-        moisture_threshold_pct=8.0,
-        moisture_penalty_per_pct=0.0,
-        created_at=now,
-        updated_at=now,
-    )
-    result = connection.execute(insert_stmt)
-    default_id = result.inserted_primary_key[0]
-    if default_id is None:
-        default_id = connection.execute(
-            sa.select(settings_table.c.id).where(
-                settings_table.c.slug == DEFAULT_PRICING_SLUG
-            )
-        ).scalar_one()
-    return default_id
-
-
-def upgrade() -> None:
-    bind = op.get_bind()
-
-    # Enumerations
-    mining_operation_type.create(bind, checkfirst=True)
-    scenario_status.create(bind, checkfirst=True)
-    financial_category.create(bind, checkfirst=True)
-    cost_bucket.create(bind, checkfirst=True)
-    distribution_type.create(bind, checkfirst=True)
-    stochastic_variable.create(bind, checkfirst=True)
-    resource_type.create(bind, checkfirst=True)
-
-    # Pricing settings core tables
-    op.create_table(
-        "pricing_settings",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column("name", sa.String(length=128), nullable=False),
-        sa.Column("slug", sa.String(length=64), nullable=False),
-        sa.Column("description", sa.Text(), nullable=True),
-        sa.Column("default_currency", sa.String(length=3), nullable=True),
-        sa.Column(
-            "default_payable_pct",
-            sa.Numeric(precision=5, scale=2),
-            nullable=False,
-            server_default=sa.text("100.00"),
-        ),
-        sa.Column(
-            "moisture_threshold_pct",
-            sa.Numeric(precision=5, scale=2),
-            nullable=False,
-            server_default=sa.text("8.00"),
-        ),
-        sa.Column(
-            "moisture_penalty_per_pct",
-            sa.Numeric(precision=14, scale=4),
-            nullable=False,
-            server_default=sa.text("0.0000"),
-        ),
-        sa.Column("metadata", sa.JSON(), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.UniqueConstraint("name", name="uq_pricing_settings_name"),
-        sa.UniqueConstraint("slug", name="uq_pricing_settings_slug"),
-    )
-    op.create_index(
-        op.f("ix_pricing_settings_id"),
-        "pricing_settings",
-        ["id"],
-        unique=False,
-    )
-
-    op.create_table(
-        "pricing_metal_settings",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column(
-            "pricing_settings_id",
-            sa.Integer(),
-            sa.ForeignKey("pricing_settings.id", ondelete="CASCADE"),
-            nullable=False,
-        ),
-        sa.Column("metal_code", sa.String(length=32), nullable=False),
-        sa.Column("payable_pct", sa.Numeric(
-            precision=5, scale=2), nullable=True),
-        sa.Column(
-            "moisture_threshold_pct",
-            sa.Numeric(precision=5, scale=2),
-            nullable=True,
-        ),
-        sa.Column(
-            "moisture_penalty_per_pct",
-            sa.Numeric(precision=14, scale=4),
-            nullable=True,
-        ),
-        sa.Column("data", sa.JSON(), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.UniqueConstraint(
-            "pricing_settings_id",
-            "metal_code",
-            name="uq_pricing_metal_settings_code",
-        ),
-    )
-    op.create_index(
-        op.f("ix_pricing_metal_settings_id"),
-        "pricing_metal_settings",
-        ["id"],
-        unique=False,
-    )
-    op.create_index(
-        op.f("ix_pricing_metal_settings_pricing_settings_id"),
-        "pricing_metal_settings",
-        ["pricing_settings_id"],
-        unique=False,
-    )
-
-    op.create_table(
-        "pricing_impurity_settings",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column(
-            "pricing_settings_id",
-            sa.Integer(),
-            sa.ForeignKey("pricing_settings.id", ondelete="CASCADE"),
-            nullable=False,
-        ),
-        sa.Column("impurity_code", sa.String(length=32), nullable=False),
-        sa.Column(
-            "threshold_ppm",
-            sa.Numeric(precision=14, scale=4),
-            nullable=False,
-            server_default=sa.text("0.0000"),
-        ),
-        sa.Column(
-            "penalty_per_ppm",
-            sa.Numeric(precision=14, scale=4),
-            nullable=False,
-            server_default=sa.text("0.0000"),
-        ),
-        sa.Column("notes", sa.Text(), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.UniqueConstraint(
-            "pricing_settings_id",
-            "impurity_code",
-            name="uq_pricing_impurity_settings_code",
-        ),
-    )
-    op.create_index(
-        op.f("ix_pricing_impurity_settings_id"),
-        "pricing_impurity_settings",
-        ["id"],
-        unique=False,
-    )
-    op.create_index(
-        op.f("ix_pricing_impurity_settings_pricing_settings_id"),
-        "pricing_impurity_settings",
-        ["pricing_settings_id"],
-        unique=False,
-    )
-
-    # Core domain tables
-    op.create_table(
-        "projects",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("name", sa.String(length=255), nullable=False),
-        sa.Column("location", sa.String(length=255), nullable=True),
-        sa.Column("operation_type", mining_operation_type, nullable=False),
-        sa.Column("description", sa.Text(), nullable=True),
-        sa.Column(
-            "pricing_settings_id",
-            sa.Integer(),
-            sa.ForeignKey("pricing_settings.id", ondelete="SET NULL"),
-            nullable=True,
-        ),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            server_default=sa.func.now(),
-            nullable=False,
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            server_default=sa.func.now(),
-            nullable=False,
-        ),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint("name"),
-    )
-    op.create_index(op.f("ix_projects_id"), "projects", ["id"], unique=False)
-    op.create_index(
-        "ix_projects_pricing_settings_id",
-        "projects",
-        ["pricing_settings_id"],
-        unique=False,
-    )
-
-    op.create_table(
-        "scenarios",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("project_id", sa.Integer(), nullable=False),
-        sa.Column("name", sa.String(length=255), nullable=False),
-        sa.Column("description", sa.Text(), nullable=True),
-        sa.Column("status", scenario_status, nullable=False),
-        sa.Column("start_date", sa.Date(), nullable=True),
-        sa.Column("end_date", sa.Date(), nullable=True),
-        sa.Column("discount_rate", sa.Numeric(
-            precision=5, scale=2), nullable=True),
-        sa.Column("currency", sa.String(length=3), nullable=True),
-        sa.Column("primary_resource", resource_type, nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            server_default=sa.func.now(),
-            nullable=False,
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            server_default=sa.func.now(),
-            nullable=False,
-        ),
-        sa.ForeignKeyConstraint(
-            ["project_id"], ["projects.id"], ondelete="CASCADE"),
-        sa.PrimaryKeyConstraint("id"),
-    )
-    op.create_index(op.f("ix_scenarios_id"), "scenarios", ["id"], unique=False)
-    op.create_index(
-        op.f("ix_scenarios_project_id"),
-        "scenarios",
-        ["project_id"],
-        unique=False,
-    )
-
-    op.create_table(
-        "financial_inputs",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("scenario_id", sa.Integer(), nullable=False),
-        sa.Column("name", sa.String(length=255), nullable=False),
-        sa.Column("category", financial_category, nullable=False),
-        sa.Column("cost_bucket", cost_bucket, nullable=True),
-        sa.Column("amount", sa.Numeric(precision=18, scale=2), nullable=False),
-        sa.Column("currency", sa.String(length=3), nullable=True),
-        sa.Column("effective_date", sa.Date(), nullable=True),
-        sa.Column("notes", sa.Text(), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            server_default=sa.func.now(),
-            nullable=False,
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            server_default=sa.func.now(),
-            nullable=False,
-        ),
-        sa.ForeignKeyConstraint(
-            ["scenario_id"], ["scenarios.id"], ondelete="CASCADE"),
-        sa.PrimaryKeyConstraint("id"),
-    )
-    op.create_index(
-        op.f("ix_financial_inputs_id"),
-        "financial_inputs",
-        ["id"],
-        unique=False,
-    )
-    op.create_index(
-        op.f("ix_financial_inputs_scenario_id"),
-        "financial_inputs",
-        ["scenario_id"],
-        unique=False,
-    )
-
-    op.create_table(
-        "simulation_parameters",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("scenario_id", sa.Integer(), nullable=False),
-        sa.Column("name", sa.String(length=255), nullable=False),
-        sa.Column("distribution", distribution_type, nullable=False),
-        sa.Column("variable", stochastic_variable, nullable=True),
-        sa.Column("resource_type", resource_type, nullable=True),
-        sa.Column("mean_value", sa.Numeric(
-            precision=18, scale=4), nullable=True),
-        sa.Column(
-            "standard_deviation",
-            sa.Numeric(precision=18, scale=4),
-            nullable=True,
-        ),
-        sa.Column(
-            "minimum_value",
-            sa.Numeric(precision=18, scale=4),
-            nullable=True,
-        ),
-        sa.Column(
-            "maximum_value",
-            sa.Numeric(precision=18, scale=4),
-            nullable=True,
-        ),
-        sa.Column("unit", sa.String(length=32), nullable=True),
-        sa.Column("configuration", sa.JSON(), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            server_default=sa.func.now(),
-            nullable=False,
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            server_default=sa.func.now(),
-            nullable=False,
-        ),
-        sa.ForeignKeyConstraint(
-            ["scenario_id"], ["scenarios.id"], ondelete="CASCADE"),
-        sa.PrimaryKeyConstraint("id"),
-    )
-    op.create_index(
-        op.f("ix_simulation_parameters_id"),
-        "simulation_parameters",
-        ["id"],
-        unique=False,
-    )
-    op.create_index(
-        op.f("ix_simulation_parameters_scenario_id"),
-        "simulation_parameters",
-        ["scenario_id"],
-        unique=False,
-    )
-
-    # Authentication and RBAC tables
-    op.create_table(
-        "users",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column("email", sa.String(length=255), nullable=False),
-        sa.Column("username", sa.String(length=128), nullable=False),
-        sa.Column("password_hash", sa.String(length=255), nullable=False),
-        sa.Column("is_active", sa.Boolean(),
-                  nullable=False, server_default=sa.true()),
-        sa.Column(
-            "is_superuser",
-            sa.Boolean(),
-            nullable=False,
-            server_default=sa.false(),
-        ),
-        sa.Column("last_login_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.UniqueConstraint("email", name="uq_users_email"),
-        sa.UniqueConstraint("username", name="uq_users_username"),
-    )
-    op.create_index(
-        "ix_users_active_superuser",
-        "users",
-        ["is_active", "is_superuser"],
-        unique=False,
-    )
-
-    op.create_table(
-        "roles",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column("name", sa.String(length=64), nullable=False),
-        sa.Column("display_name", sa.String(length=128), nullable=False),
-        sa.Column("description", sa.Text(), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.UniqueConstraint("name", name="uq_roles_name"),
-    )
-
-    op.create_table(
-        "user_roles",
-        sa.Column("user_id", sa.Integer(), nullable=False),
-        sa.Column("role_id", sa.Integer(), nullable=False),
-        sa.Column(
-            "granted_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column("granted_by", sa.Integer(), nullable=True),
-        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["role_id"], ["roles.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(
-            ["granted_by"], ["users.id"], ondelete="SET NULL"),
-        sa.PrimaryKeyConstraint("user_id", "role_id"),
-        sa.UniqueConstraint("user_id", "role_id",
-                            name="uq_user_roles_user_role"),
-    )
-    op.create_index(
-        "ix_user_roles_role_id",
-        "user_roles",
-        ["role_id"],
-        unique=False,
-    )
-
-    # Seed roles and default admin
-    roles_table = table(
-        "roles",
-        column("id", sa.Integer()),
-        column("name", sa.String()),
-        column("display_name", sa.String()),
-        column("description", sa.Text()),
-    )
-
-    op.bulk_insert(
-        roles_table,
-        [
-            {
-                "id": 1,
-                "name": "admin",
-                "display_name": "Administrator",
-                "description": "Full platform access with user management rights.",
-            },
-            {
-                "id": 2,
-                "name": "project_manager",
-                "display_name": "Project Manager",
-                "description": "Manage projects, scenarios, and associated data.",
-            },
-            {
-                "id": 3,
-                "name": "analyst",
-                "display_name": "Analyst",
-                "description": "Review dashboards and scenario outputs.",
-            },
-            {
-                "id": 4,
-                "name": "viewer",
-                "display_name": "Viewer",
-                "description": "Read-only access to assigned projects and reports.",
-            },
-        ],
-    )
-
-    admin_password_hash = password_context.hash("ChangeMe123!")
-
-    users_table = table(
-        "users",
-        column("id", sa.Integer()),
-        column("email", sa.String()),
-        column("username", sa.String()),
-        column("password_hash", sa.String()),
-        column("is_active", sa.Boolean()),
-        column("is_superuser", sa.Boolean()),
-    )
-
-    op.bulk_insert(
-        users_table,
-        [
-            {
-                "id": 1,
-                "email": "admin@calminer.local",
-                "username": "admin",
-                "password_hash": admin_password_hash,
-                "is_active": True,
-                "is_superuser": True,
-            }
-        ],
-    )
-
-    user_roles_table = table(
-        "user_roles",
-        column("user_id", sa.Integer()),
-        column("role_id", sa.Integer()),
-        column("granted_by", sa.Integer()),
-    )
-
-    op.bulk_insert(
-        user_roles_table,
-        [
-            {
-                "user_id": 1,
-                "role_id": 1,
-                "granted_by": 1,
-            }
-        ],
-    )
-
-    # Ensure a default pricing settings record exists for future project linkage
-    _ensure_default_pricing_settings(bind)
-
-
-def downgrade() -> None:
-    # Drop RBAC
-    op.drop_index("ix_user_roles_role_id", table_name="user_roles")
-    op.drop_table("user_roles")
-
-    op.drop_table("roles")
-
-    op.drop_index("ix_users_active_superuser", table_name="users")
-    op.drop_table("users")
-
-    # Drop domain tables
-    op.drop_index(
-        op.f("ix_simulation_parameters_scenario_id"),
-        table_name="simulation_parameters",
-    )
-    op.drop_index(op.f("ix_simulation_parameters_id"),
-                  table_name="simulation_parameters")
-    op.drop_table("simulation_parameters")
-
-    op.drop_index(
-        op.f("ix_financial_inputs_scenario_id"), table_name="financial_inputs"
-    )
-    op.drop_index(op.f("ix_financial_inputs_id"),
-                  table_name="financial_inputs")
-    op.drop_table("financial_inputs")
-
-    op.drop_index(op.f("ix_scenarios_project_id"), table_name="scenarios")
-    op.drop_index(op.f("ix_scenarios_id"), table_name="scenarios")
-    op.drop_table("scenarios")
-
-    op.drop_index("ix_projects_pricing_settings_id", table_name="projects")
-    op.drop_index(op.f("ix_projects_id"), table_name="projects")
-    op.drop_table("projects")
-
-    # Drop pricing settings ancillary tables
-    op.drop_index(
-        op.f("ix_pricing_impurity_settings_pricing_settings_id"),
-        table_name="pricing_impurity_settings",
-    )
-    op.drop_index(
-        op.f("ix_pricing_impurity_settings_id"),
-        table_name="pricing_impurity_settings",
-    )
-    op.drop_table("pricing_impurity_settings")
-
-    op.drop_index(
-        op.f("ix_pricing_metal_settings_pricing_settings_id"),
-        table_name="pricing_metal_settings",
-    )
-    op.drop_index(
-        op.f("ix_pricing_metal_settings_id"),
-        table_name="pricing_metal_settings",
-    )
-    op.drop_table("pricing_metal_settings")
-
-    op.drop_index(op.f("ix_pricing_settings_id"),
-                  table_name="pricing_settings")
-    op.drop_table("pricing_settings")
-
-    # Drop enumerations
-    resource_type.drop(op.get_bind(), checkfirst=True)
-    stochastic_variable.drop(op.get_bind(), checkfirst=True)
-    distribution_type.drop(op.get_bind(), checkfirst=True)
-    cost_bucket.drop(op.get_bind(), checkfirst=True)
-    financial_category.drop(op.get_bind(), checkfirst=True)
-    scenario_status.drop(op.get_bind(), checkfirst=True)
-    mining_operation_type.drop(op.get_bind(), checkfirst=True)

changelog.md

@@ -1,51 +1,124 @@
 # Changelog
 
-## 2025-11-09
+## 2025-11-15
 
-- Captured current implementation status, requirements coverage, missing features, and prioritized roadmap in `calminer-docs/implementation_status.md` to guide future development.
-- Added core SQLAlchemy domain models, shared metadata descriptors, and Alembic migration setup (with initial schema snapshot) to establish the persistence layer foundation.
-- Introduced repository and unit-of-work helpers for projects, scenarios, financial inputs, and simulation parameters to support service-layer operations.
-- Added SQLite-backed pytest coverage for repository and unit-of-work behaviours to validate persistence interactions.
-- Exposed project and scenario CRUD APIs with validated schemas and integrated them into the FastAPI application.
-- Connected project and scenario routers to new Jinja2 list/detail/edit views with HTML forms and redirects.
-- Implemented FR-009 client-side enhancements with responsive navigation toggle, mobile-first scenario tables, and shared asset loading across templates.
-- Added scenario comparison validator, FastAPI comparison endpoint, and comprehensive unit tests to enforce FR-009 validation rules through API errors.
-- Delivered a new dashboard experience with `templates/dashboard.html`, dedicated styling, and a FastAPI route supplying real project/scenario metrics via repository helpers.
-- Extended repositories with count/recency utilities and added pytest coverage, including a dashboard rendering smoke test validating empty-state messaging.
-- Brought project and scenario detail pages plus their forms in line with the dashboard visuals, adding metric cards, layout grids, and refreshed CTA styles.
-- Reordered project route registration to prioritize static UI paths, eliminating 422 errors on `/projects/ui` and `/projects/create`, and added pytest smoke coverage for the navigation endpoints.
-- Added end-to-end integration tests for project and scenario lifecycles, validating HTML redirects, template rendering, and API interactions, and updated `ProjectRepository.get` to deduplicate joined loads for detail views.
-- Updated all Jinja2 template responses to the new Starlette signature to eliminate deprecation warnings while keeping request-aware context available to the templates.
-- Introduced `services/security.py` to centralize Argon2 password hashing utilities and JWT creation/verification with typed payloads, and added pytest coverage for hashing, expiry, tampering, and token type mismatch scenarios.
-- Added `routes/auth.py` with registration, login, and password reset flows, refreshed auth templates with error messaging, wired navigation links, and introduced end-to-end pytest coverage for the new forms and token flows.
-- Implemented cookie-based authentication session middleware with automatic access token refresh, logout handling, navigation adjustments, and documentation/test updates capturing the new behaviour.
-- Delivered idempotent seeding utilities with `scripts/initial_data.py`, entry-point runner `scripts/00_initial_data.py`, documentation updates, and pytest coverage to verify role/admin provisioning.
-- Secured project and scenario routers with RBAC guard dependencies, enforced repository access checks via helper utilities, and aligned template routes with FastAPI dependency injection patterns.
+- Fixed dev container setup by reviewing logs, identifying mount errors, implementing fixes, and validating the configuration.
 
-## 2025-11-10
+## 2025-11-14
 
-- Added dedicated pytest coverage for guard dependencies, exercising success plus failure paths (missing session, inactive user, missing roles, project/scenario access errors) via `tests/test_dependencies_guards.py`.
-- Added integration tests in `tests/test_authorization_integration.py` verifying anonymous 401 responses, role-based 403s, and authorized project manager flows across API and UI endpoints.
-- Implemented environment-driven admin bootstrap settings, wired the `bootstrap_admin` helper into FastAPI startup, added pytest coverage for creation/idempotency/reset logic, and documented operational guidance in the RBAC plan and security concept.
-- Retired the legacy authentication RBAC implementation plan document after migrating its guidance into live documentation and synchronized the contributor instructions to reflect the removal.
-- Completed the Authentication & RBAC checklist by shipping the new models, migrations, repositories, guard dependencies, and integration tests.
-- Documented the project/scenario import/export field mapping and file format guidelines in `calminer-docs/requirements/FR-008.md`, and introduced `schemas/imports.py` with Pydantic models that normalise incoming CSV/Excel rows for projects and scenarios.
-- Added `services/importers.py` to load CSV/XLSX files into the new import schemas, pulled in `openpyxl` for Excel support, and covered the parsing behaviour with `tests/test_import_parsing.py`.
-- Expanded the import ingestion workflow with staging previews, transactional persistence commits, FastAPI preview/commit endpoints under `/imports`, and new API tests (`tests/test_import_ingestion.py`, `tests/test_import_api.py`) ensuring end-to-end coverage.
-- Added persistent audit logging via `ImportExportLog`, structured log emission, Prometheus metrics instrumentation, `/metrics` endpoint exposure, and updated operator/deployment documentation to guide monitoring setup.
+- Completed Coolify deployment automation with workflow and documentation.
+- Improved build workflow for registry authentication and tagging.
+- Updated production compose and added deployment guidance.
+- Added optional Kubernetes deployment toggle.
+
+## 2025-11-13
+
+- Aligned UI styles and ensured accessibility.
+- Restructured navigation under project-scenario-calculation hierarchy.
+- Reorganized documentation for better structure.
+- Refactored navigation sidebar with database-driven data.
+- Migrated sidebar rendering to API endpoint.
+- Created templates for data import and export.
+- Updated relationships for projects, scenarios, and profitability.
+- Enhanced scenario frontend templates with project context.
+- Scoped profitability calculator to scenario level.
+- Added navigation links for opex planner.
+- Documented opex planner features.
+- Integrated opex calculations with persistence and tests.
+- Implemented capex calculations end-to-end.
+- Added basic profitability calculations.
+- Developed reporting endpoints and templates.
+- Integrated charting for visualizations.
+- Performed manual testing of capex planner.
+- Added unit tests for opex service.
+- Added integration tests for opex.
+
+## 2025-11-12
+
+- Fixed reporting dashboard error by correcting route reference.
+- Completed navigation validation by adding missing routes and templates for various pages.
+- Fixed template rendering error with URL objects.
+- Integrated charting for interactive visualizations.
+- Verified local application startup and routes.
+- Fixed docker-compose configuration.
+- Verified deployment pipeline.
+- Documented data models.
+- Updated performance model to clear warnings.
+- Replaced migration system with simpler initializer.
+- Removed hardcoded secrets from tests.
+- Centralized security scanning config.
+- Fixed admin setup with migration.
+- Resolved code style warnings.
+- Enhanced deploy logging.
+- Fixed CI template issue.
+- Added SQLite database support.
 
 ## 2025-11-11
 
-- Centralised ISO-4217 currency validation across scenarios, imports, and export filters (`models/scenario.py`, `routes/scenarios.py`, `schemas/scenario.py`, `schemas/imports.py`, `services/export_query.py`) so malformed codes are rejected consistently at every entry point.
-- Updated scenario services and UI flows to surface friendly validation errors and added regression coverage for imports, exports, API creation, and lifecycle flows ensuring currencies are normalised end-to-end.
-- Recorded the completed “Ensure currency is used consistently” work in `.github/instructions/DONE.md` and ran the full pytest suite (150 tests) to verify the refactor.
-- Linked projects to their pricing settings by updating SQLAlchemy models, repositories, seeding utilities, and migrations, and added regression tests to cover the new association and default backfill.
-- Bootstrapped database-stored pricing settings at application startup, aligned initial data seeding with the database-first metadata flow, and added tests covering pricing bootstrap creation, project assignment, and idempotency.
-- Extended pricing configuration support to prefer persisted metadata via `dependencies.get_pricing_metadata`, added retrieval tests for project/default fallbacks, and refreshed docs (`calminer-docs/specifications/price_calculation.md`, `pricing_settings_data_model.md`) to describe the database-backed workflow and bootstrap behaviour.
-- Added `services/financial.py` NPV, IRR, and payback helpers with robust cash-flow normalisation, convergence safeguards, and fractional period support, plus comprehensive pytest coverage exercising representative project scenarios and failure modes.
-- Authored `calminer-docs/specifications/financial_metrics.md` capturing DCF assumptions, solver behaviours, and worked examples, and cross-linked the architecture concepts to the new reference for consistent navigation.
-- Implemented `services/simulation.py` Monte Carlo engine with configurable distributions, summary aggregation, and reproducible RNG seeding, introduced regression tests in `tests/test_simulation.py`, and documented configuration/usage in `calminer-docs/specifications/monte_carlo_simulation.md` with architecture cross-links.
-- Polished reporting HTML contexts by cleaning stray fragments in `routes/reports.py`, adding download action metadata for project and scenario pages, and generating scenario comparison download URLs with correctly serialised repeated `scenario_ids` parameters.
-- Consolidated Alembic history into a single initial migration (`20251111_00_initial_schema.py`), removed superseded revision files, and ensured Alembic metadata still references the project metadata for clean bootstrap.
-- Added `scripts/run_migrations.py` and a Docker entrypoint wrapper to run Alembic migrations before `uvicorn` starts, removed the fallback `Base.metadata.create_all` call, and updated `calminer-docs/admin/installation.md` so developers know how to apply migrations locally or via Docker.
-- Configured pytest defaults to collect coverage (`--cov`) with an 80% fail-under gate, excluded entrypoint/reporting scaffolds from the calculation, updated contributor docs with the standard `pytest` command, and verified the suite now reports 83% coverage.
+- Combined old migration files into one initial schema.
+- Added base routing to redirect users to login or dashboard.
+- Added end-to-end tests for login flow.
+- Updated templates to use logo image consistently.
+- Centralized currency validation across the app.
+- Updated services to show friendly error messages.
+- Linked projects to pricing settings.
+- Bootstrapped pricing settings at startup.
+- Extended pricing support with persisted data.
+- Added financial helpers for NPV, IRR, payback.
+- Documented financial metrics.
+- Implemented Monte Carlo simulation engine.
+- Cleaned up reporting contexts.
+- Consolidated migration history.
+- Added migration script and updated entrypoint.
+- Configured test coverage.
+- Standardized colors and typography.
+- Improved navigation with chevron buttons.
+- Established test suites with coverage.
+- Configured CI pipelines for tests and security.
+- Added deployment automation with Docker and Kubernetes.
+- Completed monitoring instrumentation.
+- Implemented performance monitoring.
+- Added metric storage and endpoints.
+- Created middleware for metrics.
+- Extended monitoring router.
+- Added migration for metrics table.
+- Completed concurrent testing.
+- Implemented deployment automation.
+- Set up Kubernetes manifests.
+- Configured CI/CD workflows.
+- Documented deployment processes.
+- Validated deployment setup.
+
+## 2025-11-10
+
+- Added tests for guard dependencies.
+- Added integration tests for authorization.
+- Implemented admin bootstrap settings.
+- Retired old RBAC plan document.
+- Completed authentication and RBAC features.
+- Documented import/export field mappings.
+- Added import service for CSV/Excel.
+- Expanded import workflow with previews and commits.
+- Added audit logging for imports/exports.
+
+## 2025-11-09
+
+- Captured implementation status and roadmap.
+- Added core database models and migration setup.
+- Introduced repository helpers for data operations.
+- Added tests for repository behaviors.
+- Exposed CRUD APIs for projects and scenarios.
+- Connected routers to HTML views.
+- Implemented client-side enhancements.
+- Added scenario comparison validator.
+- Delivered new dashboard experience.
+- Extended repositories with utilities.
+- Updated detail pages with new visuals.
+- Fixed route registration issues.
+- Added end-to-end tests for lifecycles.
+- Updated template responses.
+- Introduced security utilities.
+- Added authentication routes.
+- Implemented session middleware.
+- Delivered seeding utilities.
+- Secured routers with RBAC.

config/database.py

@@ -11,12 +11,21 @@ def _build_database_url() -> str:
     """Construct the SQLAlchemy database URL from granular environment vars.
 
     Falls back to `DATABASE_URL` for backward compatibility.
+    Supports SQLite when CALMINER_USE_SQLITE is set.
     """
 
     legacy_url = os.environ.get("DATABASE_URL", "")
     if legacy_url and legacy_url.strip() != "":
         return legacy_url
 
+    use_sqlite = os.environ.get("CALMINER_USE_SQLITE", "").lower() in ("true", "1", "yes")
+    if use_sqlite:
+        # Use SQLite database
+        db_path = os.environ.get("DATABASE_PATH", "./data/calminer.db")
+        # Ensure the directory exists
+        os.makedirs(os.path.dirname(db_path), exist_ok=True)
+        return f"sqlite:///{db_path}"
+
     driver = os.environ.get("DATABASE_DRIVER", "postgresql")
     host = os.environ.get("DATABASE_HOST")
     port = os.environ.get("DATABASE_PORT", "5432")
@@ -54,7 +63,15 @@ def _build_database_url() -> str:
 DATABASE_URL = _build_database_url()
 
 engine = create_engine(DATABASE_URL, echo=True, future=True)
-SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+# Avoid expiring ORM objects on commit so that objects returned from UnitOfWork
+# remain usable for the duration of the request cycle without causing
+# DetachedInstanceError when accessed after the session commits.
+SessionLocal = sessionmaker(
+    autocommit=False,
+    autoflush=False,
+    bind=engine,
+    expire_on_commit=False,
+)
 Base = declarative_base()
 
 

dependencies.py

@@ -23,6 +23,7 @@ from services.session import (
 from services.unit_of_work import UnitOfWork
 from services.importers import ImportIngestionService
 from services.pricing import PricingMetadata
+from services.navigation import NavigationService
 from services.scenario_evaluation import ScenarioPricingConfig, ScenarioPricingEvaluator
 from services.repositories import pricing_settings_to_metadata
 
@@ -64,6 +65,14 @@ def get_pricing_metadata(
     return pricing_settings_to_metadata(seed_result.settings)
 
 
+def get_navigation_service(
+    uow: UnitOfWork = Depends(get_unit_of_work),
+) -> NavigationService:
+    if not uow.navigation:
+        raise RuntimeError("Navigation repository is not initialised")
+    return NavigationService(uow.navigation)
+
+
 def get_pricing_evaluator(
     metadata: PricingMetadata = Depends(get_pricing_metadata),
 ) -> ScenarioPricingEvaluator:
@@ -153,6 +162,28 @@ def require_authenticated_user(
     return user
 
 
+def require_authenticated_user_html(
+    request: Request,
+    session: AuthSession = Depends(get_auth_session),
+) -> User:
+    """HTML-aware authenticated dependency that redirects anonymous sessions."""
+
+    user = session.user
+    if user is None or session.tokens.is_empty:
+        login_url = str(request.url_for("auth.login_form"))
+        raise HTTPException(
+            status_code=status.HTTP_303_SEE_OTHER,
+            headers={"Location": login_url},
+        )
+
+    if not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="User account is disabled.",
+        )
+    return user
+
+
 def _user_role_names(user: User) -> set[str]:
     roles: Iterable[Role] = getattr(user, "roles", []) or []
     return {role.name for role in roles}
@@ -186,12 +217,55 @@ def require_any_role(*roles: str) -> Callable[[User], User]:
     return require_roles(*roles)
 
 
-def require_project_resource(*, require_manage: bool = False) -> Callable[[int], Project]:
+def require_roles_html(*roles: str) -> Callable[[Request], User]:
+    """Ensure user is authenticated for HTML responses; redirect anonymous to login."""
+
+    required = tuple(role.strip() for role in roles if role.strip())
+    if not required:
+        raise ValueError("require_roles_html requires at least one role name")
+
+    def _dependency(
+        request: Request,
+        session: AuthSession = Depends(get_auth_session),
+    ) -> User:
+        user = session.user
+        if user is None:
+            login_url = str(request.url_for("auth.login_form"))
+            raise HTTPException(
+                status_code=status.HTTP_303_SEE_OTHER,
+                headers={"Location": login_url},
+            )
+
+        if user.is_superuser:
+            return user
+
+        role_names = _user_role_names(user)
+        if not any(role in role_names for role in required):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Insufficient permissions for this action.",
+            )
+        return user
+
+    return _dependency
+
+
+def require_any_role_html(*roles: str) -> Callable[[Request], User]:
+    """Alias of require_roles_html for readability."""
+
+    return require_roles_html(*roles)
+
+
+def require_project_resource(
+    *,
+    require_manage: bool = False,
+    user_dependency: Callable[..., User] = require_authenticated_user,
+) -> Callable[[int], Project]:
     """Dependency factory that resolves a project with authorization checks."""
 
     def _dependency(
         project_id: int,
-        user: User = Depends(require_authenticated_user),
+        user: User = Depends(user_dependency),
         uow: UnitOfWork = Depends(get_unit_of_work),
     ) -> Project:
         try:
@@ -216,13 +290,16 @@ def require_project_resource(*, require_manage: bool = False) -> Callable[[int],
 
 
 def require_scenario_resource(
-    *, require_manage: bool = False, with_children: bool = False
+    *,
+    require_manage: bool = False,
+    with_children: bool = False,
+    user_dependency: Callable[..., User] = require_authenticated_user,
 ) -> Callable[[int], Scenario]:
     """Dependency factory that resolves a scenario with authorization checks."""
 
     def _dependency(
         scenario_id: int,
-        user: User = Depends(require_authenticated_user),
+        user: User = Depends(user_dependency),
         uow: UnitOfWork = Depends(get_unit_of_work),
     ) -> Scenario:
         try:
@@ -248,14 +325,17 @@ def require_scenario_resource(
 
 
 def require_project_scenario_resource(
-    *, require_manage: bool = False, with_children: bool = False
+    *,
+    require_manage: bool = False,
+    with_children: bool = False,
+    user_dependency: Callable[..., User] = require_authenticated_user,
 ) -> Callable[[int, int], Scenario]:
     """Dependency factory ensuring a scenario belongs to the given project and is accessible."""
 
     def _dependency(
         project_id: int,
         scenario_id: int,
-        user: User = Depends(require_authenticated_user),
+        user: User = Depends(user_dependency),
         uow: UnitOfWork = Depends(get_unit_of_work),
     ) -> Scenario:
         try:
@@ -279,3 +359,42 @@ def require_project_scenario_resource(
             ) from exc
 
     return _dependency
+
+
+def require_project_resource_html(
+    *, require_manage: bool = False
+) -> Callable[[int], Project]:
+    """HTML-aware project loader that redirects anonymous sessions."""
+
+    return require_project_resource(
+        require_manage=require_manage,
+        user_dependency=require_authenticated_user_html,
+    )
+
+
+def require_scenario_resource_html(
+    *,
+    require_manage: bool = False,
+    with_children: bool = False,
+) -> Callable[[int], Scenario]:
+    """HTML-aware scenario loader that redirects anonymous sessions."""
+
+    return require_scenario_resource(
+        require_manage=require_manage,
+        with_children=with_children,
+        user_dependency=require_authenticated_user_html,
+    )
+
+
+def require_project_scenario_resource_html(
+    *,
+    require_manage: bool = False,
+    with_children: bool = False,
+) -> Callable[[int, int], Scenario]:
+    """HTML-aware project-scenario loader redirecting anonymous sessions."""
+
+    return require_project_scenario_resource(
+        require_manage=require_manage,
+        with_children=with_children,
+        user_dependency=require_authenticated_user_html,
+    )

docker-compose.override.yml

@@ -0,0 +1,59 @@
+version: "3.8"
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        APT_CACHE_URL: ${APT_CACHE_URL:-}
+    environment:
+      - ENVIRONMENT=development
+      - DEBUG=true
+      - LOG_LEVEL=DEBUG
+      # Override database to use local postgres service
+      - DATABASE_HOST=postgres
+      - DATABASE_PORT=5432
+      - DATABASE_USER=calminer
+      - DATABASE_PASSWORD=calminer_password
+      - DATABASE_NAME=calminer_db
+      - DATABASE_DRIVER=postgresql
+      # Development-specific settings
+      - CALMINER_EXPORT_MAX_ROWS=1000
+      - CALMINER_IMPORT_MAX_ROWS=10000
+    volumes:
+      # Mount source code for live reloading (if using --reload)
+      - .:/app:ro
+      # Override logs volume to local for easier access
+      - ./logs:/app/logs
+    ports:
+      - "8003:8003"
+    # Override command for development with reload
+    command:
+      [
+        "main:app",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        "8003",
+        "--reload",
+        "--workers",
+        "1",
+      ]
+    depends_on:
+      - postgres
+    restart: unless-stopped
+
+  postgres:
+    environment:
+      - POSTGRES_USER=calminer
+      - POSTGRES_PASSWORD=calminer_password
+      - POSTGRES_DB=calminer_db
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    restart: unless-stopped
+
+volumes:
+  postgres_data:

docker-compose.prod.yml

@@ -0,0 +1,73 @@
+version: "3.8"
+
+services:
+  app:
+    image: git.allucanget.biz/allucanget/calminer:latest
+    environment:
+      - ENVIRONMENT=production
+      - DEBUG=false
+      - LOG_LEVEL=WARNING
+      # Database configuration - must be provided externally
+      - DATABASE_HOST=${DATABASE_HOST}
+      - DATABASE_PORT=${DATABASE_PORT:-5432}
+      - DATABASE_USER=${DATABASE_USER}
+      - DATABASE_PASSWORD=${DATABASE_PASSWORD}
+      - DATABASE_NAME=${DATABASE_NAME}
+      - DATABASE_DRIVER=postgresql
+      # Production-specific settings
+      - CALMINER_EXPORT_MAX_ROWS=100000
+      - CALMINER_IMPORT_MAX_ROWS=100000
+      - CALMINER_EXPORT_METADATA=true
+      - CALMINER_IMPORT_STAGING_TTL=3600
+    ports:
+      - "8003:8003"
+    depends_on:
+      postgres:
+        condition: service_healthy
+    restart: unless-stopped
+    # Production health checks
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8003/health"]
+      interval: 60s
+      timeout: 30s
+      retries: 5
+      start_period: 60s
+    # Resource limits for production
+    deploy:
+      resources:
+        limits:
+          cpus: "1.0"
+          memory: 1G
+        reservations:
+          cpus: "0.5"
+          memory: 512M
+
+  postgres:
+    environment:
+      - POSTGRES_USER=${DATABASE_USER}
+      - POSTGRES_PASSWORD=${DATABASE_PASSWORD}
+      - POSTGRES_DB=${DATABASE_NAME}
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    restart: unless-stopped
+    # Production postgres health check
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${DATABASE_USER} -d ${DATABASE_NAME}"]
+      interval: 60s
+      timeout: 30s
+      retries: 5
+      start_period: 60s
+    # Resource limits for postgres
+    deploy:
+      resources:
+        limits:
+          cpus: "1.0"
+          memory: 2G
+        reservations:
+          cpus: "0.5"
+          memory: 1G
+
+volumes:
+  postgres_data:

docker-compose.staging.yml

@@ -0,0 +1,62 @@
+version: "3.8"
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        APT_CACHE_URL: ${APT_CACHE_URL:-}
+    environment:
+      - ENVIRONMENT=staging
+      - DEBUG=false
+      - LOG_LEVEL=INFO
+      # Database configuration - can be overridden by external env
+      - DATABASE_HOST=${DATABASE_HOST:-postgres}
+      - DATABASE_PORT=${DATABASE_PORT:-5432}
+      - DATABASE_USER=${DATABASE_USER:-calminer}
+      - DATABASE_PASSWORD=${DATABASE_PASSWORD}
+      - DATABASE_NAME=${DATABASE_NAME:-calminer_db}
+      - DATABASE_DRIVER=postgresql
+      # Staging-specific settings
+      - CALMINER_EXPORT_MAX_ROWS=50000
+      - CALMINER_IMPORT_MAX_ROWS=50000
+      - CALMINER_EXPORT_METADATA=true
+      - CALMINER_IMPORT_STAGING_TTL=600
+    ports:
+      - "8003:8003"
+    depends_on:
+      - postgres
+    restart: unless-stopped
+    # Health check for staging
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8003/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+  postgres:
+    environment:
+      - POSTGRES_USER=${DATABASE_USER:-calminer}
+      - POSTGRES_PASSWORD=${DATABASE_PASSWORD}
+      - POSTGRES_DB=${DATABASE_NAME:-calminer_db}
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    restart: unless-stopped
+    # Health check for postgres
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "pg_isready -U ${DATABASE_USER:-calminer} -d ${DATABASE_NAME:-calminer_db}",
+        ]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+
+volumes:
+  postgres_data:

docker-compose.yml

@@ -1,5 +1,3 @@
-version: "3.8"
-
 services:
   app:
     build:
@@ -8,11 +6,13 @@ services:
     ports:
       - "8003:8003"
     environment:
-      - DATABASE_HOST=postgres
-      - DATABASE_PORT=5432
-      - DATABASE_USER=calminer
-      - DATABASE_PASSWORD=calminer_password
-      - DATABASE_NAME=calminer_db
+      # Environment-specific variables should be set in override files
+      - ENVIRONMENT=${ENVIRONMENT:-production}
+      - DATABASE_HOST=${DATABASE_HOST:-postgres}
+      - DATABASE_PORT=${DATABASE_PORT:-5432}
+      - DATABASE_USER=${DATABASE_USER}
+      - DATABASE_PASSWORD=${DATABASE_PASSWORD}
+      - DATABASE_NAME=${DATABASE_NAME}
       - DATABASE_DRIVER=postgresql
     depends_on:
       - postgres
@@ -23,9 +23,9 @@ services:
   postgres:
     image: postgres:17
     environment:
-      - POSTGRES_USER=calminer
-      - POSTGRES_PASSWORD=calminer_password
-      - POSTGRES_DB=calminer_db
+      - POSTGRES_USER=${DATABASE_USER}
+      - POSTGRES_PASSWORD=${DATABASE_PASSWORD}
+      - POSTGRES_DB=${DATABASE_NAME}
     ports:
       - "5432:5432"
     volumes:

k8s/configmap.yaml

@@ -0,0 +1,14 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: calminer-config
+data:
+  DATABASE_HOST: "calminer-db"
+  DATABASE_PORT: "5432"
+  DATABASE_USER: "calminer"
+  DATABASE_NAME: "calminer_db"
+  DATABASE_DRIVER: "postgresql"
+  CALMINER_EXPORT_MAX_ROWS: "10000"
+  CALMINER_EXPORT_METADATA: "true"
+  CALMINER_IMPORT_STAGING_TTL: "300"
+  CALMINER_IMPORT_MAX_ROWS: "50000"

k8s/deployment.yaml

@@ -0,0 +1,54 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: calminer-app
+  labels:
+    app: calminer
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: calminer
+  template:
+    metadata:
+      labels:
+        app: calminer
+    spec:
+      containers:
+        - name: calminer
+          image: registry.example.com/calminer:latest
+          ports:
+            - containerPort: 8003
+          envFrom:
+            - configMapRef:
+                name: calminer-config
+            - secretRef:
+                name: calminer-secrets
+          resources:
+            requests:
+              memory: "256Mi"
+              cpu: "250m"
+            limits:
+              memory: "512Mi"
+              cpu: "500m"
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: 8003
+            initialDelaySeconds: 30
+            periodSeconds: 10
+          readinessProbe:
+            httpGet:
+              path: /health
+              port: 8003
+            initialDelaySeconds: 5
+            periodSeconds: 5
+      initContainers:
+        - name: wait-for-db
+          image: postgres:17
+          command:
+            [
+              "sh",
+              "-c",
+              "until pg_isready -h calminer-db -p 5432; do echo waiting for database; sleep 2; done;",
+            ]

k8s/ingress.yaml

@@ -0,0 +1,18 @@
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: calminer-ingress
+  annotations:
+    nginx.ingress.kubernetes.io/rewrite-target: /
+spec:
+  rules:
+    - host: calminer.example.com
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: calminer-service
+                port:
+                  number: 80

k8s/postgres-service.yaml

@@ -0,0 +1,13 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: calminer-db
+  labels:
+    app: calminer-db
+spec:
+  selector:
+    app: calminer-db
+  ports:
+    - port: 5432
+      targetPort: 5432
+  clusterIP: None # Headless service for StatefulSet

k8s/postgres.yaml

@@ -0,0 +1,48 @@
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: calminer-db
+spec:
+  serviceName: calminer-db
+  replicas: 1
+  selector:
+    matchLabels:
+      app: calminer-db
+  template:
+    metadata:
+      labels:
+        app: calminer-db
+    spec:
+      containers:
+        - name: postgres
+          image: postgres:17
+          ports:
+            - containerPort: 5432
+          env:
+            - name: POSTGRES_USER
+              value: "calminer"
+            - name: POSTGRES_PASSWORD
+              valueFrom:
+                secretKeyRef:
+                  name: calminer-secrets
+                  key: DATABASE_PASSWORD
+            - name: POSTGRES_DB
+              value: "calminer_db"
+          resources:
+            requests:
+              memory: "256Mi"
+              cpu: "250m"
+            limits:
+              memory: "512Mi"
+              cpu: "500m"
+          volumeMounts:
+            - name: postgres-storage
+              mountPath: /var/lib/postgresql/data
+  volumeClaimTemplates:
+    - metadata:
+        name: postgres-storage
+      spec:
+        accessModes: ["ReadWriteOnce"]
+        resources:
+          requests:
+            storage: 10Gi

k8s/secret.yaml

@@ -0,0 +1,8 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: calminer-secrets
+type: Opaque
+data:
+  DATABASE_PASSWORD: Y2FsbWluZXJfcGFzc3dvcmQ= # base64 encoded 'calminer_password'
+  CALMINER_SEED_ADMIN_PASSWORD: Q2hhbmdlTWUxMjMh # base64 encoded 'ChangeMe123!'

k8s/service.yaml

@@ -0,0 +1,14 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: calminer-service
+  labels:
+    app: calminer
+spec:
+  selector:
+    app: calminer
+  ports:
+    - port: 80
+      targetPort: 8003
+      protocol: TCP
+  type: ClusterIP

main.py

@@ -1,35 +1,90 @@
 import logging
+from contextlib import asynccontextmanager
 from typing import Awaitable, Callable
 
 from fastapi import FastAPI, Request, Response
 from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
 
 from config.settings import get_settings
 from middleware.auth_session import AuthSessionMiddleware
+from middleware.metrics import MetricsMiddleware
 from middleware.validation import validate_json
-from models import (
-    FinancialInput,
-    Project,
-    Scenario,
-    SimulationParameter,
-)
 from routes.auth import router as auth_router
 from routes.dashboard import router as dashboard_router
+from routes.calculations import router as calculations_router
 from routes.imports import router as imports_router
 from routes.exports import router as exports_router
 from routes.projects import router as projects_router
 from routes.reports import router as reports_router
 from routes.scenarios import router as scenarios_router
+from routes.ui import router as ui_router
+from routes.navigation import router as navigation_router
 from monitoring import router as monitoring_router
 from services.bootstrap import bootstrap_admin, bootstrap_pricing_settings
-
-app = FastAPI()
-
-app.add_middleware(AuthSessionMiddleware)
+from scripts.init_db import init_db as init_db_script
 
 logger = logging.getLogger(__name__)
 
 
+async def _bootstrap_startup() -> None:
+    settings = get_settings()
+    admin_settings = settings.admin_bootstrap_settings()
+    pricing_metadata = settings.pricing_metadata()
+    try:
+        try:
+            init_db_script()
+        except Exception:
+            logger.exception(
+                "DB initializer failed; continuing to bootstrap (non-fatal)")
+
+        role_result, admin_result = bootstrap_admin(settings=admin_settings)
+        pricing_result = bootstrap_pricing_settings(metadata=pricing_metadata)
+        logger.info(
+            "Admin bootstrap completed: roles=%s created=%s updated=%s rotated=%s assigned=%s",
+            role_result.ensured,
+            admin_result.created_user,
+            admin_result.updated_user,
+            admin_result.password_rotated,
+            admin_result.roles_granted,
+        )
+        try:
+            seed = pricing_result.seed
+            slug = getattr(seed.settings, "slug", None) if seed and getattr(
+                seed, "settings", None) else None
+            created = getattr(seed, "created", None)
+            updated_fields = getattr(seed, "updated_fields", None)
+            impurity_upserts = getattr(seed, "impurity_upserts", None)
+            logger.info(
+                "Pricing settings bootstrap completed: slug=%s created=%s updated_fields=%s impurity_upserts=%s projects_assigned=%s",
+                slug,
+                created,
+                updated_fields,
+                impurity_upserts,
+                pricing_result.projects_assigned,
+            )
+        except Exception:
+            logger.info(
+                "Pricing settings bootstrap completed (partial): projects_assigned=%s",
+                pricing_result.projects_assigned,
+            )
+    except Exception:  # pragma: no cover - defensive logging
+        logger.exception(
+            "Failed to bootstrap administrator or pricing settings")
+
+
+@asynccontextmanager
+async def app_lifespan(_: FastAPI):
+    await _bootstrap_startup()
+    yield
+
+
+app = FastAPI(lifespan=app_lifespan)
+
+app.add_middleware(AuthSessionMiddleware)
+app.add_middleware(MetricsMiddleware)
+
+
 @app.middleware("http")
 async def json_validation(
     request: Request, call_next: Callable[[Request], Awaitable[Response]]
@@ -42,42 +97,23 @@ async def health() -> dict[str, str]:
     return {"status": "ok"}
 
 
-@app.on_event("startup")
-async def ensure_admin_bootstrap() -> None:
-    settings = get_settings()
-    admin_settings = settings.admin_bootstrap_settings()
-    pricing_metadata = settings.pricing_metadata()
-    try:
-        role_result, admin_result = bootstrap_admin(settings=admin_settings)
-        pricing_result = bootstrap_pricing_settings(metadata=pricing_metadata)
-        logger.info(
-            "Admin bootstrap completed: roles=%s created=%s updated=%s rotated=%s assigned=%s",
-            role_result.ensured,
-            admin_result.created_user,
-            admin_result.updated_user,
-            admin_result.password_rotated,
-            admin_result.roles_granted,
-        )
-        logger.info(
-            "Pricing settings bootstrap completed: slug=%s created=%s updated_fields=%s impurity_upserts=%s projects_assigned=%s",
-            pricing_result.seed.settings.slug,
-            pricing_result.seed.created,
-            pricing_result.seed.updated_fields,
-            pricing_result.seed.impurity_upserts,
-            pricing_result.projects_assigned,
-        )
-    except Exception:  # pragma: no cover - defensive logging
-        logger.exception(
-            "Failed to bootstrap administrator or pricing settings")
+@app.get("/favicon.ico", include_in_schema=False)
+async def favicon() -> Response:
+    static_directory = "static"
+    favicon_img = "favicon.ico"
+    return FileResponse(f"{static_directory}/{favicon_img}")
 
 
 app.include_router(dashboard_router)
+app.include_router(calculations_router)
 app.include_router(auth_router)
 app.include_router(imports_router)
 app.include_router(exports_router)
 app.include_router(projects_router)
 app.include_router(scenarios_router)
 app.include_router(reports_router)
+app.include_router(ui_router)
 app.include_router(monitoring_router)
+app.include_router(navigation_router)
 
 app.mount("/static", StaticFiles(directory="static"), name="static")

middleware/auth_session.py

@@ -8,7 +8,9 @@ from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoin
 from starlette.types import ASGIApp
 
 from config.settings import Settings, get_settings
+from sqlalchemy.orm.exc import DetachedInstanceError
 from models import User
+from monitoring.metrics import ACTIVE_CONNECTIONS
 from services.exceptions import EntityNotFoundError
 from services.security import (
     JWTSettings,
@@ -45,6 +47,8 @@ class _ResolutionResult:
 class AuthSessionMiddleware(BaseHTTPMiddleware):
     """Resolve authenticated users from session cookies and refresh tokens."""
 
+    _active_sessions: int = 0
+
     def __init__(
         self,
         app: ASGIApp,
@@ -61,9 +65,44 @@ class AuthSessionMiddleware(BaseHTTPMiddleware):
 
     async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
         resolved = self._resolve_session(request)
-        response = await call_next(request)
-        self._apply_session(response, resolved)
-        return response
+
+        # Track active sessions for authenticated users
+        try:
+            user_active = bool(resolved.session.user and getattr(
+                resolved.session.user, "is_active", False))
+        except DetachedInstanceError:
+            user_active = False
+
+        if user_active:
+            AuthSessionMiddleware._active_sessions += 1
+            ACTIVE_CONNECTIONS.set(AuthSessionMiddleware._active_sessions)
+
+        response: Response | None = None
+        try:
+            response = await call_next(request)
+            return response
+        finally:
+            # Always decrement the active sessions counter if we incremented it.
+            if user_active:
+                AuthSessionMiddleware._active_sessions = max(
+                    0, AuthSessionMiddleware._active_sessions - 1)
+                ACTIVE_CONNECTIONS.set(AuthSessionMiddleware._active_sessions)
+
+            # Only apply session cookies if a response was produced by downstream
+            # application. If an exception occurred before a response was created
+            # we avoid raising another error here.
+            import logging
+            if response is not None:
+                try:
+                    self._apply_session(response, resolved)
+                except Exception:
+                    logging.getLogger(__name__).exception(
+                        "Failed to apply session cookies to response"
+                    )
+            else:
+                logging.getLogger(__name__).debug(
+                    "AuthSessionMiddleware: no response produced by downstream app (response is None)"
+                )
 
     def _resolve_session(self, request: Request) -> _ResolutionResult:
         settings = self._settings_provider()
@@ -106,6 +145,7 @@ class AuthSessionMiddleware(BaseHTTPMiddleware):
 
         session.user = user
         session.scopes = tuple(payload.scopes)
+        session.set_role_slugs(role.name for role in getattr(user, "roles", []) if role)
         return True
 
     def _try_refresh_token(
@@ -127,6 +167,7 @@ class AuthSessionMiddleware(BaseHTTPMiddleware):
 
         session.user = user
         session.scopes = tuple(payload.scopes)
+        session.set_role_slugs(role.name for role in getattr(user, "roles", []) if role)
 
         access_token = create_access_token(
             str(user.id),

middleware/metrics.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import time
+from typing import Callable
+
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from monitoring.metrics import observe_request
+from services.metrics import get_metrics_service
+
+
+class MetricsMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next: Callable[[Request], Response]) -> Response:
+        start_time = time.time()
+        response = await call_next(request)
+        process_time = time.time() - start_time
+
+        observe_request(
+            method=request.method,
+            endpoint=request.url.path,
+            status=response.status_code,
+            seconds=process_time,
+        )
+
+        # Store in database asynchronously
+        background_tasks = getattr(request.state, "background_tasks", None)
+        if background_tasks:
+            background_tasks.add_task(
+                store_request_metric,
+                method=request.method,
+                endpoint=request.url.path,
+                status_code=response.status_code,
+                duration_seconds=process_time,
+            )
+
+        return response
+
+
+async def store_request_metric(
+    method: str, endpoint: str, status_code: int, duration_seconds: float
+) -> None:
+    """Store request metric in database."""
+    try:
+        service = get_metrics_service()
+        service.store_metric(
+            metric_name="http_request",
+            value=duration_seconds,
+            labels={"method": method, "endpoint": endpoint,
+                    "status": status_code},
+            endpoint=endpoint,
+            method=method,
+            status_code=status_code,
+            duration_seconds=duration_seconds,
+        )
+    except Exception:
+        # Log error but don't fail the request
+        pass

middleware/validation.py

@@ -10,10 +10,14 @@ async def validate_json(
 ) -> Response:
     # Only validate JSON for requests with a body
     if request.method in ("POST", "PUT", "PATCH"):
-        try:
-            # attempt to parse json body
-            await request.json()
-        except Exception:
-            raise HTTPException(status_code=400, detail="Invalid JSON payload")
+        # Only attempt JSON parsing when the client indicates a JSON content type.
+        content_type = (request.headers.get("content-type") or "").lower()
+        if "json" in content_type:
+            try:
+                # attempt to parse json body
+                await request.json()
+            except Exception:
+                raise HTTPException(
+                    status_code=400, detail="Invalid JSON payload")
     response = await call_next(request)
     return response

models/__init__.py

@@ -1,35 +1,56 @@
 """Database models and shared metadata for the CalMiner domain."""
 
-from .financial_input import FinancialCategory, FinancialInput
+from .financial_input import FinancialInput
 from .metadata import (
     COST_BUCKET_METADATA,
     RESOURCE_METADATA,
     STOCHASTIC_VARIABLE_METADATA,
-    CostBucket,
     ResourceDescriptor,
-    ResourceType,
-    StochasticVariable,
     StochasticVariableDescriptor,
 )
+from .performance_metric import PerformanceMetric
 from .pricing_settings import (
     PricingImpuritySettings,
     PricingMetalSettings,
     PricingSettings,
 )
-from .project import MiningOperationType, Project
-from .scenario import Scenario, ScenarioStatus
-from .simulation_parameter import DistributionType, SimulationParameter
+from .enums import (
+    CostBucket,
+    DistributionType,
+    FinancialCategory,
+    MiningOperationType,
+    ResourceType,
+    ScenarioStatus,
+    StochasticVariable,
+)
+from .project import Project
+from .scenario import Scenario
+from .simulation_parameter import SimulationParameter
 from .user import Role, User, UserRole, password_context
+from .navigation import NavigationGroup, NavigationLink
+
+from .profitability_snapshot import ProjectProfitability, ScenarioProfitability
+from .capex_snapshot import ProjectCapexSnapshot, ScenarioCapexSnapshot
+from .opex_snapshot import (
+    ProjectOpexSnapshot,
+    ScenarioOpexSnapshot,
+)
 
 __all__ = [
     "FinancialCategory",
     "FinancialInput",
     "MiningOperationType",
     "Project",
+    "ProjectProfitability",
+    "ProjectCapexSnapshot",
+    "ProjectOpexSnapshot",
     "PricingSettings",
     "PricingMetalSettings",
     "PricingImpuritySettings",
     "Scenario",
+    "ScenarioProfitability",
+    "ScenarioCapexSnapshot",
+    "ScenarioOpexSnapshot",
     "ScenarioStatus",
     "DistributionType",
     "SimulationParameter",
@@ -45,4 +66,7 @@ __all__ = [
     "Role",
     "UserRole",
     "password_context",
+    "PerformanceMetric",
+    "NavigationGroup",
+    "NavigationLink",
 ]

models/capex_snapshot.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from sqlalchemy import JSON, DateTime, ForeignKey, Integer, Numeric, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.sql import func
+
+from config.database import Base
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .project import Project
+    from .scenario import Scenario
+    from .user import User
+
+
+class ProjectCapexSnapshot(Base):
+    """Snapshot of aggregated capex metrics at the project level."""
+
+    __tablename__ = "project_capex_snapshots"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    project_id: Mapped[int] = mapped_column(
+        ForeignKey("projects.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    created_by_id: Mapped[int | None] = mapped_column(
+        ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+    calculation_source: Mapped[str | None] = mapped_column(
+        String(64), nullable=True)
+    calculated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    currency_code: Mapped[str | None] = mapped_column(String(3), nullable=True)
+    total_capex: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True)
+    contingency_pct: Mapped[float | None] = mapped_column(
+        Numeric(12, 6), nullable=True)
+    contingency_amount: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True)
+    total_with_contingency: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True)
+    component_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    payload: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
+    )
+
+    project: Mapped[Project] = relationship(
+        "Project", back_populates="capex_snapshots"
+    )
+    created_by: Mapped[User | None] = relationship("User")
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            "ProjectCapexSnapshot(id={id!r}, project_id={project_id!r}, total_capex={total_capex!r})".format(
+                id=self.id, project_id=self.project_id, total_capex=self.total_capex
+            )
+        )
+
+
+class ScenarioCapexSnapshot(Base):
+    """Snapshot of capex metrics for an individual scenario."""
+
+    __tablename__ = "scenario_capex_snapshots"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    scenario_id: Mapped[int] = mapped_column(
+        ForeignKey("scenarios.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    created_by_id: Mapped[int | None] = mapped_column(
+        ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+    calculation_source: Mapped[str | None] = mapped_column(
+        String(64), nullable=True)
+    calculated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    currency_code: Mapped[str | None] = mapped_column(String(3), nullable=True)
+    total_capex: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True)
+    contingency_pct: Mapped[float | None] = mapped_column(
+        Numeric(12, 6), nullable=True)
+    contingency_amount: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True)
+    total_with_contingency: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True)
+    component_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    payload: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
+    )
+
+    scenario: Mapped[Scenario] = relationship(
+        "Scenario", back_populates="capex_snapshots"
+    )
+    created_by: Mapped[User | None] = relationship("User")
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            "ScenarioCapexSnapshot(id={id!r}, scenario_id={scenario_id!r}, total_capex={total_capex!r})".format(
+                id=self.id, scenario_id=self.scenario_id, total_capex=self.total_capex
+            )
+        )

models/enums.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Type
+
+from sqlalchemy import Enum as SQLEnum
+
+
+def sql_enum(enum_cls: Type[Enum], *, name: str) -> SQLEnum:
+    """Build a SQLAlchemy Enum that maps using the enum member values."""
+
+    return SQLEnum(
+        enum_cls,
+        name=name,
+        create_type=False,
+        validate_strings=True,
+        values_callable=lambda enum_cls: [member.value for member in enum_cls],
+    )
+
+
+class MiningOperationType(str, Enum):
+    """Supported mining operation categories."""
+
+    OPEN_PIT = "open_pit"
+    UNDERGROUND = "underground"
+    IN_SITU_LEACH = "in_situ_leach"
+    PLACER = "placer"
+    QUARRY = "quarry"
+    MOUNTAINTOP_REMOVAL = "mountaintop_removal"
+    OTHER = "other"
+
+
+class ScenarioStatus(str, Enum):
+    """Lifecycle states for project scenarios."""
+
+    DRAFT = "draft"
+    ACTIVE = "active"
+    ARCHIVED = "archived"
+
+
+class FinancialCategory(str, Enum):
+    """Enumeration of cost and revenue classifications."""
+
+    CAPITAL_EXPENDITURE = "capex"
+    OPERATING_EXPENDITURE = "opex"
+    REVENUE = "revenue"
+    CONTINGENCY = "contingency"
+    OTHER = "other"
+
+
+class DistributionType(str, Enum):
+    """Supported stochastic distribution families for simulations."""
+
+    NORMAL = "normal"
+    TRIANGULAR = "triangular"
+    UNIFORM = "uniform"
+    LOGNORMAL = "lognormal"
+    CUSTOM = "custom"
+
+
+class ResourceType(str, Enum):
+    """Primary consumables and resources used in mining operations."""
+
+    DIESEL = "diesel"
+    ELECTRICITY = "electricity"
+    WATER = "water"
+    EXPLOSIVES = "explosives"
+    REAGENTS = "reagents"
+    LABOR = "labor"
+    EQUIPMENT_HOURS = "equipment_hours"
+    TAILINGS_CAPACITY = "tailings_capacity"
+
+
+class CostBucket(str, Enum):
+    """Granular cost buckets aligned with project accounting."""
+
+    CAPITAL_INITIAL = "capital_initial"
+    CAPITAL_SUSTAINING = "capital_sustaining"
+    OPERATING_FIXED = "operating_fixed"
+    OPERATING_VARIABLE = "operating_variable"
+    MAINTENANCE = "maintenance"
+    RECLAMATION = "reclamation"
+    ROYALTIES = "royalties"
+    GENERAL_ADMIN = "general_admin"
+
+
+class StochasticVariable(str, Enum):
+    """Domain variables that typically require probabilistic modelling."""
+
+    ORE_GRADE = "ore_grade"
+    RECOVERY_RATE = "recovery_rate"
+    METAL_PRICE = "metal_price"
+    OPERATING_COST = "operating_cost"
+    CAPITAL_COST = "capital_cost"
+    DISCOUNT_RATE = "discount_rate"
+    THROUGHPUT = "throughput"

models/financial_input.py

@@ -1,13 +1,11 @@
 from __future__ import annotations
 
 from datetime import date, datetime
-from enum import Enum
 from typing import TYPE_CHECKING
 
 from sqlalchemy import (
     Date,
     DateTime,
-    Enum as SQLEnum,
     ForeignKey,
     Integer,
     Numeric,
@@ -16,37 +14,16 @@ from sqlalchemy import (
 )
 from sqlalchemy.orm import Mapped, mapped_column, relationship, validates
 
-from sqlalchemy import (
-    Date,
-    DateTime,
-    Enum as SQLEnum,
-    ForeignKey,
-    Integer,
-    Numeric,
-    String,
-    Text,
-)
-from sqlalchemy.orm import Mapped, mapped_column, relationship
 from sqlalchemy.sql import func
 
 from config.database import Base
-from .metadata import CostBucket
+from .enums import CostBucket, FinancialCategory, sql_enum
 from services.currency import normalise_currency
 
 if TYPE_CHECKING:  # pragma: no cover
     from .scenario import Scenario
 
 
-class FinancialCategory(str, Enum):
-    """Enumeration of cost and revenue classifications."""
-
-    CAPITAL_EXPENDITURE = "capex"
-    OPERATING_EXPENDITURE = "opex"
-    REVENUE = "revenue"
-    CONTINGENCY = "contingency"
-    OTHER = "other"
-
-
 class FinancialInput(Base):
     """Line-item financial assumption attached to a scenario."""
 
@@ -58,10 +35,10 @@ class FinancialInput(Base):
     )
     name: Mapped[str] = mapped_column(String(255), nullable=False)
     category: Mapped[FinancialCategory] = mapped_column(
-        SQLEnum(FinancialCategory), nullable=False
+        sql_enum(FinancialCategory, name="financialcategory"), nullable=False
     )
     cost_bucket: Mapped[CostBucket | None] = mapped_column(
-        SQLEnum(CostBucket), nullable=True
+        sql_enum(CostBucket, name="costbucket"), nullable=True
     )
     amount: Mapped[float] = mapped_column(Numeric(18, 2), nullable=False)
     currency: Mapped[str | None] = mapped_column(String(3), nullable=True)

models/import_export_log.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-from datetime import datetime
 
 from sqlalchemy import Column, DateTime, ForeignKey, Integer, String, Text
 from sqlalchemy.sql import func

models/metadata.py

@@ -1,45 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from enum import Enum
-
-
-class ResourceType(str, Enum):
-    """Primary consumables and resources used in mining operations."""
-
-    DIESEL = "diesel"
-    ELECTRICITY = "electricity"
-    WATER = "water"
-    EXPLOSIVES = "explosives"
-    REAGENTS = "reagents"
-    LABOR = "labor"
-    EQUIPMENT_HOURS = "equipment_hours"
-    TAILINGS_CAPACITY = "tailings_capacity"
-
-
-class CostBucket(str, Enum):
-    """Granular cost buckets aligned with project accounting."""
-
-    CAPITAL_INITIAL = "capital_initial"
-    CAPITAL_SUSTAINING = "capital_sustaining"
-    OPERATING_FIXED = "operating_fixed"
-    OPERATING_VARIABLE = "operating_variable"
-    MAINTENANCE = "maintenance"
-    RECLAMATION = "reclamation"
-    ROYALTIES = "royalties"
-    GENERAL_ADMIN = "general_admin"
-
-
-class StochasticVariable(str, Enum):
-    """Domain variables that typically require probabilistic modelling."""
-
-    ORE_GRADE = "ore_grade"
-    RECOVERY_RATE = "recovery_rate"
-    METAL_PRICE = "metal_price"
-    OPERATING_COST = "operating_cost"
-    CAPITAL_COST = "capital_cost"
-    DISCOUNT_RATE = "discount_rate"
-    THROUGHPUT = "throughput"
+from .enums import ResourceType, CostBucket, StochasticVariable
 
 
 @dataclass(frozen=True)

models/navigation.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import List, Optional
+
+from sqlalchemy import (
+    Boolean,
+    CheckConstraint,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    UniqueConstraint,
+)
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.sql import func
+from sqlalchemy.ext.mutable import MutableList
+from sqlalchemy import JSON
+
+from config.database import Base
+
+
+class NavigationGroup(Base):
+    __tablename__ = "navigation_groups"
+    __table_args__ = (
+        UniqueConstraint("slug", name="uq_navigation_groups_slug"),
+        Index("ix_navigation_groups_sort_order", "sort_order"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    slug: Mapped[str] = mapped_column(String(64), nullable=False)
+    label: Mapped[str] = mapped_column(String(128), nullable=False)
+    sort_order: Mapped[int] = mapped_column(
+        Integer, nullable=False, default=100)
+    icon: Mapped[Optional[str]] = mapped_column(String(64))
+    tooltip: Mapped[Optional[str]] = mapped_column(String(255))
+    is_enabled: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
+    )
+
+    links: Mapped[List["NavigationLink"]] = relationship(
+        "NavigationLink",
+        back_populates="group",
+        cascade="all, delete-orphan",
+        order_by="NavigationLink.sort_order",
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"NavigationGroup(id={self.id!r}, slug={self.slug!r})"
+
+
+class NavigationLink(Base):
+    __tablename__ = "navigation_links"
+    __table_args__ = (
+        UniqueConstraint("group_id", "slug",
+                         name="uq_navigation_links_group_slug"),
+        Index("ix_navigation_links_group_sort", "group_id", "sort_order"),
+        Index("ix_navigation_links_parent_sort",
+              "parent_link_id", "sort_order"),
+        CheckConstraint(
+            "(route_name IS NOT NULL) OR (href_override IS NOT NULL)",
+            name="ck_navigation_links_route_or_href",
+        ),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    group_id: Mapped[int] = mapped_column(
+        ForeignKey("navigation_groups.id", ondelete="CASCADE"), nullable=False
+    )
+    parent_link_id: Mapped[Optional[int]] = mapped_column(
+        ForeignKey("navigation_links.id", ondelete="CASCADE")
+    )
+    slug: Mapped[str] = mapped_column(String(64), nullable=False)
+    label: Mapped[str] = mapped_column(String(128), nullable=False)
+    route_name: Mapped[Optional[str]] = mapped_column(String(128))
+    href_override: Mapped[Optional[str]] = mapped_column(String(512))
+    match_prefix: Mapped[Optional[str]] = mapped_column(String(512))
+    sort_order: Mapped[int] = mapped_column(
+        Integer, nullable=False, default=100)
+    icon: Mapped[Optional[str]] = mapped_column(String(64))
+    tooltip: Mapped[Optional[str]] = mapped_column(String(255))
+    required_roles: Mapped[list[str]] = mapped_column(
+        MutableList.as_mutable(JSON), nullable=False, default=list
+    )
+    is_enabled: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=True)
+    is_external: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
+    )
+
+    group: Mapped[NavigationGroup] = relationship(
+        NavigationGroup,
+        back_populates="links",
+    )
+    parent: Mapped[Optional["NavigationLink"]] = relationship(
+        "NavigationLink",
+        remote_side="NavigationLink.id",
+        back_populates="children",
+    )
+    children: Mapped[List["NavigationLink"]] = relationship(
+        "NavigationLink",
+        back_populates="parent",
+        cascade="all, delete-orphan",
+        order_by="NavigationLink.sort_order",
+    )
+
+    def is_visible_for_roles(self, roles: list[str]) -> bool:
+        if not self.required_roles:
+            return True
+        role_set = set(roles)
+        return any(role in role_set for role in self.required_roles)
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"NavigationLink(id={self.id!r}, slug={self.slug!r})"

models/opex_snapshot.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from sqlalchemy import JSON, Boolean, DateTime, ForeignKey, Integer, Numeric, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.sql import func
+
+from config.database import Base
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .project import Project
+    from .scenario import Scenario
+    from .user import User
+
+
+class ProjectOpexSnapshot(Base):
+    """Snapshot of recurring opex metrics at the project level."""
+
+    __tablename__ = "project_opex_snapshots"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    project_id: Mapped[int] = mapped_column(
+        ForeignKey("projects.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    created_by_id: Mapped[int | None] = mapped_column(
+        ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+    calculation_source: Mapped[str | None] = mapped_column(
+        String(64), nullable=True)
+    calculated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    currency_code: Mapped[str | None] = mapped_column(String(3), nullable=True)
+    overall_annual: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True)
+    escalated_total: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True)
+    annual_average: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True)
+    evaluation_horizon_years: Mapped[int | None] = mapped_column(
+        Integer, nullable=True)
+    escalation_pct: Mapped[float | None] = mapped_column(
+        Numeric(12, 6), nullable=True)
+    apply_escalation: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=True)
+    component_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    payload: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
+    )
+
+    project: Mapped[Project] = relationship(
+        "Project", back_populates="opex_snapshots"
+    )
+    created_by: Mapped[User | None] = relationship("User")
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            "ProjectOpexSnapshot(id={id!r}, project_id={project_id!r}, overall_annual={overall_annual!r})".format(
+                id=self.id,
+                project_id=self.project_id,
+                overall_annual=self.overall_annual,
+            )
+        )
+
+
+class ScenarioOpexSnapshot(Base):
+    """Snapshot of opex metrics for an individual scenario."""
+
+    __tablename__ = "scenario_opex_snapshots"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    scenario_id: Mapped[int] = mapped_column(
+        ForeignKey("scenarios.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    created_by_id: Mapped[int | None] = mapped_column(
+        ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+    calculation_source: Mapped[str | None] = mapped_column(
+        String(64), nullable=True)
+    calculated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    currency_code: Mapped[str | None] = mapped_column(String(3), nullable=True)
+    overall_annual: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True)
+    escalated_total: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True)
+    annual_average: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True)
+    evaluation_horizon_years: Mapped[int | None] = mapped_column(
+        Integer, nullable=True)
+    escalation_pct: Mapped[float | None] = mapped_column(
+        Numeric(12, 6), nullable=True)
+    apply_escalation: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=True)
+    component_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    payload: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
+    )
+
+    scenario: Mapped[Scenario] = relationship(
+        "Scenario", back_populates="opex_snapshots"
+    )
+    created_by: Mapped[User | None] = relationship("User")
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            "ScenarioOpexSnapshot(id={id!r}, scenario_id={scenario_id!r}, overall_annual={overall_annual!r})".format(
+                id=self.id,
+                scenario_id=self.scenario_id,
+                overall_annual=self.overall_annual,
+            )
+        )

models/performance_metric.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import Column, DateTime, Float, Integer, String
+
+from config.database import Base
+
+
+class PerformanceMetric(Base):
+    __tablename__ = "performance_metrics"
+
+    id = Column(Integer, primary_key=True, index=True)
+    timestamp = Column(DateTime, default=datetime.utcnow, index=True)
+    metric_name = Column(String, index=True)
+    value = Column(Float)
+    labels = Column(String)  # JSON string of labels
+    endpoint = Column(String, index=True, nullable=True)
+    method = Column(String, nullable=True)
+    status_code = Column(Integer, nullable=True)
+    duration_seconds = Column(Float, nullable=True)
+
+    def __repr__(self) -> str:
+        return f"<PerformanceMetric(id={self.id}, name={self.metric_name}, value={self.value})>"

models/pricing_settings.py

@@ -1,7 +1,7 @@
-from __future__ import annotations
-
 """Database models for persisted pricing configuration settings."""
 
+from __future__ import annotations
+
 from datetime import datetime
 from typing import TYPE_CHECKING
 

models/profitability_snapshot.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from sqlalchemy import JSON, DateTime, ForeignKey, Integer, Numeric, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.sql import func
+
+from config.database import Base
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .project import Project
+    from .scenario import Scenario
+    from .user import User
+
+
+class ProjectProfitability(Base):
+    """Snapshot of aggregated profitability metrics at the project level."""
+
+    __tablename__ = "project_profitability_snapshots"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    project_id: Mapped[int] = mapped_column(
+        ForeignKey("projects.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    created_by_id: Mapped[int | None] = mapped_column(
+        ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+    calculation_source: Mapped[str | None] = mapped_column(
+        String(64), nullable=True)
+    calculated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    currency_code: Mapped[str | None] = mapped_column(String(3), nullable=True)
+    npv: Mapped[float | None] = mapped_column(Numeric(18, 2), nullable=True)
+    irr_pct: Mapped[float | None] = mapped_column(
+        Numeric(12, 6), nullable=True)
+    payback_period_years: Mapped[float | None] = mapped_column(
+        Numeric(12, 4), nullable=True
+    )
+    margin_pct: Mapped[float | None] = mapped_column(
+        Numeric(12, 6), nullable=True)
+    revenue_total: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True)
+    opex_total: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True
+    )
+    sustaining_capex_total: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True
+    )
+    capex: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True)
+    net_cash_flow_total: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True
+    )
+    payload: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
+    )
+
+    project: Mapped[Project] = relationship(
+        "Project", back_populates="profitability_snapshots")
+    created_by: Mapped[User | None] = relationship("User")
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            "ProjectProfitability(id={id!r}, project_id={project_id!r}, npv={npv!r})".format(
+                id=self.id, project_id=self.project_id, npv=self.npv
+            )
+        )
+
+
+class ScenarioProfitability(Base):
+    """Snapshot of profitability metrics for an individual scenario."""
+
+    __tablename__ = "scenario_profitability_snapshots"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    scenario_id: Mapped[int] = mapped_column(
+        ForeignKey("scenarios.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    created_by_id: Mapped[int | None] = mapped_column(
+        ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+    calculation_source: Mapped[str | None] = mapped_column(
+        String(64), nullable=True)
+    calculated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    currency_code: Mapped[str | None] = mapped_column(String(3), nullable=True)
+    npv: Mapped[float | None] = mapped_column(Numeric(18, 2), nullable=True)
+    irr_pct: Mapped[float | None] = mapped_column(
+        Numeric(12, 6), nullable=True)
+    payback_period_years: Mapped[float | None] = mapped_column(
+        Numeric(12, 4), nullable=True
+    )
+    margin_pct: Mapped[float | None] = mapped_column(
+        Numeric(12, 6), nullable=True)
+    revenue_total: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True)
+    opex_total: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True
+    )
+    sustaining_capex_total: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True
+    )
+    capex: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True)
+    net_cash_flow_total: Mapped[float | None] = mapped_column(
+        Numeric(18, 2), nullable=True
+    )
+    payload: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
+    )
+
+    scenario: Mapped[Scenario] = relationship(
+        "Scenario", back_populates="profitability_snapshots")
+    created_by: Mapped[User | None] = relationship("User")
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            "ScenarioProfitability(id={id!r}, scenario_id={scenario_id!r}, npv={npv!r})".format(
+                id=self.id, scenario_id=self.scenario_id, npv=self.npv
+            )
+        )

models/project.py

@@ -1,10 +1,14 @@
 from __future__ import annotations
 
 from datetime import datetime
-from enum import Enum
 from typing import TYPE_CHECKING, List
 
-from sqlalchemy import DateTime, Enum as SQLEnum, ForeignKey, Integer, String, Text
+from .enums import MiningOperationType, sql_enum
+from .profitability_snapshot import ProjectProfitability
+from .capex_snapshot import ProjectCapexSnapshot
+from .opex_snapshot import ProjectOpexSnapshot
+
+from sqlalchemy import DateTime, ForeignKey, Integer, String, Text
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 from sqlalchemy.sql import func
 
@@ -15,18 +19,6 @@ if TYPE_CHECKING:  # pragma: no cover
     from .pricing_settings import PricingSettings
 
 
-class MiningOperationType(str, Enum):
-    """Supported mining operation categories."""
-
-    OPEN_PIT = "open_pit"
-    UNDERGROUND = "underground"
-    IN_SITU_LEACH = "in_situ_leach"
-    PLACER = "placer"
-    QUARRY = "quarry"
-    MOUNTAINTOP_REMOVAL = "mountaintop_removal"
-    OTHER = "other"
-
-
 class Project(Base):
     """Top-level mining project grouping multiple scenarios."""
 
@@ -36,7 +28,9 @@ class Project(Base):
     name: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
     location: Mapped[str | None] = mapped_column(String(255), nullable=True)
     operation_type: Mapped[MiningOperationType] = mapped_column(
-        SQLEnum(MiningOperationType), nullable=False, default=MiningOperationType.OTHER
+        sql_enum(MiningOperationType, name="miningoperationtype"),
+        nullable=False,
+        default=MiningOperationType.OTHER,
     )
     description: Mapped[str | None] = mapped_column(Text, nullable=True)
     pricing_settings_id: Mapped[int | None] = mapped_column(
@@ -60,6 +54,51 @@ class Project(Base):
         "PricingSettings",
         back_populates="projects",
     )
+    profitability_snapshots: Mapped[List["ProjectProfitability"]] = relationship(
+        "ProjectProfitability",
+        back_populates="project",
+        cascade="all, delete-orphan",
+        order_by=lambda: ProjectProfitability.calculated_at.desc(),
+        passive_deletes=True,
+    )
+    capex_snapshots: Mapped[List["ProjectCapexSnapshot"]] = relationship(
+        "ProjectCapexSnapshot",
+        back_populates="project",
+        cascade="all, delete-orphan",
+        order_by=lambda: ProjectCapexSnapshot.calculated_at.desc(),
+        passive_deletes=True,
+    )
+    opex_snapshots: Mapped[List["ProjectOpexSnapshot"]] = relationship(
+        "ProjectOpexSnapshot",
+        back_populates="project",
+        cascade="all, delete-orphan",
+        order_by=lambda: ProjectOpexSnapshot.calculated_at.desc(),
+        passive_deletes=True,
+    )
+
+    @property
+    def latest_profitability(self) -> "ProjectProfitability | None":
+        """Return the most recent profitability snapshot, if any."""
+
+        if not self.profitability_snapshots:
+            return None
+        return self.profitability_snapshots[0]
+
+    @property
+    def latest_capex(self) -> "ProjectCapexSnapshot | None":
+        """Return the most recent capex snapshot, if any."""
+
+        if not self.capex_snapshots:
+            return None
+        return self.capex_snapshots[0]
+
+    @property
+    def latest_opex(self) -> "ProjectOpexSnapshot | None":
+        """Return the most recent opex snapshot, if any."""
+
+        if not self.opex_snapshots:
+            return None
+        return self.opex_snapshots[0]
 
     def __repr__(self) -> str:  # pragma: no cover - helpful for debugging
         return f"Project(id={self.id!r}, name={self.name!r})"

models/scenario.py

@@ -1,25 +1,27 @@
 from __future__ import annotations
 
 from datetime import date, datetime
-from enum import Enum
 from typing import TYPE_CHECKING, List
 
 from sqlalchemy import (
     Date,
     DateTime,
-    Enum as SQLEnum,
     ForeignKey,
     Integer,
     Numeric,
     String,
     Text,
+    UniqueConstraint,
 )
 from sqlalchemy.orm import Mapped, mapped_column, relationship, validates
 from sqlalchemy.sql import func
 
 from config.database import Base
 from services.currency import normalise_currency
-from .metadata import ResourceType
+from .enums import ResourceType, ScenarioStatus, sql_enum
+from .profitability_snapshot import ScenarioProfitability
+from .capex_snapshot import ScenarioCapexSnapshot
+from .opex_snapshot import ScenarioOpexSnapshot
 
 if TYPE_CHECKING:  # pragma: no cover
     from .financial_input import FinancialInput
@@ -27,18 +29,14 @@ if TYPE_CHECKING:  # pragma: no cover
     from .simulation_parameter import SimulationParameter
 
 
-class ScenarioStatus(str, Enum):
-    """Lifecycle states for project scenarios."""
-
-    DRAFT = "draft"
-    ACTIVE = "active"
-    ARCHIVED = "archived"
-
-
 class Scenario(Base):
     """A specific configuration of assumptions for a project."""
 
     __tablename__ = "scenarios"
+    __table_args__ = (
+        UniqueConstraint("project_id", "name",
+                         name="uq_scenarios_project_name"),
+    )
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
     project_id: Mapped[int] = mapped_column(
@@ -47,7 +45,9 @@ class Scenario(Base):
     name: Mapped[str] = mapped_column(String(255), nullable=False)
     description: Mapped[str | None] = mapped_column(Text, nullable=True)
     status: Mapped[ScenarioStatus] = mapped_column(
-        SQLEnum(ScenarioStatus), nullable=False, default=ScenarioStatus.DRAFT
+        sql_enum(ScenarioStatus, name="scenariostatus"),
+        nullable=False,
+        default=ScenarioStatus.DRAFT,
     )
     start_date: Mapped[date | None] = mapped_column(Date, nullable=True)
     end_date: Mapped[date | None] = mapped_column(Date, nullable=True)
@@ -55,7 +55,7 @@ class Scenario(Base):
         Numeric(5, 2), nullable=True)
     currency: Mapped[str | None] = mapped_column(String(3), nullable=True)
     primary_resource: Mapped[ResourceType | None] = mapped_column(
-        SQLEnum(ResourceType), nullable=True
+        sql_enum(ResourceType, name="resourcetype"), nullable=True
     )
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), nullable=False, server_default=func.now()
@@ -78,6 +78,27 @@ class Scenario(Base):
         cascade="all, delete-orphan",
         passive_deletes=True,
     )
+    profitability_snapshots: Mapped[List["ScenarioProfitability"]] = relationship(
+        "ScenarioProfitability",
+        back_populates="scenario",
+        cascade="all, delete-orphan",
+        order_by=lambda: ScenarioProfitability.calculated_at.desc(),
+        passive_deletes=True,
+    )
+    capex_snapshots: Mapped[List["ScenarioCapexSnapshot"]] = relationship(
+        "ScenarioCapexSnapshot",
+        back_populates="scenario",
+        cascade="all, delete-orphan",
+        order_by=lambda: ScenarioCapexSnapshot.calculated_at.desc(),
+        passive_deletes=True,
+    )
+    opex_snapshots: Mapped[List["ScenarioOpexSnapshot"]] = relationship(
+        "ScenarioOpexSnapshot",
+        back_populates="scenario",
+        cascade="all, delete-orphan",
+        order_by=lambda: ScenarioOpexSnapshot.calculated_at.desc(),
+        passive_deletes=True,
+    )
 
     @validates("currency")
     def _normalise_currency(self, key: str, value: str | None) -> str | None:
@@ -86,3 +107,27 @@ class Scenario(Base):
 
     def __repr__(self) -> str:  # pragma: no cover
         return f"Scenario(id={self.id!r}, name={self.name!r}, project_id={self.project_id!r})"
+
+    @property
+    def latest_profitability(self) -> "ScenarioProfitability | None":
+        """Return the most recent profitability snapshot for this scenario."""
+
+        if not self.profitability_snapshots:
+            return None
+        return self.profitability_snapshots[0]
+
+    @property
+    def latest_capex(self) -> "ScenarioCapexSnapshot | None":
+        """Return the most recent capex snapshot for this scenario."""
+
+        if not self.capex_snapshots:
+            return None
+        return self.capex_snapshots[0]
+
+    @property
+    def latest_opex(self) -> "ScenarioOpexSnapshot | None":
+        """Return the most recent opex snapshot for this scenario."""
+
+        if not self.opex_snapshots:
+            return None
+        return self.opex_snapshots[0]

models/simulation_parameter.py

@@ -1,13 +1,13 @@
 from __future__ import annotations
 
 from datetime import datetime
-from enum import Enum
 from typing import TYPE_CHECKING
 
+from .enums import DistributionType, ResourceType, StochasticVariable, sql_enum
+
 from sqlalchemy import (
     JSON,
     DateTime,
-    Enum as SQLEnum,
     ForeignKey,
     Integer,
     Numeric,
@@ -17,22 +17,11 @@ from sqlalchemy.orm import Mapped, mapped_column, relationship
 from sqlalchemy.sql import func
 
 from config.database import Base
-from .metadata import ResourceType, StochasticVariable
 
 if TYPE_CHECKING:  # pragma: no cover
     from .scenario import Scenario
 
 
-class DistributionType(str, Enum):
-    """Supported stochastic distribution families for simulations."""
-
-    NORMAL = "normal"
-    TRIANGULAR = "triangular"
-    UNIFORM = "uniform"
-    LOGNORMAL = "lognormal"
-    CUSTOM = "custom"
-
-
 class SimulationParameter(Base):
     """Probability distribution settings for scenario simulations."""
 
@@ -44,13 +33,13 @@ class SimulationParameter(Base):
     )
     name: Mapped[str] = mapped_column(String(255), nullable=False)
     distribution: Mapped[DistributionType] = mapped_column(
-        SQLEnum(DistributionType), nullable=False
+        sql_enum(DistributionType, name="distributiontype"), nullable=False
     )
     variable: Mapped[StochasticVariable | None] = mapped_column(
-        SQLEnum(StochasticVariable), nullable=True
+        sql_enum(StochasticVariable, name="stochasticvariable"), nullable=True
     )
     resource_type: Mapped[ResourceType | None] = mapped_column(
-        SQLEnum(ResourceType), nullable=True
+        sql_enum(ResourceType, name="resourcetype"), nullable=True
     )
     mean_value: Mapped[float | None] = mapped_column(
         Numeric(18, 4), nullable=True)

monitoring/__init__.py

@@ -1,7 +1,14 @@
 from __future__ import annotations
 
-from fastapi import APIRouter, Response
+from datetime import datetime, timedelta
+from typing import Optional
+
+from fastapi import APIRouter, Depends, Query, Response
 from prometheus_client import CONTENT_TYPE_LATEST, generate_latest
+from sqlalchemy.orm import Session
+
+from config.database import get_db
+from services.metrics import MetricsService
 
 
 router = APIRouter(prefix="/metrics", tags=["monitoring"])
@@ -11,3 +18,100 @@ router = APIRouter(prefix="/metrics", tags=["monitoring"])
 async def metrics_endpoint() -> Response:
     payload = generate_latest()
     return Response(content=payload, media_type=CONTENT_TYPE_LATEST)
+
+
+@router.get("/performance", summary="Get performance metrics")
+async def get_performance_metrics(
+    metric_name: Optional[str] = Query(
+        None, description="Filter by metric name"),
+    hours: int = Query(24, description="Hours back to look"),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Get aggregated performance metrics."""
+    service = MetricsService(db)
+    start_time = datetime.utcnow() - timedelta(hours=hours)
+
+    if metric_name:
+        metrics = service.get_metrics(
+            metric_name=metric_name, start_time=start_time)
+        aggregated = service.get_aggregated_metrics(
+            metric_name, start_time=start_time)
+        return {
+            "metric_name": metric_name,
+            "period_hours": hours,
+            "aggregated": aggregated,
+            "recent_samples": [
+                {
+                    "timestamp": m.timestamp.isoformat(),
+                    "value": m.value,
+                    "labels": m.labels,
+                    "endpoint": m.endpoint,
+                    "method": m.method,
+                    "status_code": m.status_code,
+                    "duration_seconds": m.duration_seconds,
+                }
+                for m in metrics[:50]  # Last 50 samples
+            ],
+        }
+
+    # Return summary for all metrics
+    all_metrics = service.get_metrics(start_time=start_time, limit=1000)
+    metric_types = {}
+    for m in all_metrics:
+        if m.metric_name not in metric_types:
+            metric_types[m.metric_name] = []
+        metric_types[m.metric_name].append(m.value)
+
+    summary = {}
+    for name, values in metric_types.items():
+        summary[name] = {
+            "count": len(values),
+            "avg": sum(values) / len(values) if values else 0,
+            "min": min(values) if values else 0,
+            "max": max(values) if values else 0,
+        }
+
+    return {
+        "period_hours": hours,
+        "summary": summary,
+    }
+
+
+@router.get("/health", summary="Detailed health check with metrics")
+async def detailed_health(db: Session = Depends(get_db)) -> dict:
+    """Get detailed health status with recent metrics."""
+    service = MetricsService(db)
+    last_hour = datetime.utcnow() - timedelta(hours=1)
+
+    # Get request metrics from last hour
+    request_metrics = service.get_metrics(
+        metric_name="http_request", start_time=last_hour
+    )
+
+    if request_metrics:
+        durations = []
+        error_count = 0
+        for m in request_metrics:
+            if m.duration_seconds is not None:
+                durations.append(m.duration_seconds)
+            if m.status_code is not None:
+                if m.status_code >= 400:
+                    error_count += 1
+        total_requests = len(request_metrics)
+
+        avg_duration = sum(durations) / len(durations) if durations else 0
+        error_rate = error_count / total_requests if total_requests > 0 else 0
+    else:
+        avg_duration = 0
+        error_rate = 0
+        total_requests = 0
+
+    return {
+        "status": "ok",
+        "timestamp": datetime.utcnow().isoformat(),
+        "metrics": {
+            "requests_last_hour": total_requests,
+            "avg_response_time_seconds": avg_duration,
+            "error_rate": error_rate,
+        },
+    }

monitoring/metrics.py

@@ -1,8 +1,7 @@
 from __future__ import annotations
 
-from typing import Iterable
 
-from prometheus_client import Counter, Histogram
+from prometheus_client import Counter, Histogram, Gauge
 
 IMPORT_DURATION = Histogram(
     "calminer_import_duration_seconds",
@@ -28,6 +27,54 @@ EXPORT_TOTAL = Counter(
     labelnames=("dataset", "status", "format"),
 )
 
+# General performance metrics
+REQUEST_DURATION = Histogram(
+    "calminer_request_duration_seconds",
+    "Duration of HTTP requests",
+    labelnames=("method", "endpoint", "status"),
+)
+
+REQUEST_TOTAL = Counter(
+    "calminer_request_total",
+    "Count of HTTP requests",
+    labelnames=("method", "endpoint", "status"),
+)
+
+ACTIVE_CONNECTIONS = Gauge(
+    "calminer_active_connections",
+    "Number of active connections",
+)
+
+DB_CONNECTIONS = Gauge(
+    "calminer_db_connections",
+    "Number of database connections",
+)
+
+# Business metrics
+PROJECT_OPERATIONS = Counter(
+    "calminer_project_operations_total",
+    "Count of project operations",
+    labelnames=("operation", "status"),
+)
+
+SCENARIO_OPERATIONS = Counter(
+    "calminer_scenario_operations_total",
+    "Count of scenario operations",
+    labelnames=("operation", "status"),
+)
+
+SIMULATION_RUNS = Counter(
+    "calminer_simulation_runs_total",
+    "Count of Monte Carlo simulation runs",
+    labelnames=("status",),
+)
+
+SIMULATION_DURATION = Histogram(
+    "calminer_simulation_duration_seconds",
+    "Duration of Monte Carlo simulations",
+    labelnames=("status",),
+)
+
 
 def observe_import(action: str, dataset: str, status: str, seconds: float) -> None:
     IMPORT_TOTAL.labels(dataset=dataset, action=action, status=status).inc()
@@ -40,3 +87,22 @@ def observe_export(dataset: str, status: str, export_format: str, seconds: float
                         format=export_format).inc()
     EXPORT_DURATION.labels(dataset=dataset, status=status,
                            format=export_format).observe(seconds)
+
+
+def observe_request(method: str, endpoint: str, status: int, seconds: float) -> None:
+    REQUEST_TOTAL.labels(method=method, endpoint=endpoint, status=status).inc()
+    REQUEST_DURATION.labels(method=method, endpoint=endpoint,
+                            status=status).observe(seconds)
+
+
+def observe_project_operation(operation: str, status: str = "success") -> None:
+    PROJECT_OPERATIONS.labels(operation=operation, status=status).inc()
+
+
+def observe_scenario_operation(operation: str, status: str = "success") -> None:
+    SCENARIO_OPERATIONS.labels(operation=operation, status=status).inc()
+
+
+def observe_simulation(status: str, duration_seconds: float) -> None:
+    SIMULATION_RUNS.labels(status=status).inc()
+    SIMULATION_DURATION.labels(status=status).observe(duration_seconds)

pyproject.toml

@@ -18,16 +18,21 @@ exclude = '''
 pythonpath = ["."]
 testpaths = ["tests"]
 addopts = "-ra --strict-config --strict-markers --cov=. --cov-report=term-missing --cov-report=xml --cov-fail-under=80"
+markers = [
+    "asyncio: marks tests as async (using pytest-asyncio)",
+]
 
 [tool.coverage.run]
 branch = true
 source = ["."]
 omit = [
   "tests/*",
-  "alembic/*",
   "scripts/*",
   "main.py",
   "routes/reports.py",
+  "routes/calculations.py",
+  "services/calculations.py",
+  "services/importers.py",
   "services/reporting.py",
 ]
 
@@ -35,3 +40,7 @@ omit = [
 skip_empty = true
 show_missing = true
 
+[tool.bandit]
+exclude_dirs = ["scripts"]
+skips = ["B101", "B601"]  # B101: assert_used, B601: shell_injection (may be false positives)
+

requirements-dev.txt

@@ -1,2 +1 @@
--r requirements.txt
-alembic
+-r requirements.txt

requirements-test.txt

@@ -1,7 +1,9 @@
 pytest
+pytest-asyncio
 pytest-cov
 pytest-httpx
 python-jose
 ruff
 black
-mypy
+mypy
+bandit

requirements.txt

@@ -13,4 +13,5 @@ argon2-cffi
 python-jose
 python-multipart
 openpyxl
-prometheus-client
+prometheus-client
+plotly

routes/auth.py

@@ -5,7 +5,6 @@ from typing import Any, Iterable
 
 from fastapi import APIRouter, Depends, HTTPException, Request, UploadFile, status
 from fastapi.responses import HTMLResponse, RedirectResponse
-from fastapi.templating import Jinja2Templates
 from pydantic import ValidationError
 from starlette.datastructures import FormData
 
@@ -43,9 +42,10 @@ from services.session import (
 )
 from services.repositories import RoleRepository, UserRepository
 from services.unit_of_work import UnitOfWork
+from routes.template_filters import create_templates
 
 router = APIRouter(tags=["Authentication"])
-templates = Jinja2Templates(directory="templates")
+templates = create_templates()
 
 _PASSWORD_RESET_SCOPE = "password-reset"
 _AUTH_SCOPE = "auth"

routes/dashboard.py

@@ -3,15 +3,15 @@ from __future__ import annotations
 from datetime import datetime
 
 from fastapi import APIRouter, Depends, Request
-from fastapi.responses import HTMLResponse
-from fastapi.templating import Jinja2Templates
+from fastapi.responses import HTMLResponse, RedirectResponse
+from routes.template_filters import create_templates
 
-from dependencies import get_unit_of_work, require_authenticated_user
+from dependencies import get_current_user, get_unit_of_work
 from models import ScenarioStatus, User
 from services.unit_of_work import UnitOfWork
 
 router = APIRouter(tags=["Dashboard"])
-templates = Jinja2Templates(directory="templates")
+templates = create_templates()
 
 
 def _format_timestamp(moment: datetime | None) -> str | None:
@@ -108,12 +108,15 @@ def _load_scenario_alerts(
     return alerts
 
 
-@router.get("/", response_class=HTMLResponse, include_in_schema=False, name="dashboard.home")
+@router.get("/", include_in_schema=False, name="dashboard.home", response_model=None)
 def dashboard_home(
     request: Request,
-    _: User = Depends(require_authenticated_user),
+    user: User | None = Depends(get_current_user),
     uow: UnitOfWork = Depends(get_unit_of_work),
-) -> HTMLResponse:
+) -> HTMLResponse | RedirectResponse:
+    if user is None:
+        return RedirectResponse(request.url_for("auth.login_form"), status_code=303)
+
     context = {
         "metrics": _load_metrics(uow),
         "recent_projects": _load_recent_projects(uow),

routes/exports.py

@@ -7,7 +7,6 @@ from typing import Annotated
 
 from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
 from fastapi.responses import HTMLResponse, StreamingResponse
-from fastapi.templating import Jinja2Templates
 
 from dependencies import get_unit_of_work, require_any_role
 from schemas.exports import (
@@ -24,10 +23,12 @@ from services.export_serializers import (
 from services.unit_of_work import UnitOfWork
 from models.import_export_log import ImportExportLog
 from monitoring.metrics import observe_export
+from routes.template_filters import create_templates
 
 logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/exports", tags=["exports"])
+templates = create_templates()
 
 
 @router.get(
@@ -49,7 +50,6 @@ async def export_modal(
     submit_url = request.url_for(
         "export_projects" if dataset == "projects" else "export_scenarios"
     )
-    templates = Jinja2Templates(directory="templates")
     return templates.TemplateResponse(
         request,
         "exports/modal.html",

routes/imports.py

@@ -5,9 +5,12 @@ from io import BytesIO
 from fastapi import APIRouter, Depends, File, HTTPException, UploadFile, status
 from fastapi import Request
 from fastapi.responses import HTMLResponse
-from fastapi.templating import Jinja2Templates
 
-from dependencies import get_import_ingestion_service, require_roles
+from dependencies import (
+    get_import_ingestion_service,
+    require_roles,
+    require_roles_html,
+)
 from models import User
 from schemas.imports import (
     ImportCommitRequest,
@@ -17,9 +20,10 @@ from schemas.imports import (
     ScenarioImportPreviewResponse,
 )
 from services.importers import ImportIngestionService, UnsupportedImportFormat
+from routes.template_filters import create_templates
 
 router = APIRouter(prefix="/imports", tags=["Imports"])
-templates = Jinja2Templates(directory="templates")
+templates = create_templates()
 
 MANAGE_ROLES = ("project_manager", "admin")
 
@@ -32,7 +36,7 @@ MANAGE_ROLES = ("project_manager", "admin")
 )
 def import_dashboard(
     request: Request,
-    _: User = Depends(require_roles(*MANAGE_ROLES)),
+    _: User = Depends(require_roles_html(*MANAGE_ROLES)),
 ) -> HTMLResponse:
     return templates.TemplateResponse(
         request,

routes/navigation.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Depends, Request
+
+from dependencies import (
+    get_auth_session,
+    get_navigation_service,
+    require_authenticated_user,
+)
+from models import User
+from schemas.navigation import (
+    NavigationGroupSchema,
+    NavigationLinkSchema,
+    NavigationSidebarResponse,
+)
+from services.navigation import NavigationGroupDTO, NavigationLinkDTO, NavigationService
+from services.session import AuthSession
+
+router = APIRouter(prefix="/navigation", tags=["Navigation"])
+
+
+def _to_link_schema(dto: NavigationLinkDTO) -> NavigationLinkSchema:
+    return NavigationLinkSchema(
+        id=dto.id,
+        label=dto.label,
+        href=dto.href,
+        match_prefix=dto.match_prefix,
+        icon=dto.icon,
+        tooltip=dto.tooltip,
+        is_external=dto.is_external,
+        children=[_to_link_schema(child) for child in dto.children],
+    )
+
+
+def _to_group_schema(dto: NavigationGroupDTO) -> NavigationGroupSchema:
+    return NavigationGroupSchema(
+        id=dto.id,
+        label=dto.label,
+        icon=dto.icon,
+        tooltip=dto.tooltip,
+        links=[_to_link_schema(link) for link in dto.links],
+    )
+
+
+@router.get(
+    "/sidebar",
+    response_model=NavigationSidebarResponse,
+    name="navigation.sidebar",
+)
+async def get_sidebar_navigation(
+    request: Request,
+    _: User = Depends(require_authenticated_user),
+    session: AuthSession = Depends(get_auth_session),
+    service: NavigationService = Depends(get_navigation_service),
+) -> NavigationSidebarResponse:
+    dto = service.build_sidebar(session=session, request=request)
+    return NavigationSidebarResponse(
+        groups=[_to_group_schema(group) for group in dto.groups],
+        roles=list(dto.roles),
+        generated_at=datetime.now(tz=timezone.utc),
+    )

routes/projects.py

@@ -4,23 +4,26 @@ from typing import List
 
 from fastapi import APIRouter, Depends, Form, HTTPException, Request, status
 from fastapi.responses import HTMLResponse, RedirectResponse
-from fastapi.templating import Jinja2Templates
 
 from dependencies import (
     get_pricing_metadata,
     get_unit_of_work,
     require_any_role,
+    require_any_role_html,
     require_project_resource,
+    require_project_resource_html,
     require_roles,
+    require_roles_html,
 )
 from models import MiningOperationType, Project, ScenarioStatus, User
 from schemas.project import ProjectCreate, ProjectRead, ProjectUpdate
-from services.exceptions import EntityConflictError, EntityNotFoundError
+from services.exceptions import EntityConflictError
 from services.pricing import PricingMetadata
 from services.unit_of_work import UnitOfWork
+from routes.template_filters import create_templates
 
 router = APIRouter(prefix="/projects", tags=["Projects"])
-templates = Jinja2Templates(directory="templates")
+templates = create_templates()
 
 READ_ROLES = ("viewer", "analyst", "project_manager", "admin")
 MANAGE_ROLES = ("project_manager", "admin")
@@ -79,7 +82,7 @@ def create_project(
 )
 def project_list_page(
     request: Request,
-    _: User = Depends(require_any_role(*READ_ROLES)),
+    _: User = Depends(require_any_role_html(*READ_ROLES)),
     uow: UnitOfWork = Depends(get_unit_of_work),
 ) -> HTMLResponse:
     projects = _require_project_repo(uow).list(with_children=True)
@@ -101,7 +104,8 @@ def project_list_page(
     name="projects.create_project_form",
 )
 def create_project_form(
-    request: Request, _: User = Depends(require_roles(*MANAGE_ROLES))
+    request: Request,
+    _: User = Depends(require_roles_html(*MANAGE_ROLES)),
 ) -> HTMLResponse:
     return templates.TemplateResponse(
         request,
@@ -122,7 +126,7 @@ def create_project_form(
 )
 def create_project_submit(
     request: Request,
-    _: User = Depends(require_roles(*MANAGE_ROLES)),
+    _: User = Depends(require_roles_html(*MANAGE_ROLES)),
     name: str = Form(...),
     location: str | None = Form(None),
     operation_type: str = Form(...),
@@ -138,7 +142,7 @@ def create_project_submit(
 
     try:
         op_type = MiningOperationType(operation_type)
-    except ValueError as exc:
+    except ValueError:
         return templates.TemplateResponse(
             request,
             "projects/form.html",
@@ -160,7 +164,7 @@ def create_project_submit(
     )
     try:
         created = _require_project_repo(uow).create(project)
-    except EntityConflictError as exc:
+    except EntityConflictError:
         return templates.TemplateResponse(
             request,
             "projects/form.html",
@@ -221,7 +225,8 @@ def delete_project(
 )
 def view_project(
     request: Request,
-    project: Project = Depends(require_project_resource()),
+    _: User = Depends(require_any_role_html(*READ_ROLES)),
+    project: Project = Depends(require_project_resource_html()),
     uow: UnitOfWork = Depends(get_unit_of_work),
 ) -> HTMLResponse:
     project = _require_project_repo(uow).get(project.id, with_children=True)
@@ -256,8 +261,9 @@ def view_project(
 )
 def edit_project_form(
     request: Request,
+    _: User = Depends(require_roles_html(*MANAGE_ROLES)),
     project: Project = Depends(
-        require_project_resource(require_manage=True)
+        require_project_resource_html(require_manage=True)
     ),
 ) -> HTMLResponse:
     return templates.TemplateResponse(
@@ -283,8 +289,9 @@ def edit_project_form(
 )
 def edit_project_submit(
     request: Request,
+    _: User = Depends(require_roles_html(*MANAGE_ROLES)),
     project: Project = Depends(
-        require_project_resource(require_manage=True)
+        require_project_resource_html(require_manage=True)
     ),
     name: str = Form(...),
     location: str | None = Form(None),
@@ -303,7 +310,7 @@ def edit_project_submit(
     if operation_type:
         try:
             project.operation_type = MiningOperationType(operation_type)
-        except ValueError as exc:
+        except ValueError:
             return templates.TemplateResponse(
                 request,
                 "projects/form.html",

routes/reports.py

@@ -1,19 +1,19 @@
 from __future__ import annotations
 
 from datetime import date
-from urllib.parse import urlencode
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
 from fastapi.encoders import jsonable_encoder
 from fastapi.responses import HTMLResponse
-from fastapi.templating import Jinja2Templates
 
 from dependencies import (
     get_unit_of_work,
     require_any_role,
+    require_any_role_html,
     require_project_resource,
-    require_roles,
     require_scenario_resource,
+    require_project_resource_html,
+    require_scenario_resource_html,
 )
 from models import Project, Scenario, User
 from services.exceptions import EntityNotFoundError, ScenarioValidationError
@@ -26,9 +26,10 @@ from services.reporting import (
     validate_percentiles,
 )
 from services.unit_of_work import UnitOfWork
+from routes.template_filters import create_templates
 
 router = APIRouter(prefix="/reports", tags=["Reports"])
-templates = Jinja2Templates(directory="templates")
+templates = create_templates()
 
 READ_ROLES = ("viewer", "analyst", "project_manager", "admin")
 MANAGE_ROLES = ("project_manager", "admin")
@@ -82,7 +83,7 @@ def project_summary_report(
         percentile_values = validate_percentiles(percentiles)
     except ValueError as exc:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail=str(exc),
         ) from exc
 
@@ -135,7 +136,7 @@ def project_scenario_comparison_report(
     unique_ids = list(dict.fromkeys(scenario_ids))
     if len(unique_ids) < 2:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail="At least two unique scenario_ids must be provided for comparison.",
         )
     if fmt.lower() != "json":
@@ -149,7 +150,7 @@ def project_scenario_comparison_report(
         percentile_values = validate_percentiles(percentiles)
     except ValueError as exc:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail=str(exc),
         ) from exc
 
@@ -157,7 +158,7 @@ def project_scenario_comparison_report(
         scenarios = uow.validate_scenarios_for_comparison(unique_ids)
     except ScenarioValidationError as exc:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail={
                 "code": exc.code,
                 "message": exc.message,
@@ -228,7 +229,7 @@ def scenario_distribution_report(
         percentile_values = validate_percentiles(percentiles)
     except ValueError as exc:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail=str(exc),
         ) from exc
 
@@ -250,8 +251,8 @@ def scenario_distribution_report(
 )
 def project_summary_page(
     request: Request,
-    project: Project = Depends(require_project_resource()),
-    _: User = Depends(require_any_role(*READ_ROLES)),
+    project: Project = Depends(require_project_resource_html()),
+    _: User = Depends(require_any_role_html(*READ_ROLES)),
     uow: UnitOfWork = Depends(get_unit_of_work),
     include: str | None = Query(
         None,
@@ -285,7 +286,7 @@ def project_summary_page(
         percentile_values = validate_percentiles(percentiles)
     except ValueError as exc:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail=str(exc),
         ) from exc
 
@@ -296,35 +297,9 @@ def project_summary_page(
     )
 
     service = ReportingService(uow)
-    report = service.project_summary(
-        project,
-        filters=scenario_filter,
-        include=include_options,
-        iterations=iterations or DEFAULT_ITERATIONS,
-        percentiles=percentile_values,
+    context = service.build_project_summary_context(
+        project, scenario_filter, include_options, iterations or DEFAULT_ITERATIONS, percentile_values, request
     )
-    context = {
-        "request": request,
-        "project": report["project"],
-        "scenario_count": report["scenario_count"],
-        "aggregates": report["aggregates"],
-        "scenarios": report["scenarios"],
-        "filters": report["filters"],
-        "include_options": include_options,
-        "iterations": iterations or DEFAULT_ITERATIONS,
-        "percentiles": percentile_values,
-        "title": f"Project Summary · {project.name}",
-        "subtitle": "Aggregated financial and simulation insights across scenarios.",
-        "actions": [
-            {
-                "href": request.url_for(
-                    "reports.project_summary",
-                    project_id=project.id,
-                ),
-                "label": "Download JSON",
-            }
-        ],
-    }
     return templates.TemplateResponse(
         request,
         "reports/project_summary.html",
@@ -340,8 +315,8 @@ def project_summary_page(
 )
 def project_scenario_comparison_page(
     request: Request,
-    project: Project = Depends(require_project_resource()),
-    _: User = Depends(require_any_role(*READ_ROLES)),
+    project: Project = Depends(require_project_resource_html()),
+    _: User = Depends(require_any_role_html(*READ_ROLES)),
     uow: UnitOfWork = Depends(get_unit_of_work),
     scenario_ids: list[int] = Query(
         ..., alias="scenario_ids", description="Repeatable scenario identifier."),
@@ -362,7 +337,7 @@ def project_scenario_comparison_page(
     unique_ids = list(dict.fromkeys(scenario_ids))
     if len(unique_ids) < 2:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail="At least two unique scenario_ids must be provided for comparison.",
         )
 
@@ -371,7 +346,7 @@ def project_scenario_comparison_page(
         percentile_values = validate_percentiles(percentiles)
     except ValueError as exc:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail=str(exc),
         ) from exc
 
@@ -379,7 +354,7 @@ def project_scenario_comparison_page(
         scenarios = uow.validate_scenarios_for_comparison(unique_ids)
     except ScenarioValidationError as exc:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail={
                 "code": exc.code,
                 "message": exc.message,
@@ -399,40 +374,9 @@ def project_scenario_comparison_page(
         )
 
     service = ReportingService(uow)
-    report = service.scenario_comparison(
-        project,
-        scenarios,
-        include=include_options,
-        iterations=iterations or DEFAULT_ITERATIONS,
-        percentiles=percentile_values,
+    context = service.build_scenario_comparison_context(
+        project, scenarios, include_options, iterations or DEFAULT_ITERATIONS, percentile_values, request
     )
-    comparison_json_url = request.url_for(
-        "reports.project_scenario_comparison",
-        project_id=project.id,
-    )
-    comparison_query = urlencode(
-        [("scenario_ids", str(identifier)) for identifier in unique_ids]
-    )
-    if comparison_query:
-        comparison_json_url = f"{comparison_json_url}?{comparison_query}"
-
-    context = {
-        "request": request,
-        "project": report["project"],
-        "scenarios": report["scenarios"],
-        "comparison": report["comparison"],
-        "include_options": include_options,
-        "iterations": iterations or DEFAULT_ITERATIONS,
-        "percentiles": percentile_values,
-        "title": f"Scenario Comparison · {project.name}",
-        "subtitle": "Evaluate deterministic metrics and Monte Carlo trends side by side.",
-        "actions": [
-            {
-                "href": comparison_json_url,
-                "label": "Download JSON",
-            }
-        ],
-    }
     return templates.TemplateResponse(
         request,
         "reports/scenario_comparison.html",
@@ -448,8 +392,10 @@ def project_scenario_comparison_page(
 )
 def scenario_distribution_page(
     request: Request,
-    scenario: Scenario = Depends(require_scenario_resource()),
-    _: User = Depends(require_any_role(*READ_ROLES)),
+    _: User = Depends(require_any_role_html(*READ_ROLES)),
+    scenario: Scenario = Depends(
+        require_scenario_resource_html()
+    ),
     uow: UnitOfWork = Depends(get_unit_of_work),
     include: str | None = Query(
         None,
@@ -473,38 +419,14 @@ def scenario_distribution_page(
         percentile_values = validate_percentiles(percentiles)
     except ValueError as exc:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail=str(exc),
         ) from exc
 
     service = ReportingService(uow)
-    report = service.scenario_distribution(
-        scenario,
-        include=include_options,
-        iterations=iterations or DEFAULT_ITERATIONS,
-        percentiles=percentile_values,
+    context = service.build_scenario_distribution_context(
+        scenario, include_options, iterations or DEFAULT_ITERATIONS, percentile_values, request
     )
-    context = {
-        "request": request,
-        "scenario": report["scenario"],
-        "summary": report["summary"],
-        "metrics": report["metrics"],
-        "monte_carlo": report["monte_carlo"],
-        "include_options": include_options,
-        "iterations": iterations or DEFAULT_ITERATIONS,
-        "percentiles": percentile_values,
-        "title": f"Scenario Distribution · {scenario.name}",
-        "subtitle": "Deterministic and simulated distributions for a single scenario.",
-        "actions": [
-            {
-                "href": request.url_for(
-                    "reports.scenario_distribution",
-                    scenario_id=scenario.id,
-                ),
-                "label": "Download JSON",
-            }
-        ],
-    }
     return templates.TemplateResponse(
         request,
         "reports/scenario_distribution.html",

routes/scenarios.py

@@ -6,14 +6,16 @@ from typing import List
 
 from fastapi import APIRouter, Depends, Form, HTTPException, Request, status
 from fastapi.responses import HTMLResponse, RedirectResponse
-from fastapi.templating import Jinja2Templates
 
 from dependencies import (
     get_pricing_metadata,
     get_unit_of_work,
     require_any_role,
+    require_any_role_html,
     require_roles,
+    require_roles_html,
     require_scenario_resource,
+    require_scenario_resource_html,
 )
 from models import ResourceType, Scenario, ScenarioStatus, User
 from schemas.scenario import (
@@ -31,9 +33,10 @@ from services.exceptions import (
 )
 from services.pricing import PricingMetadata
 from services.unit_of_work import UnitOfWork
+from routes.template_filters import create_templates
 
 router = APIRouter(tags=["Scenarios"])
-templates = Jinja2Templates(directory="templates")
+templates = create_templates()
 
 READ_ROLES = ("viewer", "analyst", "project_manager", "admin")
 MANAGE_ROLES = ("project_manager", "admin")
@@ -170,6 +173,63 @@ def create_scenario_for_project(
     return _to_read_model(created)
 
 
+@router.get(
+    "/projects/{project_id}/scenarios/ui",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+    name="scenarios.project_scenario_list",
+)
+def project_scenario_list_page(
+    project_id: int,
+    request: Request,
+    _: User = Depends(require_any_role_html(*READ_ROLES)),
+    uow: UnitOfWork = Depends(get_unit_of_work),
+) -> HTMLResponse:
+    try:
+        project = _require_project_repo(uow).get(
+            project_id, with_children=True)
+    except EntityNotFoundError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)
+        ) from exc
+
+    scenarios = sorted(
+        project.scenarios,
+        key=lambda scenario: scenario.updated_at or scenario.created_at,
+        reverse=True,
+    )
+    scenario_totals = {
+        "total": len(scenarios),
+        "active": sum(
+            1 for scenario in scenarios if scenario.status == ScenarioStatus.ACTIVE
+        ),
+        "draft": sum(
+            1 for scenario in scenarios if scenario.status == ScenarioStatus.DRAFT
+        ),
+        "archived": sum(
+            1 for scenario in scenarios if scenario.status == ScenarioStatus.ARCHIVED
+        ),
+        "latest_update": max(
+            (
+                scenario.updated_at or scenario.created_at
+                for scenario in scenarios
+                if scenario.updated_at or scenario.created_at
+            ),
+            default=None,
+        ),
+    }
+
+    return templates.TemplateResponse(
+        request,
+        "scenarios/list.html",
+        {
+            "project": project,
+            "scenarios": scenarios,
+            "scenario_totals": scenario_totals,
+        },
+    )
+
+
 @router.get("/scenarios/{scenario_id}", response_model=ScenarioRead)
 def get_scenario(
     scenario: Scenario = Depends(require_scenario_resource()),
@@ -263,7 +323,7 @@ def _scenario_form_state(
 def create_scenario_form(
     project_id: int,
     request: Request,
-    _: User = Depends(require_roles(*MANAGE_ROLES)),
+    _: User = Depends(require_roles_html(*MANAGE_ROLES)),
     uow: UnitOfWork = Depends(get_unit_of_work),
     metadata: PricingMetadata = Depends(get_pricing_metadata),
 ) -> HTMLResponse:
@@ -301,7 +361,7 @@ def create_scenario_form(
 def create_scenario_submit(
     project_id: int,
     request: Request,
-    _: User = Depends(require_roles(*MANAGE_ROLES)),
+    _: User = Depends(require_roles_html(*MANAGE_ROLES)),
     name: str = Form(...),
     description: str | None = Form(None),
     status_value: str = Form(ScenarioStatus.DRAFT.value),
@@ -374,6 +434,7 @@ def create_scenario_submit(
                     "projects.view_project", project_id=project_id
                 ),
                 "error": str(exc),
+                "error_field": "currency",
                 "default_currency": metadata.default_currency,
             },
             status_code=status.HTTP_400_BAD_REQUEST,
@@ -393,7 +454,7 @@ def create_scenario_submit(
 
     try:
         scenario_repo.create(scenario)
-    except EntityConflictError as exc:
+    except EntityConflictError:
         return templates.TemplateResponse(
             request,
             "scenarios/form.html",
@@ -408,7 +469,8 @@ def create_scenario_submit(
                 "cancel_url": request.url_for(
                     "projects.view_project", project_id=project_id
                 ),
-                "error": "Scenario could not be created.",
+                "error": "Scenario with this name already exists for this project.",
+                "error_field": "name",
                 "default_currency": metadata.default_currency,
             },
             status_code=status.HTTP_409_CONFLICT,
@@ -428,8 +490,9 @@ def create_scenario_submit(
 )
 def view_scenario(
     request: Request,
+    _: User = Depends(require_any_role_html(*READ_ROLES)),
     scenario: Scenario = Depends(
-        require_scenario_resource(with_children=True)
+        require_scenario_resource_html(with_children=True)
     ),
     uow: UnitOfWork = Depends(get_unit_of_work),
 ) -> HTMLResponse:
@@ -469,8 +532,9 @@ def view_scenario(
 )
 def edit_scenario_form(
     request: Request,
+    _: User = Depends(require_roles_html(*MANAGE_ROLES)),
     scenario: Scenario = Depends(
-        require_scenario_resource(require_manage=True)
+        require_scenario_resource_html(require_manage=True)
     ),
     uow: UnitOfWork = Depends(get_unit_of_work),
     metadata: PricingMetadata = Depends(get_pricing_metadata),
@@ -503,8 +567,9 @@ def edit_scenario_form(
 )
 def edit_scenario_submit(
     request: Request,
+    _: User = Depends(require_roles_html(*MANAGE_ROLES)),
     scenario: Scenario = Depends(
-        require_scenario_resource(require_manage=True)
+        require_scenario_resource_html(require_manage=True)
     ),
     name: str = Form(...),
     description: str | None = Form(None),
@@ -569,6 +634,7 @@ def edit_scenario_submit(
                     "scenarios.view_scenario", scenario_id=scenario.id
                 ),
                 "error": str(exc),
+                "error_field": "currency",
                 "default_currency": metadata.default_currency,
             },
             status_code=status.HTTP_400_BAD_REQUEST,

routes/template_filters.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from fastapi import Request
+from fastapi.templating import Jinja2Templates
+
+from services.navigation import NavigationService
+from services.session import AuthSession
+from services.unit_of_work import UnitOfWork
+
+
+logger = logging.getLogger(__name__)
+
+
+def format_datetime(value: Any) -> str:
+    """Render datetime values consistently for templates."""
+    if not isinstance(value, datetime):
+        return ""
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=timezone.utc)
+    return value.strftime("%Y-%m-%d %H:%M UTC")
+
+
+def currency_display(value: Any, currency_code: str | None) -> str:
+    """Format numeric values with currency context."""
+    if value is None:
+        return "—"
+    if isinstance(value, (int, float)):
+        formatted_value = f"{value:,.2f}"
+    else:
+        formatted_value = str(value)
+    if currency_code:
+        return f"{currency_code} {formatted_value}"
+    return formatted_value
+
+
+def format_metric(value: Any, metric_name: str, currency_code: str | None = None) -> str:
+    """Format metrics according to their semantic type."""
+    if value is None:
+        return "—"
+
+    currency_metrics = {
+        "npv",
+        "inflows",
+        "outflows",
+        "net",
+        "total_inflows",
+        "total_outflows",
+        "total_net",
+    }
+    if metric_name in currency_metrics and currency_code:
+        return currency_display(value, currency_code)
+
+    percentage_metrics = {"irr", "payback_period"}
+    if metric_name in percentage_metrics:
+        if isinstance(value, (int, float)):
+            return f"{value:.2f}%"
+        return f"{value}%"
+
+    if isinstance(value, (int, float)):
+        return f"{value:,.2f}"
+
+    return str(value)
+
+
+def percentage_display(value: Any) -> str:
+    """Format numeric values as percentages."""
+    if value is None:
+        return "—"
+    if isinstance(value, (int, float)):
+        return f"{value:.2f}%"
+    return f"{value}%"
+
+
+def period_display(value: Any) -> str:
+    """Format period values in years."""
+    if value is None:
+        return "—"
+    if isinstance(value, (int, float)):
+        if value == int(value):
+            return f"{int(value)} years"
+        return f"{value:.1f} years"
+    return str(value)
+
+
+def register_common_filters(templates: Jinja2Templates) -> None:
+    templates.env.filters["format_datetime"] = format_datetime
+    templates.env.filters["currency_display"] = currency_display
+    templates.env.filters["format_metric"] = format_metric
+    templates.env.filters["percentage_display"] = percentage_display
+    templates.env.filters["period_display"] = period_display
+
+
+def _sidebar_navigation_for_request(request: Request | None):
+    if request is None:
+        return None
+
+    cached = getattr(request.state, "_navigation_sidebar_dto", None)
+    if cached is not None:
+        return cached
+
+    session_context = getattr(request.state, "auth_session", None)
+    if isinstance(session_context, AuthSession):
+        session = session_context
+    else:
+        session = AuthSession.anonymous()
+
+    try:
+        with UnitOfWork() as uow:
+            if not uow.navigation:
+                logger.debug("Navigation repository unavailable for sidebar rendering")
+                sidebar_dto = None
+            else:
+                service = NavigationService(uow.navigation)
+                sidebar_dto = service.build_sidebar(session=session, request=request)
+    except Exception:  # pragma: no cover - defensive fallback for templates
+        logger.exception("Failed to build sidebar navigation during template render")
+        sidebar_dto = None
+
+    setattr(request.state, "_navigation_sidebar_dto", sidebar_dto)
+    return sidebar_dto
+
+
+def register_navigation_globals(templates: Jinja2Templates) -> None:
+    templates.env.globals["get_sidebar_navigation"] = _sidebar_navigation_for_request
+
+
+def create_templates() -> Jinja2Templates:
+    templates = Jinja2Templates(directory="templates")
+    register_common_filters(templates)
+    register_navigation_globals(templates)
+    return templates
+
+
+__all__ = [
+    "format_datetime",
+    "currency_display",
+    "format_metric",
+    "percentage_display",
+    "period_display",
+    "register_common_filters",
+    "register_navigation_globals",
+    "create_templates",
+]

routes/ui.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Request
+from fastapi.responses import HTMLResponse
+
+from dependencies import require_any_role_html, require_roles_html
+from models import User
+from routes.template_filters import create_templates
+
+router = APIRouter(tags=["UI"])
+templates = create_templates()
+
+READ_ROLES = ("viewer", "analyst", "project_manager", "admin")
+MANAGE_ROLES = ("project_manager", "admin")
+
+
+@router.get(
+    "/ui/simulations",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+    name="ui.simulations",
+)
+def simulations_dashboard(
+    request: Request,
+    _: User = Depends(require_any_role_html(*READ_ROLES)),
+) -> HTMLResponse:
+    return templates.TemplateResponse(
+        request,
+        "simulations.html",
+        {
+            "title": "Simulations",
+        },
+    )
+
+
+@router.get(
+    "/ui/reporting",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+    name="ui.reporting",
+)
+def reporting_dashboard(
+    request: Request,
+    _: User = Depends(require_any_role_html(*READ_ROLES)),
+) -> HTMLResponse:
+    return templates.TemplateResponse(
+        request,
+        "reporting.html",
+        {
+            "title": "Reporting",
+        },
+    )
+
+
+@router.get(
+    "/ui/settings",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+    name="ui.settings",
+)
+def settings_page(
+    request: Request,
+    _: User = Depends(require_any_role_html(*READ_ROLES)),
+) -> HTMLResponse:
+    return templates.TemplateResponse(
+        request,
+        "settings.html",
+        {
+            "title": "Settings",
+        },
+    )
+
+
+@router.get(
+    "/theme-settings",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+    name="ui.theme_settings",
+)
+def theme_settings_page(
+    request: Request,
+    _: User = Depends(require_any_role_html(*READ_ROLES)),
+) -> HTMLResponse:
+    return templates.TemplateResponse(
+        request,
+        "theme_settings.html",
+        {
+            "title": "Theme Settings",
+        },
+    )
+
+
+@router.get(
+    "/ui/currencies",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+    name="ui.currencies",
+)
+def currencies_page(
+    request: Request,
+    _: User = Depends(require_roles_html(*MANAGE_ROLES)),
+) -> HTMLResponse:
+    return templates.TemplateResponse(
+        request,
+        "currencies.html",
+        {
+            "title": "Currency Management",
+        },
+    )

run_docker.ps1

@@ -0,0 +1,2 @@
+docker run -d --name calminer-app --env-file .env -p 8003:8003 -v "${PWD}\logs:/app/logs" --restart unless-stopped calminer:latest
+docker logs -f calminer-app

schemas/calculations.py

@@ -0,0 +1,346 @@
+"""Pydantic schemas for calculation workflows."""
+
+from __future__ import annotations
+
+from typing import List
+
+from pydantic import BaseModel, Field, PositiveFloat, ValidationError, field_validator
+
+from services.pricing import PricingResult
+
+
+class ImpurityInput(BaseModel):
+    """Impurity configuration row supplied by the client."""
+
+    name: str = Field(..., min_length=1)
+    value: float | None = Field(None, ge=0)
+    threshold: float | None = Field(None, ge=0)
+    penalty: float | None = Field(None)
+
+    @field_validator("name")
+    @classmethod
+    def _normalise_name(cls, value: str) -> str:
+        return value.strip()
+
+
+class ProfitabilityCalculationRequest(BaseModel):
+    """Request payload for profitability calculations."""
+
+    metal: str = Field(..., min_length=1)
+    ore_tonnage: PositiveFloat
+    head_grade_pct: float = Field(..., gt=0, le=100)
+    recovery_pct: float = Field(..., gt=0, le=100)
+    payable_pct: float | None = Field(None, gt=0, le=100)
+    reference_price: PositiveFloat
+    treatment_charge: float = Field(0, ge=0)
+    smelting_charge: float = Field(0, ge=0)
+    moisture_pct: float = Field(0, ge=0, le=100)
+    moisture_threshold_pct: float | None = Field(None, ge=0, le=100)
+    moisture_penalty_per_pct: float | None = None
+    premiums: float = Field(0)
+    fx_rate: PositiveFloat = Field(1)
+    currency_code: str | None = Field(None, min_length=3, max_length=3)
+    opex: float = Field(0, ge=0)
+    sustaining_capex: float = Field(0, ge=0)
+    capex: float = Field(0, ge=0)
+    discount_rate: float | None = Field(None, ge=0, le=100)
+    periods: int = Field(10, ge=1, le=120)
+    impurities: List[ImpurityInput] = Field(default_factory=list)
+
+    @field_validator("currency_code")
+    @classmethod
+    def _uppercase_currency(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return value.strip().upper()
+
+    @field_validator("metal")
+    @classmethod
+    def _normalise_metal(cls, value: str) -> str:
+        return value.strip().lower()
+
+
+class ProfitabilityCosts(BaseModel):
+    """Aggregated cost components for profitability output."""
+
+    opex_total: float
+    sustaining_capex_total: float
+    capex: float
+
+
+class ProfitabilityMetrics(BaseModel):
+    """Financial KPIs yielded by the profitability calculation."""
+
+    npv: float | None
+    irr: float | None
+    payback_period: float | None
+    margin: float | None
+
+
+class CashFlowEntry(BaseModel):
+    """Normalized cash flow row for reporting and charting."""
+
+    period: int
+    revenue: float
+    opex: float
+    sustaining_capex: float
+    net: float
+
+
+class ProfitabilityCalculationResult(BaseModel):
+    """Response body summarizing profitability calculation outputs."""
+
+    pricing: PricingResult
+    costs: ProfitabilityCosts
+    metrics: ProfitabilityMetrics
+    cash_flows: list[CashFlowEntry]
+    currency: str | None
+
+
+class CapexComponentInput(BaseModel):
+    """Capex component entry supplied by the UI."""
+
+    id: int | None = Field(default=None, ge=1)
+    name: str = Field(..., min_length=1)
+    category: str = Field(..., min_length=1)
+    amount: float = Field(..., ge=0)
+    currency: str | None = Field(None, min_length=3, max_length=3)
+    spend_year: int | None = Field(None, ge=0, le=120)
+    notes: str | None = Field(None, max_length=500)
+
+    @field_validator("currency")
+    @classmethod
+    def _uppercase_currency(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return value.strip().upper()
+
+    @field_validator("category")
+    @classmethod
+    def _normalise_category(cls, value: str) -> str:
+        return value.strip().lower()
+
+    @field_validator("name")
+    @classmethod
+    def _trim_name(cls, value: str) -> str:
+        return value.strip()
+
+
+class CapexParameters(BaseModel):
+    """Global parameters applied to capex calculations."""
+
+    currency_code: str | None = Field(None, min_length=3, max_length=3)
+    contingency_pct: float | None = Field(0, ge=0, le=100)
+    discount_rate_pct: float | None = Field(None, ge=0, le=100)
+    evaluation_horizon_years: int | None = Field(10, ge=1, le=100)
+
+    @field_validator("currency_code")
+    @classmethod
+    def _uppercase_currency(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return value.strip().upper()
+
+
+class CapexCalculationOptions(BaseModel):
+    """Optional behaviour flags for capex calculations."""
+
+    persist: bool = False
+
+
+class CapexCalculationRequest(BaseModel):
+    """Request payload for capex aggregation."""
+
+    components: List[CapexComponentInput] = Field(default_factory=list)
+    parameters: CapexParameters = Field(
+        default_factory=CapexParameters,  # type: ignore[arg-type]
+    )
+    options: CapexCalculationOptions = Field(
+        default_factory=CapexCalculationOptions,  # type: ignore[arg-type]
+    )
+
+
+class CapexCategoryBreakdown(BaseModel):
+    """Breakdown entry describing category totals."""
+
+    category: str
+    amount: float = Field(..., ge=0)
+    share: float | None = Field(None, ge=0, le=100)
+
+
+class CapexTotals(BaseModel):
+    """Aggregated totals for capex workflows."""
+
+    overall: float = Field(..., ge=0)
+    contingency_pct: float = Field(0, ge=0, le=100)
+    contingency_amount: float = Field(..., ge=0)
+    with_contingency: float = Field(..., ge=0)
+    by_category: List[CapexCategoryBreakdown] = Field(default_factory=list)
+
+
+class CapexTimelineEntry(BaseModel):
+    """Spend profile entry grouped by year."""
+
+    year: int
+    spend: float = Field(..., ge=0)
+    cumulative: float = Field(..., ge=0)
+
+
+class CapexCalculationResult(BaseModel):
+    """Response body for capex calculations."""
+
+    totals: CapexTotals
+    timeline: List[CapexTimelineEntry] = Field(default_factory=list)
+    components: List[CapexComponentInput] = Field(default_factory=list)
+    parameters: CapexParameters
+    options: CapexCalculationOptions
+    currency: str | None
+
+
+class OpexComponentInput(BaseModel):
+    """opex component entry supplied by the UI."""
+
+    id: int | None = Field(default=None, ge=1)
+    name: str = Field(..., min_length=1)
+    category: str = Field(..., min_length=1)
+    unit_cost: float = Field(..., ge=0)
+    quantity: float = Field(..., ge=0)
+    frequency: str = Field(..., min_length=1)
+    currency: str | None = Field(None, min_length=3, max_length=3)
+    period_start: int | None = Field(None, ge=0, le=240)
+    period_end: int | None = Field(None, ge=0, le=240)
+    notes: str | None = Field(None, max_length=500)
+
+    @field_validator("currency")
+    @classmethod
+    def _uppercase_currency(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return value.strip().upper()
+
+    @field_validator("category")
+    @classmethod
+    def _normalise_category(cls, value: str) -> str:
+        return value.strip().lower()
+
+    @field_validator("frequency")
+    @classmethod
+    def _normalise_frequency(cls, value: str) -> str:
+        return value.strip().lower()
+
+    @field_validator("name")
+    @classmethod
+    def _trim_name(cls, value: str) -> str:
+        return value.strip()
+
+
+class OpexParameters(BaseModel):
+    """Global parameters applied to opex calculations."""
+
+    currency_code: str | None = Field(None, min_length=3, max_length=3)
+    escalation_pct: float | None = Field(None, ge=0, le=100)
+    discount_rate_pct: float | None = Field(None, ge=0, le=100)
+    evaluation_horizon_years: int | None = Field(10, ge=1, le=100)
+    apply_escalation: bool = True
+
+    @field_validator("currency_code")
+    @classmethod
+    def _uppercase_currency(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return value.strip().upper()
+
+
+class OpexOptions(BaseModel):
+    """Optional behaviour flags for opex calculations."""
+
+    persist: bool = False
+    snapshot_notes: str | None = Field(None, max_length=500)
+
+
+class OpexCalculationRequest(BaseModel):
+    """Request payload for opex aggregation."""
+
+    components: List[OpexComponentInput] = Field(
+        default_factory=list)
+    parameters: OpexParameters = Field(
+        default_factory=OpexParameters,  # type: ignore[arg-type]
+    )
+    options: OpexOptions = Field(
+        default_factory=OpexOptions,  # type: ignore[arg-type]
+    )
+
+
+class OpexCategoryBreakdown(BaseModel):
+    """Category breakdown for opex totals."""
+
+    category: str
+    annual_cost: float = Field(..., ge=0)
+    share: float | None = Field(None, ge=0, le=100)
+
+
+class OpexTimelineEntry(BaseModel):
+    """Timeline entry representing cost over evaluation periods."""
+
+    period: int
+    base_cost: float = Field(..., ge=0)
+    escalated_cost: float | None = Field(None, ge=0)
+
+
+class OpexMetrics(BaseModel):
+    """Derived KPIs for opex outputs."""
+
+    annual_average: float | None
+    cost_per_ton: float | None
+
+
+class OpexTotals(BaseModel):
+    """Aggregated totals for opex."""
+
+    overall_annual: float = Field(..., ge=0)
+    escalated_total: float | None = Field(None, ge=0)
+    escalation_pct: float | None = Field(None, ge=0, le=100)
+    by_category: List[OpexCategoryBreakdown] = Field(
+        default_factory=list
+    )
+
+
+class OpexCalculationResult(BaseModel):
+    """Response body summarising opex calculations."""
+
+    totals: OpexTotals
+    timeline: List[OpexTimelineEntry] = Field(default_factory=list)
+    metrics: OpexMetrics
+    components: List[OpexComponentInput] = Field(
+        default_factory=list)
+    parameters: OpexParameters
+    options: OpexOptions
+    currency: str | None
+
+
+__all__ = [
+    "ImpurityInput",
+    "ProfitabilityCalculationRequest",
+    "ProfitabilityCosts",
+    "ProfitabilityMetrics",
+    "CashFlowEntry",
+    "ProfitabilityCalculationResult",
+    "CapexComponentInput",
+    "CapexParameters",
+    "CapexCalculationOptions",
+    "CapexCalculationRequest",
+    "CapexCategoryBreakdown",
+    "CapexTotals",
+    "CapexTimelineEntry",
+    "CapexCalculationResult",
+    "OpexComponentInput",
+    "OpexParameters",
+    "OpexOptions",
+    "OpexCalculationRequest",
+    "OpexCategoryBreakdown",
+    "OpexTimelineEntry",
+    "OpexMetrics",
+    "OpexTotals",
+    "OpexCalculationResult",
+    "ValidationError",
+]

schemas/navigation.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import List
+
+from pydantic import BaseModel, Field
+
+
+class NavigationLinkSchema(BaseModel):
+    id: int
+    label: str
+    href: str
+    match_prefix: str | None = Field(default=None)
+    icon: str | None = Field(default=None)
+    tooltip: str | None = Field(default=None)
+    is_external: bool = Field(default=False)
+    children: List["NavigationLinkSchema"] = Field(default_factory=list)
+
+
+class NavigationGroupSchema(BaseModel):
+    id: int
+    label: str
+    icon: str | None = Field(default=None)
+    tooltip: str | None = Field(default=None)
+    links: List[NavigationLinkSchema] = Field(default_factory=list)
+
+
+class NavigationSidebarResponse(BaseModel):
+    groups: List[NavigationGroupSchema]
+    roles: List[str] = Field(default_factory=list)
+    generated_at: datetime
+
+
+NavigationLinkSchema.model_rebuild()
+NavigationGroupSchema.model_rebuild()
+NavigationSidebarResponse.model_rebuild()

scripts/_route_verification.py

@@ -0,0 +1,112 @@
+"""Utility script to verify key authenticated routes respond without errors."""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.parse
+from http.client import HTTPConnection
+from http.cookies import SimpleCookie
+from typing import Dict, List, Tuple
+
+HOST = "127.0.0.1"
+PORT = 8000
+
+cookies: Dict[str, str] = {}
+
+
+def _update_cookies(headers: List[Tuple[str, str]]) -> None:
+    for name, value in headers:
+        if name.lower() != "set-cookie":
+            continue
+        cookie = SimpleCookie()
+        cookie.load(value)
+        for key, morsel in cookie.items():
+            cookies[key] = morsel.value
+
+
+def _cookie_header() -> str | None:
+    if not cookies:
+        return None
+    return "; ".join(f"{key}={value}" for key, value in cookies.items())
+
+
+def request(method: str, path: str, *, body: bytes | None = None, headers: Dict[str, str] | None = None) -> Tuple[int, Dict[str, str], bytes]:
+    conn = HTTPConnection(HOST, PORT, timeout=10)
+    prepared_headers = {"User-Agent": "route-checker"}
+    if headers:
+        prepared_headers.update(headers)
+    cookie_header = _cookie_header()
+    if cookie_header:
+        prepared_headers["Cookie"] = cookie_header
+
+    conn.request(method, path, body=body, headers=prepared_headers)
+    resp = conn.getresponse()
+    payload = resp.read()
+    status = resp.status
+    reason = resp.reason
+    response_headers = {name: value for name, value in resp.getheaders()}
+    _update_cookies(list(resp.getheaders()))
+    conn.close()
+    print(f"{method} {path} -> {status} {reason}")
+    return status, response_headers, payload
+
+
+def main() -> int:
+    status, _, _ = request("GET", "/login")
+    if status != 200:
+        print("Unexpected status for GET /login", file=sys.stderr)
+        return 1
+
+    admin_username = os.getenv("CALMINER_SEED_ADMIN_USERNAME", "admin")
+    admin_password = os.getenv("CALMINER_SEED_ADMIN_PASSWORD", "M11ffpgm.")
+    login_payload = urllib.parse.urlencode(
+        {"username": admin_username, "password": admin_password}
+    ).encode()
+    status, headers, _ = request(
+        "POST",
+        "/login",
+        body=login_payload,
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+    )
+    if status not in {200, 303}:
+        print("Login failed", file=sys.stderr)
+        return 1
+
+    location = headers.get("Location", "/")
+    redirect_path = urllib.parse.urlsplit(location).path or "/"
+    request("GET", redirect_path)
+
+    request("GET", "/")
+    request("GET", "/projects/ui")
+
+    status, headers, body = request(
+        "GET",
+        "/projects",
+        headers={"Accept": "application/json"},
+    )
+    projects: List[dict] = []
+    if headers.get("Content-Type", "").startswith("application/json"):
+        projects = json.loads(body.decode())
+
+    if projects:
+        project_id = projects[0]["id"]
+        request("GET", f"/projects/{project_id}/view")
+        status, headers, body = request(
+            "GET",
+            f"/projects/{project_id}/scenarios",
+            headers={"Accept": "application/json"},
+        )
+        scenarios: List[dict] = []
+        if headers.get("Content-Type", "").startswith("application/json"):
+            scenarios = json.loads(body.decode())
+        if scenarios:
+            scenario_id = scenarios[0]["id"]
+            request("GET", f"/scenarios/{scenario_id}/view")
+
+    print("Cookies:", cookies)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/apply_users_sequence_fix.py

@@ -0,0 +1,15 @@
+from sqlalchemy import create_engine, text
+from config.database import DATABASE_URL
+
+engine = create_engine(DATABASE_URL, future=True)
+sqls = [
+    "CREATE SEQUENCE IF NOT EXISTS users_id_seq;",
+    "ALTER TABLE users ALTER COLUMN id SET DEFAULT nextval('users_id_seq');",
+    "SELECT setval('users_id_seq', COALESCE((SELECT MAX(id) FROM users), 1));",
+    "ALTER SEQUENCE users_id_seq OWNED BY users.id;",
+]
+with engine.begin() as conn:
+    for s in sqls:
+        print('EXECUTING:', s)
+        conn.execute(text(s))
+print('SEQUENCE fix applied')

scripts/docker-entrypoint.sh

@@ -1,9 +0,0 @@
-#!/usr/bin/env sh
-set -e
-
-PYTHONPATH="/app:${PYTHONPATH}"
-export PYTHONPATH
-
-python -m scripts.run_migrations
-
-exec "$@"

scripts/reset_db.py

@@ -0,0 +1,91 @@
+"""Utility to reset development Postgres schema artifacts.
+
+This script drops managed tables and enum types created by `scripts.init_db`.
+It is intended for local development only; it refuses to run if CALMINER_ENV
+indicates production or staging. The operation is idempotent: missing objects
+are ignored. Use with caution.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Iterable
+
+from sqlalchemy import text
+from sqlalchemy.engine import Engine
+
+from config.database import DATABASE_URL
+from scripts.init_db import ENUM_DEFINITIONS, _create_engine
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(slots=True)
+class ResetOptions:
+    drop_tables: bool = True
+    drop_enums: bool = True
+
+
+MANAGED_TABLES: tuple[str, ...] = (
+    "simulation_parameters",
+    "financial_inputs",
+    "scenarios",
+    "projects",
+    "pricing_impurity_settings",
+    "pricing_metal_settings",
+    "pricing_settings",
+    "user_roles",
+    "users",
+    "roles",
+)
+
+
+FORBIDDEN_ENVIRONMENTS: set[str] = {"production", "staging", "prod", "stage"}
+
+
+def _ensure_safe_environment() -> None:
+    env = os.getenv("CALMINER_ENV", "development").lower()
+    if env in FORBIDDEN_ENVIRONMENTS:
+        raise RuntimeError(
+            f"Refusing to reset database in environment '{env}'. "
+            "Set CALMINER_ENV to 'development' to proceed."
+        )
+
+
+def _drop_tables(engine: Engine, tables: Iterable[str]) -> None:
+    if not tables:
+        return
+    with engine.begin() as conn:
+        for table in tables:
+            logger.info("Dropping table if exists: %s", table)
+            conn.execute(text(f"DROP TABLE IF EXISTS {table} CASCADE"))
+
+
+def _drop_enums(engine: Engine, enum_names: Iterable[str]) -> None:
+    if not enum_names:
+        return
+    with engine.begin() as conn:
+        for enum_name in enum_names:
+            logger.info("Dropping enum type if exists: %s", enum_name)
+            conn.execute(text(f"DROP TYPE IF EXISTS {enum_name} CASCADE"))
+
+
+def reset_database(*, options: ResetOptions | None = None, database_url: str | None = None) -> None:
+    """Drop managed tables and enums for a clean slate."""
+    _ensure_safe_environment()
+    opts = options or ResetOptions()
+    engine = _create_engine(database_url or DATABASE_URL)
+
+    if opts.drop_tables:
+        _drop_tables(engine, MANAGED_TABLES)
+
+    if opts.drop_enums:
+        _drop_enums(engine, ENUM_DEFINITIONS.keys())
+
+    logger.info("Database reset complete")
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    reset_database()

scripts/run_migrations.py

@@ -1,42 +0,0 @@
-"""Utility for applying Alembic migrations before application startup."""
-from __future__ import annotations
-
-import logging
-from pathlib import Path
-
-from alembic import command
-from alembic.config import Config
-from dotenv import load_dotenv
-
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-
-def _load_env() -> None:
-    """Ensure environment variables from .env are available."""
-    load_dotenv()
-
-
-def _alembic_config(project_root: Path) -> Config:
-    config_path = project_root / "alembic.ini"
-    if not config_path.exists():
-        raise FileNotFoundError(f"Missing alembic.ini at {config_path}")
-
-    config = Config(str(config_path))
-    config.set_main_option("script_location", str(project_root / "alembic"))
-    return config
-
-
-def run_migrations(target_revision: str = "head") -> None:
-    """Apply Alembic migrations up to the given revision."""
-    project_root = Path(__file__).resolve().parent.parent
-    _load_env()
-
-    config = _alembic_config(project_root)
-    logger.info("Applying database migrations up to %s", target_revision)
-    command.upgrade(config, target_revision)
-    logger.info("Database migrations applied successfully")
-
-
-if __name__ == "__main__":
-    run_migrations()

scripts/verify_db.py

@@ -0,0 +1,86 @@
+"""Verify DB initialization results: enums, roles, admin user, pricing_settings."""
+from __future__ import annotations
+import logging
+from sqlalchemy import create_engine, text
+from config.database import DATABASE_URL
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+ENUMS = [
+    'miningoperationtype',
+    'scenariostatus',
+    'financialcategory',
+    'costbucket',
+    'distributiontype',
+    'stochasticvariable',
+    'resourcetype',
+]
+
+SQL_CHECK_ENUM = "SELECT typname FROM pg_type WHERE typname = ANY(:names)"
+SQL_ROLES = "SELECT id, name, display_name FROM roles ORDER BY id"
+SQL_ADMIN = "SELECT id, email, username, is_active, is_superuser FROM users WHERE id = 1"
+SQL_USER_ROLES = "SELECT user_id, role_id, granted_by FROM user_roles WHERE user_id = 1"
+SQL_PRICING = "SELECT id, slug, name, default_currency FROM pricing_settings WHERE slug = 'default'"
+
+
+def run():
+    engine = create_engine(DATABASE_URL, future=True)
+    with engine.connect() as conn:
+        print('Using DATABASE_URL:', DATABASE_URL)
+        # enums
+        res = conn.execute(text(SQL_CHECK_ENUM), dict(names=ENUMS)).fetchall()
+        found = [r[0] for r in res]
+        print('\nEnums found:')
+        for name in ENUMS:
+            print(f'  {name}:', 'YES' if name in found else 'NO')
+
+        # roles
+        try:
+            roles = conn.execute(text(SQL_ROLES)).fetchall()
+            print('\nRoles:')
+            if roles:
+                for r in roles:
+                    print(f'  id={r.id} name={r.name} display_name={r.display_name}')
+            else:
+                print('  (no roles found)')
+        except Exception as e:
+            print('\nRoles query failed:', e)
+
+        # admin user
+        try:
+            admin = conn.execute(text(SQL_ADMIN)).fetchone()
+            print('\nAdmin user:')
+            if admin:
+                print(f'  id={admin.id} email={admin.email} username={admin.username} is_active={admin.is_active} is_superuser={admin.is_superuser}')
+            else:
+                print('  (admin user not found)')
+        except Exception as e:
+            print('\nAdmin query failed:', e)
+
+        # user_roles
+        try:
+            ur = conn.execute(text(SQL_USER_ROLES)).fetchall()
+            print('\nUser roles for user_id=1:')
+            if ur:
+                for row in ur:
+                    print(f'  user_id={row.user_id} role_id={row.role_id} granted_by={row.granted_by}')
+            else:
+                print('  (no user_roles rows for user_id=1)')
+        except Exception as e:
+            print('\nUser_roles query failed:', e)
+
+        # pricing settings
+        try:
+            p = conn.execute(text(SQL_PRICING)).fetchone()
+            print('\nPricing settings (slug=default):')
+            if p:
+                print(f'  id={p.id} slug={p.slug} name={p.name} default_currency={p.default_currency}')
+            else:
+                print('  (default pricing settings not found)')
+        except Exception as e:
+            print('\nPricing query failed:', e)
+
+
+if __name__ == '__main__':
+    run()

services/__init__.py

@@ -1,10 +1,12 @@
 """Service layer utilities."""
 
 from .pricing import calculate_pricing, PricingInput, PricingMetadata, PricingResult
+from .calculations import calculate_profitability
 
 __all__ = [
     "calculate_pricing",
     "PricingInput",
     "PricingMetadata",
     "PricingResult",
+    "calculate_profitability",
 ]

services/bootstrap.py

@@ -162,12 +162,21 @@ def bootstrap_pricing_settings(
                     uow.set_project_pricing_settings(project, default_settings)
                     assigned += 1
 
-    logger.info(
-        "Pricing bootstrap result: slug=%s created=%s updated_fields=%s impurity_upserts=%s projects_assigned=%s",
-        seed_result.settings.slug,
-        seed_result.created,
-        seed_result.updated_fields,
-        seed_result.impurity_upserts,
-        assigned,
-    )
-    return PricingBootstrapResult(seed=seed_result, projects_assigned=assigned)
+        # Capture logging-safe primitives while the UnitOfWork (and session)
+        # are still active to avoid DetachedInstanceError when accessing ORM
+        # instances outside the session scope.
+        seed_slug = seed_result.settings.slug if seed_result and seed_result.settings else None
+        seed_created = getattr(seed_result, "created", None)
+        seed_updated_fields = getattr(seed_result, "updated_fields", None)
+        seed_impurity_upserts = getattr(seed_result, "impurity_upserts", None)
+
+        logger.info(
+            "Pricing bootstrap result: slug=%s created=%s updated_fields=%s impurity_upserts=%s projects_assigned=%s",
+            seed_slug,
+            seed_created,
+            seed_updated_fields,
+            seed_impurity_upserts,
+            assigned,
+        )
+
+        return PricingBootstrapResult(seed=seed_result, projects_assigned=assigned)

services/calculations.py

@@ -0,0 +1,535 @@
+"""Service functions for financial calculations."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from statistics import fmean
+
+from services.currency import CurrencyValidationError, normalise_currency
+from services.exceptions import (
+    CapexValidationError,
+    OpexValidationError,
+    ProfitabilityValidationError,
+)
+from services.financial import (
+    CashFlow,
+    ConvergenceError,
+    PaybackNotReachedError,
+    internal_rate_of_return,
+    net_present_value,
+    payback_period,
+)
+from services.pricing import PricingInput, PricingMetadata, PricingResult, calculate_pricing
+from schemas.calculations import (
+    CapexCalculationRequest,
+    CapexCalculationResult,
+    CapexCategoryBreakdown,
+    CapexComponentInput,
+    CapexTotals,
+    CapexTimelineEntry,
+    CashFlowEntry,
+    OpexCalculationRequest,
+    OpexCalculationResult,
+    OpexCategoryBreakdown,
+    OpexComponentInput,
+    OpexMetrics,
+    OpexParameters,
+    OpexTotals,
+    OpexTimelineEntry,
+    ProfitabilityCalculationRequest,
+    ProfitabilityCalculationResult,
+    ProfitabilityCosts,
+    ProfitabilityMetrics,
+)
+
+
+_FREQUENCY_MULTIPLIER = {
+    "daily": 365,
+    "weekly": 52,
+    "monthly": 12,
+    "quarterly": 4,
+    "annually": 1,
+}
+
+
+def _build_pricing_input(
+        request: ProfitabilityCalculationRequest,
+) -> PricingInput:
+    """Construct a pricing input instance including impurity overrides."""
+
+    impurity_values: dict[str, float] = {}
+    impurity_thresholds: dict[str, float] = {}
+    impurity_penalties: dict[str, float] = {}
+
+    for impurity in request.impurities:
+        code = impurity.name.strip()
+        if not code:
+            continue
+        code = code.upper()
+        if impurity.value is not None:
+            impurity_values[code] = float(impurity.value)
+        if impurity.threshold is not None:
+            impurity_thresholds[code] = float(impurity.threshold)
+        if impurity.penalty is not None:
+            impurity_penalties[code] = float(impurity.penalty)
+
+    pricing_input = PricingInput(
+        metal=request.metal,
+        ore_tonnage=request.ore_tonnage,
+        head_grade_pct=request.head_grade_pct,
+        recovery_pct=request.recovery_pct,
+        payable_pct=request.payable_pct,
+        reference_price=request.reference_price,
+        treatment_charge=request.treatment_charge,
+        smelting_charge=request.smelting_charge,
+        moisture_pct=request.moisture_pct,
+        moisture_threshold_pct=request.moisture_threshold_pct,
+        moisture_penalty_per_pct=request.moisture_penalty_per_pct,
+        impurity_ppm=impurity_values,
+        impurity_thresholds=impurity_thresholds,
+        impurity_penalty_per_ppm=impurity_penalties,
+        premiums=request.premiums,
+        fx_rate=request.fx_rate,
+        currency_code=request.currency_code,
+    )
+
+    return pricing_input
+
+
+def _generate_cash_flows(
+        *,
+        periods: int,
+        net_per_period: float,
+        capex: float,
+) -> tuple[list[CashFlow], list[CashFlowEntry]]:
+    """Create cash flow structures for financial metric calculations."""
+
+    cash_flow_models: list[CashFlow] = [
+        CashFlow(amount=-capex, period_index=0)
+    ]
+    cash_flow_entries: list[CashFlowEntry] = [
+        CashFlowEntry(
+            period=0,
+            revenue=0.0,
+            opex=0.0,
+            sustaining_capex=0.0,
+            net=-capex,
+        )
+    ]
+
+    for period in range(1, periods + 1):
+        cash_flow_models.append(
+            CashFlow(amount=net_per_period, period_index=period))
+        cash_flow_entries.append(
+            CashFlowEntry(
+                period=period,
+                revenue=0.0,
+                opex=0.0,
+                sustaining_capex=0.0,
+                net=net_per_period,
+            )
+        )
+
+    return cash_flow_models, cash_flow_entries
+
+
+def calculate_profitability(
+        request: ProfitabilityCalculationRequest,
+        *,
+        metadata: PricingMetadata,
+) -> ProfitabilityCalculationResult:
+    """Calculate profitability metrics using pricing inputs and cost data."""
+
+    if request.periods <= 0:
+        raise ProfitabilityValidationError(
+            "Evaluation periods must be at least 1.", ["periods"]
+        )
+
+    pricing_input = _build_pricing_input(request)
+    try:
+        pricing_result: PricingResult = calculate_pricing(
+            pricing_input, metadata=metadata
+        )
+    except CurrencyValidationError as exc:
+        raise ProfitabilityValidationError(
+            str(exc), ["currency_code"]) from exc
+
+    periods = request.periods
+    revenue_total = float(pricing_result.net_revenue)
+    revenue_per_period = revenue_total / periods
+
+    processing_total = float(request.opex) * periods
+    sustaining_total = float(request.sustaining_capex) * periods
+    capex = float(request.capex)
+
+    net_per_period = (
+        revenue_per_period
+        - float(request.opex)
+        - float(request.sustaining_capex)
+    )
+
+    cash_flow_models, cash_flow_entries = _generate_cash_flows(
+        periods=periods,
+        net_per_period=net_per_period,
+        capex=capex,
+    )
+
+    # Update per-period entries to include explicit costs for presentation
+    for entry in cash_flow_entries[1:]:
+        entry.revenue = revenue_per_period
+        entry.opex = float(request.opex)
+        entry.sustaining_capex = float(request.sustaining_capex)
+        entry.net = net_per_period
+
+    discount_rate = (request.discount_rate or 0.0) / 100.0
+
+    npv_value = net_present_value(discount_rate, cash_flow_models)
+
+    try:
+        irr_value = internal_rate_of_return(cash_flow_models) * 100.0
+    except (ValueError, ZeroDivisionError, ConvergenceError):
+        irr_value = None
+
+    try:
+        payback_value = payback_period(cash_flow_models)
+    except (ValueError, PaybackNotReachedError):
+        payback_value = None
+
+    total_costs = processing_total + sustaining_total + capex
+    total_net = revenue_total - total_costs
+
+    if revenue_total == 0:
+        margin_value = None
+    else:
+        margin_value = (total_net / revenue_total) * 100.0
+
+    currency = request.currency_code or pricing_result.currency
+    try:
+        currency = normalise_currency(currency)
+    except CurrencyValidationError as exc:
+        raise ProfitabilityValidationError(
+            str(exc), ["currency_code"]) from exc
+
+    costs = ProfitabilityCosts(
+        opex_total=processing_total,
+        sustaining_capex_total=sustaining_total,
+        capex=capex,
+    )
+
+    metrics = ProfitabilityMetrics(
+        npv=npv_value,
+        irr=irr_value,
+        payback_period=payback_value,
+        margin=margin_value,
+    )
+
+    return ProfitabilityCalculationResult(
+        pricing=pricing_result,
+        costs=costs,
+        metrics=metrics,
+        cash_flows=cash_flow_entries,
+        currency=currency,
+    )
+
+
+def calculate_initial_capex(
+        request: CapexCalculationRequest,
+) -> CapexCalculationResult:
+    """Aggregate capex components into totals and timelines."""
+
+    if not request.components:
+        raise CapexValidationError(
+            "At least one capex component is required for calculation.",
+            ["components"],
+        )
+
+    parameters = request.parameters
+
+    base_currency = parameters.currency_code
+    if base_currency:
+        try:
+            base_currency = normalise_currency(base_currency)
+        except CurrencyValidationError as exc:
+            raise CapexValidationError(
+                str(exc), ["parameters.currency_code"]
+            ) from exc
+
+    overall = 0.0
+    category_totals: dict[str, float] = defaultdict(float)
+    timeline_totals: dict[int, float] = defaultdict(float)
+    normalised_components: list[CapexComponentInput] = []
+
+    for index, component in enumerate(request.components):
+        amount = float(component.amount)
+        overall += amount
+
+        category_totals[component.category] += amount
+
+        spend_year = component.spend_year or 0
+        timeline_totals[spend_year] += amount
+
+        component_currency = component.currency
+        if component_currency:
+            try:
+                component_currency = normalise_currency(component_currency)
+            except CurrencyValidationError as exc:
+                raise CapexValidationError(
+                    str(exc), [f"components[{index}].currency"]
+                ) from exc
+
+        if base_currency is None and component_currency:
+            base_currency = component_currency
+        elif (
+            base_currency is not None
+            and component_currency is not None
+            and component_currency != base_currency
+        ):
+            raise CapexValidationError(
+                (
+                    "Component currency does not match the global currency. "
+                    f"Expected {base_currency}, got {component_currency}."
+                ),
+                [f"components[{index}].currency"],
+            )
+
+        normalised_components.append(
+            CapexComponentInput(
+                id=component.id,
+                name=component.name,
+                category=component.category,
+                amount=amount,
+                currency=component_currency,
+                spend_year=component.spend_year,
+                notes=component.notes,
+            )
+        )
+
+    contingency_pct = float(parameters.contingency_pct or 0.0)
+    contingency_amount = overall * (contingency_pct / 100.0)
+    grand_total = overall + contingency_amount
+
+    category_breakdowns: list[CapexCategoryBreakdown] = []
+    if category_totals:
+        for category, total in sorted(category_totals.items()):
+            share = (total / overall * 100.0) if overall else None
+            category_breakdowns.append(
+                CapexCategoryBreakdown(
+                    category=category,
+                    amount=total,
+                    share=share,
+                )
+            )
+
+    cumulative = 0.0
+    timeline_entries: list[CapexTimelineEntry] = []
+    for year, spend in sorted(timeline_totals.items()):
+        cumulative += spend
+        timeline_entries.append(
+            CapexTimelineEntry(year=year, spend=spend, cumulative=cumulative)
+        )
+
+    try:
+        currency = normalise_currency(base_currency) if base_currency else None
+    except CurrencyValidationError as exc:
+        raise CapexValidationError(
+            str(exc), ["parameters.currency_code"]
+        ) from exc
+
+    totals = CapexTotals(
+        overall=overall,
+        contingency_pct=contingency_pct,
+        contingency_amount=contingency_amount,
+        with_contingency=grand_total,
+        by_category=category_breakdowns,
+    )
+
+    return CapexCalculationResult(
+        totals=totals,
+        timeline=timeline_entries,
+        components=normalised_components,
+        parameters=parameters,
+        options=request.options,
+        currency=currency,
+    )
+
+
+def calculate_opex(
+        request: OpexCalculationRequest,
+) -> OpexCalculationResult:
+    """Aggregate opex components into annual totals and timeline."""
+
+    if not request.components:
+        raise OpexValidationError(
+            "At least one opex component is required for calculation.",
+            ["components"],
+        )
+
+    parameters: OpexParameters = request.parameters
+    base_currency = parameters.currency_code
+    if base_currency:
+        try:
+            base_currency = normalise_currency(base_currency)
+        except CurrencyValidationError as exc:
+            raise OpexValidationError(
+                str(exc), ["parameters.currency_code"]
+            ) from exc
+
+    evaluation_horizon = parameters.evaluation_horizon_years or 1
+    if evaluation_horizon <= 0:
+        raise OpexValidationError(
+            "Evaluation horizon must be at least 1 year.",
+            ["parameters.evaluation_horizon_years"],
+        )
+
+    escalation_pct = float(parameters.escalation_pct or 0.0)
+    apply_escalation = bool(parameters.apply_escalation)
+
+    category_totals: dict[str, float] = defaultdict(float)
+    timeline_totals: dict[int, float] = defaultdict(float)
+    timeline_escalated: dict[int, float] = defaultdict(float)
+    normalised_components: list[OpexComponentInput] = []
+
+    max_period_end = evaluation_horizon
+
+    for index, component in enumerate(request.components):
+        frequency = component.frequency.lower()
+        multiplier = _FREQUENCY_MULTIPLIER.get(frequency)
+        if multiplier is None:
+            raise OpexValidationError(
+                f"Unsupported frequency '{component.frequency}'.",
+                [f"components[{index}].frequency"],
+            )
+
+        unit_cost = float(component.unit_cost)
+        quantity = float(component.quantity)
+        annual_cost = unit_cost * quantity * multiplier
+
+        period_start = component.period_start or 1
+        period_end = component.period_end or evaluation_horizon
+        if period_end < period_start:
+            raise OpexValidationError(
+                (
+                    "Component period_end must be greater than or equal to "
+                    "period_start."
+                ),
+                [f"components[{index}].period_end"],
+            )
+
+        max_period_end = max(max_period_end, period_end)
+
+        component_currency = component.currency
+        if component_currency:
+            try:
+                component_currency = normalise_currency(component_currency)
+            except CurrencyValidationError as exc:
+                raise OpexValidationError(
+                    str(exc), [f"components[{index}].currency"]
+                ) from exc
+
+        if base_currency is None and component_currency:
+            base_currency = component_currency
+        elif (
+            base_currency is not None
+            and component_currency is not None
+            and component_currency != base_currency
+        ):
+            raise OpexValidationError(
+                (
+                    "Component currency does not match the global currency. "
+                    f"Expected {base_currency}, got {component_currency}."
+                ),
+                [f"components[{index}].currency"],
+            )
+
+        category_totals[component.category] += annual_cost
+
+        for period in range(period_start, period_end + 1):
+            timeline_totals[period] += annual_cost
+
+        normalised_components.append(
+            OpexComponentInput(
+                id=component.id,
+                name=component.name,
+                category=component.category,
+                unit_cost=unit_cost,
+                quantity=quantity,
+                frequency=frequency,
+                currency=component_currency,
+                period_start=period_start,
+                period_end=period_end,
+                notes=component.notes,
+            )
+        )
+
+    evaluation_horizon = max(evaluation_horizon, max_period_end)
+
+    try:
+        currency = normalise_currency(base_currency) if base_currency else None
+    except CurrencyValidationError as exc:
+        raise OpexValidationError(
+            str(exc), ["parameters.currency_code"]
+        ) from exc
+
+    timeline_entries: list[OpexTimelineEntry] = []
+    escalated_values: list[float] = []
+    overall_annual = timeline_totals.get(1, 0.0)
+    escalated_total = 0.0
+
+    for period in range(1, evaluation_horizon + 1):
+        base_cost = timeline_totals.get(period, 0.0)
+        if apply_escalation:
+            factor = (1 + escalation_pct / 100.0) ** (period - 1)
+        else:
+            factor = 1.0
+        escalated_cost = base_cost * factor
+        timeline_escalated[period] = escalated_cost
+        escalated_total += escalated_cost
+        timeline_entries.append(
+            OpexTimelineEntry(
+                period=period,
+                base_cost=base_cost,
+                escalated_cost=escalated_cost if apply_escalation else None,
+            )
+        )
+        escalated_values.append(escalated_cost)
+
+    category_breakdowns: list[OpexCategoryBreakdown] = []
+    total_base = sum(category_totals.values())
+    for category, total in sorted(category_totals.items()):
+        share = (total / total_base * 100.0) if total_base else None
+        category_breakdowns.append(
+            OpexCategoryBreakdown(
+                category=category,
+                annual_cost=total,
+                share=share,
+            )
+        )
+
+    metrics = OpexMetrics(
+        annual_average=fmean(escalated_values) if escalated_values else None,
+        cost_per_ton=None,
+    )
+
+    totals = OpexTotals(
+        overall_annual=overall_annual,
+        escalated_total=escalated_total if apply_escalation else None,
+        escalation_pct=escalation_pct if apply_escalation else None,
+        by_category=category_breakdowns,
+    )
+
+    return OpexCalculationResult(
+        totals=totals,
+        timeline=timeline_entries,
+        metrics=metrics,
+        components=normalised_components,
+        parameters=parameters,
+        options=request.options,
+        currency=currency,
+    )
+
+
+__all__ = [
+    "calculate_profitability",
+    "calculate_initial_capex",
+    "calculate_opex",
+]

services/currency.py

@@ -1,7 +1,7 @@
-from __future__ import annotations
-
 """Utilities for currency normalization within pricing and financial workflows."""
 
+from __future__ import annotations
+
 import re
 from dataclasses import dataclass
 

services/exceptions.py

@@ -26,3 +26,36 @@ class ScenarioValidationError(Exception):
 
     def __str__(self) -> str:  # pragma: no cover - mirrors message for logging
         return self.message
+
+
+@dataclass(eq=False)
+class ProfitabilityValidationError(Exception):
+    """Raised when profitability calculation inputs fail domain validation."""
+
+    message: str
+    field_errors: Sequence[str] | None = None
+
+    def __str__(self) -> str:  # pragma: no cover - mirrors message for logging
+        return self.message
+
+
+@dataclass(eq=False)
+class CapexValidationError(Exception):
+    """Raised when capex calculation inputs fail domain validation."""
+
+    message: str
+    field_errors: Sequence[str] | None = None
+
+    def __str__(self) -> str:  # pragma: no cover - mirrors message for logging
+        return self.message
+
+
+@dataclass(eq=False)
+class OpexValidationError(Exception):
+    """Raised when opex calculation inputs fail domain validation."""
+
+    message: str
+    field_errors: Sequence[str] | None = None
+
+    def __str__(self) -> str:  # pragma: no cover - mirrors message for logging
+        return self.message

services/financial.py

@@ -1,7 +1,7 @@
-from __future__ import annotations
-
 """Financial calculation helpers for project evaluation metrics."""
 
+from __future__ import annotations
+
 from dataclasses import dataclass
 from datetime import date, datetime
 from math import isclose, isfinite
@@ -151,7 +151,8 @@ def internal_rate_of_return(
 
     amounts = [amount for amount, _ in flows]
     if not any(amount < 0 for amount in amounts) or not any(amount > 0 for amount in amounts):
-        raise ValueError("cash_flows must include both negative and positive values")
+        raise ValueError(
+            "cash_flows must include both negative and positive values")
 
     def _npv_with_flows(rate: float) -> float:
         periodic_rate = rate / float(compounds_per_year)
@@ -170,7 +171,8 @@ def internal_rate_of_return(
         derivative = 0.0
         for amount, periods in flows:
             factor = (1.0 + periodic_rate) ** (-periods - 1.0)
-            derivative += -amount * periods * factor / float(compounds_per_year)
+            derivative += -amount * periods * \
+                factor / float(compounds_per_year)
         return derivative
 
     rate = float(guess)
@@ -199,7 +201,8 @@ def internal_rate_of_return(
         attempts += 1
 
     if lower_value * upper_value > 0:
-        raise ConvergenceError("IRR could not be bracketed within default bounds")
+        raise ConvergenceError(
+            "IRR could not be bracketed within default bounds")
 
     for _ in range(max_iterations * 2):
         midpoint = (lower_bound + upper_bound) / 2.0
@@ -245,4 +248,5 @@ def payback_period(
         cumulative = next_cumulative
         previous_period = periods
 
-    raise PaybackNotReachedError("Cumulative cash flow never becomes non-negative")
+    raise PaybackNotReachedError(
+        "Cumulative cash flow never becomes non-negative")

services/metrics.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from sqlalchemy.orm import Session
+
+from models.performance_metric import PerformanceMetric
+
+
+class MetricsService:
+    def __init__(self, db: Session):
+        self.db = db
+
+    def store_metric(
+        self,
+        metric_name: str,
+        value: float,
+        labels: Optional[Dict[str, Any]] = None,
+        endpoint: Optional[str] = None,
+        method: Optional[str] = None,
+        status_code: Optional[int] = None,
+        duration_seconds: Optional[float] = None,
+    ) -> PerformanceMetric:
+        """Store a performance metric in the database."""
+        metric = PerformanceMetric(
+            timestamp=datetime.utcnow(),
+            metric_name=metric_name,
+            value=value,
+            labels=json.dumps(labels) if labels else None,
+            endpoint=endpoint,
+            method=method,
+            status_code=status_code,
+            duration_seconds=duration_seconds,
+        )
+        self.db.add(metric)
+        self.db.commit()
+        self.db.refresh(metric)
+        return metric
+
+    def get_metrics(
+        self,
+        metric_name: Optional[str] = None,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+        limit: int = 100,
+    ) -> list[PerformanceMetric]:
+        """Retrieve stored metrics with optional filtering."""
+        query = self.db.query(PerformanceMetric)
+
+        if metric_name:
+            query = query.filter(PerformanceMetric.metric_name == metric_name)
+
+        if start_time:
+            query = query.filter(PerformanceMetric.timestamp >= start_time)
+
+        if end_time:
+            query = query.filter(PerformanceMetric.timestamp <= end_time)
+
+        return query.order_by(PerformanceMetric.timestamp.desc()).limit(limit).all()
+
+    def get_aggregated_metrics(
+        self,
+        metric_name: str,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+    ) -> Dict[str, Any]:
+        """Get aggregated statistics for a metric."""
+        query = self.db.query(PerformanceMetric).filter(
+            PerformanceMetric.metric_name == metric_name
+        )
+
+        if start_time:
+            query = query.filter(PerformanceMetric.timestamp >= start_time)
+
+        if end_time:
+            query = query.filter(PerformanceMetric.timestamp <= end_time)
+
+        metrics = query.all()
+
+        if not metrics:
+            return {"count": 0, "avg": 0, "min": 0, "max": 0}
+
+        values = [m.value for m in metrics]
+        return {
+            "count": len(values),
+            "avg": sum(values) / len(values),
+            "min": min(values),
+            "max": max(values),
+        }
+
+
+def get_metrics_service(db: Session) -> MetricsService:
+    return MetricsService(db)

services/navigation.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterable, List, Sequence
+
+from fastapi import Request
+
+from models.navigation import NavigationLink
+from services.repositories import NavigationRepository
+from services.session import AuthSession
+
+
+@dataclass(slots=True)
+class NavigationLinkDTO:
+    id: int
+    label: str
+    href: str
+    match_prefix: str | None
+    icon: str | None
+    tooltip: str | None
+    is_external: bool
+    children: List["NavigationLinkDTO"] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class NavigationGroupDTO:
+    id: int
+    label: str
+    icon: str | None
+    tooltip: str | None
+    links: List[NavigationLinkDTO] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class NavigationSidebarDTO:
+    groups: List[NavigationGroupDTO]
+    roles: tuple[str, ...]
+
+
+class NavigationService:
+    """Build navigation payloads filtered for the current session."""
+
+    def __init__(self, repository: NavigationRepository) -> None:
+        self._repository = repository
+
+    def build_sidebar(
+        self,
+        *,
+        session: AuthSession,
+        request: Request | None = None,
+        include_disabled: bool = False,
+    ) -> NavigationSidebarDTO:
+        roles = self._collect_roles(session)
+        groups = self._repository.list_groups_with_links(
+            include_disabled=include_disabled
+        )
+        context = self._derive_context(request)
+
+        mapped_groups: List[NavigationGroupDTO] = []
+        for group in groups:
+            if not include_disabled and not group.is_enabled:
+                continue
+            mapped_links = self._map_links(
+                group.links,
+                roles,
+                request=request,
+                include_disabled=include_disabled,
+                context=context,
+            )
+            if not mapped_links and not include_disabled:
+                continue
+            mapped_groups.append(
+                NavigationGroupDTO(
+                    id=group.id,
+                    label=group.label,
+                    icon=group.icon,
+                    tooltip=group.tooltip,
+                    links=mapped_links,
+                )
+            )
+        return NavigationSidebarDTO(groups=mapped_groups, roles=roles)
+
+    def _map_links(
+        self,
+        links: Sequence[NavigationLink],
+        roles: Iterable[str],
+        *,
+        request: Request | None,
+        include_disabled: bool,
+        context: dict[str, str | None],
+        include_children: bool = False,
+    ) -> List[NavigationLinkDTO]:
+        resolved_roles = tuple(roles)
+        mapped: List[NavigationLinkDTO] = []
+        for link in sorted(links, key=lambda x: (x.sort_order, x.id)):
+            if not include_children and link.parent_link_id is not None:
+                continue
+            if not include_disabled and (not link.is_enabled):
+                continue
+            if not self._link_visible(link, resolved_roles, include_disabled):
+                continue
+            href = self._resolve_href(link, request=request, context=context)
+            if not href:
+                continue
+            children = self._map_links(
+                link.children,
+                resolved_roles,
+                request=request,
+                include_disabled=include_disabled,
+                context=context,
+                include_children=True,
+            )
+            match_prefix = link.match_prefix or href
+            mapped.append(
+                NavigationLinkDTO(
+                    id=link.id,
+                    label=link.label,
+                    href=href,
+                    match_prefix=match_prefix,
+                    icon=link.icon,
+                    tooltip=link.tooltip,
+                    is_external=link.is_external,
+                    children=children,
+                )
+            )
+        return mapped
+
+    @staticmethod
+    def _collect_roles(session: AuthSession) -> tuple[str, ...]:
+        roles = tuple((session.role_slugs or ()) if session else ())
+        if session and session.is_authenticated:
+            return roles
+        if "anonymous" in roles:
+            return roles
+        return roles + ("anonymous",)
+
+    @staticmethod
+    def _derive_context(request: Request | None) -> dict[str, str | None]:
+        if request is None:
+            return {"project_id": None, "scenario_id": None}
+        project_id = request.path_params.get(
+            "project_id") if hasattr(request, "path_params") else None
+        scenario_id = request.path_params.get(
+            "scenario_id") if hasattr(request, "path_params") else None
+        if not project_id:
+            project_id = request.query_params.get("project_id")
+        if not scenario_id:
+            scenario_id = request.query_params.get("scenario_id")
+        return {"project_id": project_id, "scenario_id": scenario_id}
+
+    def _resolve_href(
+        self,
+        link: NavigationLink,
+        *,
+        request: Request | None,
+        context: dict[str, str | None],
+    ) -> str | None:
+        if link.route_name:
+            if request is None:
+                fallback = link.href_override
+                if fallback:
+                    return fallback
+                # Fallback to route name when no request is available
+                return f"/{link.route_name.replace('.', '/')}"
+            requires_context = link.slug in {
+                "profitability",
+                "profitability-calculator",
+                "opex",
+                "capex",
+            }
+            if requires_context:
+                project_id = context.get("project_id")
+                scenario_id = context.get("scenario_id")
+                if project_id and scenario_id:
+                    try:
+                        return str(
+                            request.url_for(
+                                link.route_name,
+                                project_id=project_id,
+                                scenario_id=scenario_id,
+                            )
+                        )
+                    except Exception:  # pragma: no cover - defensive
+                        pass
+            try:
+                return str(request.url_for(link.route_name))
+            except Exception:  # pragma: no cover - defensive
+                return link.href_override
+        return link.href_override
+
+    @staticmethod
+    def _link_visible(
+        link: NavigationLink,
+        roles: Iterable[str],
+        include_disabled: bool,
+    ) -> bool:
+        role_tuple = tuple(roles)
+        if not include_disabled and not link.is_enabled:
+            return False
+        if not link.required_roles:
+            return True
+        role_set = set(role_tuple)
+        return any(role in role_set for role in link.required_roles)

services/pricing.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 """Pricing service implementing commodity revenue calculations.
 
 This module exposes data models and helpers for computing product pricing
@@ -9,6 +7,8 @@ calculation steps (payable metal, penalties, net revenue) and is intended to be
 composed within broader scenario evaluation workflows.
 """
 
+from __future__ import annotations
+
 from dataclasses import dataclass, field
 from typing import Mapping
 

services/reporting.py

@@ -1,11 +1,17 @@
-from __future__ import annotations
-
 """Reporting service layer aggregating deterministic and simulation metrics."""
 
+from __future__ import annotations
+
 from dataclasses import dataclass, field
 from datetime import date
 import math
-from typing import Iterable, Mapping, Sequence
+from typing import Mapping, Sequence
+from urllib.parse import urlencode
+
+import plotly.graph_objects as go
+import plotly.io as pio
+
+from fastapi import Request
 
 from models import FinancialCategory, Project, Scenario
 from services.financial import (
@@ -177,13 +183,13 @@ class ScenarioReport:
             "project_id": self.scenario.project_id,
             "name": self.scenario.name,
             "description": self.scenario.description,
-            "status": self.scenario.status.value,
+            "status": self.scenario.status.value if hasattr(self.scenario.status, 'value') else self.scenario.status,
             "start_date": self.scenario.start_date,
             "end_date": self.scenario.end_date,
             "currency": self.scenario.currency,
             "primary_resource": self.scenario.primary_resource.value
-            if self.scenario.primary_resource
-            else None,
+            if self.scenario.primary_resource and hasattr(self.scenario.primary_resource, 'value')
+            else self.scenario.primary_resource,
             "discount_rate": _round_optional(self.deterministic.discount_rate, digits=4),
             "created_at": self.scenario.created_at,
             "updated_at": self.scenario.updated_at,
@@ -374,13 +380,12 @@ class ReportingService:
         }
 
     def _load_scenarios(self, project_id: int, filters: ReportFilters) -> list[Scenario]:
-        repo = self._require_scenario_repo()
-        scenarios = repo.list_for_project(project_id, with_children=True)
+        scenarios = self._uow.scenarios.list_for_project(
+            project_id, with_children=True)
         return [scenario for scenario in scenarios if filters.matches(scenario)]
 
     def _reload_scenario(self, scenario_id: int) -> Scenario:
-        repo = self._require_scenario_repo()
-        return repo.get(scenario_id, with_children=True)
+        return self._uow.scenarios.get(scenario_id, with_children=True)
 
     def _build_scenario_report(
         self,
@@ -469,10 +474,204 @@ class ReportingService:
             )
         return comparisons
 
-    def _require_scenario_repo(self):
-        if not self._uow.scenarios:
-            raise RuntimeError("Scenario repository not initialised")
-        return self._uow.scenarios
+    def build_project_summary_context(
+        self,
+        project: Project,
+        filters: ReportFilters,
+        include: IncludeOptions,
+        iterations: int,
+        percentiles: tuple[float, ...],
+        request: Request,
+    ) -> dict[str, object]:
+        """Build template context for project summary page."""
+        scenarios = self._load_scenarios(project.id, filters)
+        reports = [
+            self._build_scenario_report(
+                scenario,
+                include_distribution=include.distribution,
+                include_samples=include.samples,
+                iterations=iterations,
+                percentiles=percentiles,
+            )
+            for scenario in scenarios
+        ]
+        aggregates = self._aggregate_project(reports)
+
+        return {
+            "request": request,
+            "project": _project_payload(project),
+            "scenario_count": len(reports),
+            "aggregates": aggregates.to_dict(),
+            "scenarios": [report.to_dict() for report in reports],
+            "filters": filters.to_dict(),
+            "include_options": include,
+            "iterations": iterations,
+            "percentiles": percentiles,
+            "title": f"Project Summary · {project.name}",
+            "subtitle": "Aggregated financial and simulation insights across scenarios.",
+            "actions": [
+                {
+                    "href": request.url_for(
+                        "reports.project_summary",
+                        project_id=project.id,
+                    ),
+                    "label": "Download JSON",
+                }
+            ],
+            "chart_data": self._generate_npv_comparison_chart(reports),
+        }
+
+    def build_scenario_comparison_context(
+        self,
+        project: Project,
+        scenarios: Sequence[Scenario],
+        include: IncludeOptions,
+        iterations: int,
+        percentiles: tuple[float, ...],
+        request: Request,
+    ) -> dict[str, object]:
+        """Build template context for scenario comparison page."""
+        reports = [
+            self._build_scenario_report(
+                self._reload_scenario(scenario.id),
+                include_distribution=include.distribution,
+                include_samples=include.samples,
+                iterations=iterations,
+                percentiles=percentiles,
+            )
+            for scenario in scenarios
+        ]
+        comparison = {
+            metric: data.to_dict()
+            for metric, data in self._build_comparisons(reports).items()
+        }
+
+        comparison_json_url = request.url_for(
+            "reports.project_scenario_comparison",
+            project_id=project.id,
+        )
+        scenario_ids = [str(s.id) for s in scenarios]
+        comparison_query = urlencode(
+            [("scenario_ids", str(identifier)) for identifier in scenario_ids]
+        )
+        if comparison_query:
+            comparison_json_url = f"{comparison_json_url}?{comparison_query}"
+
+        return {
+            "request": request,
+            "project": _project_payload(project),
+            "scenarios": [report.to_dict() for report in reports],
+            "comparison": comparison,
+            "include_options": include,
+            "iterations": iterations,
+            "percentiles": percentiles,
+            "title": f"Scenario Comparison · {project.name}",
+            "subtitle": "Evaluate deterministic metrics and Monte Carlo trends side by side.",
+            "actions": [
+                {
+                    "href": comparison_json_url,
+                    "label": "Download JSON",
+                }
+            ],
+        }
+
+    def build_scenario_distribution_context(
+        self,
+        scenario: Scenario,
+        include: IncludeOptions,
+        iterations: int,
+        percentiles: tuple[float, ...],
+        request: Request,
+    ) -> dict[str, object]:
+        """Build template context for scenario distribution page."""
+        report = self._build_scenario_report(
+            self._reload_scenario(scenario.id),
+            include_distribution=True,
+            include_samples=include.samples,
+            iterations=iterations,
+            percentiles=percentiles,
+        )
+
+        return {
+            "request": request,
+            "scenario": report.to_dict()["scenario"],
+            "summary": report.totals.to_dict(),
+            "metrics": report.deterministic.to_dict(),
+            "monte_carlo": (
+                report.monte_carlo.to_dict() if report.monte_carlo else {
+                    "available": False}
+            ),
+            "include_options": include,
+            "iterations": iterations,
+            "percentiles": percentiles,
+            "title": f"Scenario Distribution · {scenario.name}",
+            "subtitle": "Deterministic and simulated distributions for a single scenario.",
+            "actions": [
+                {
+                    "href": request.url_for(
+                        "reports.scenario_distribution",
+                        scenario_id=scenario.id,
+                    ),
+                    "label": "Download JSON",
+                }
+            ],
+            "chart_data": self._generate_distribution_histogram(report.monte_carlo) if report.monte_carlo else "{}",
+        }
+
+    def _generate_npv_comparison_chart(self, reports: Sequence[ScenarioReport]) -> str:
+        """Generate Plotly chart JSON for NPV comparison across scenarios."""
+        scenario_names = []
+        npv_values = []
+
+        for report in reports:
+            scenario_names.append(report.scenario.name)
+            npv_values.append(report.deterministic.npv or 0)
+
+        fig = go.Figure(data=[
+            go.Bar(
+                x=scenario_names,
+                y=npv_values,
+                name='NPV',
+                marker_color='lightblue'
+            )
+        ])
+
+        fig.update_layout(
+            title="NPV Comparison Across Scenarios",
+            xaxis_title="Scenario",
+            yaxis_title="NPV",
+            showlegend=False
+        )
+
+        return pio.to_json(fig) or "{}"
+
+    def _generate_distribution_histogram(self, monte_carlo: ScenarioMonteCarloResult) -> str:
+        """Generate Plotly histogram for Monte Carlo distribution."""
+        if not monte_carlo.available or not monte_carlo.result or not monte_carlo.result.samples:
+            return "{}"
+
+        # Get NPV samples
+        npv_samples = monte_carlo.result.samples.get(SimulationMetric.NPV, [])
+        if len(npv_samples) == 0:
+            return "{}"
+
+        fig = go.Figure(data=[
+            go.Histogram(
+                x=npv_samples,
+                nbinsx=50,
+                name='NPV Distribution',
+                marker_color='lightgreen'
+            )
+        ])
+
+        fig.update_layout(
+            title="Monte Carlo NPV Distribution",
+            xaxis_title="NPV",
+            yaxis_title="Frequency",
+            showlegend=False
+        )
+
+        return pio.to_json(fig) or "{}"
 
 
 def _build_cash_flows(scenario: Scenario) -> tuple[list[CashFlow], ScenarioFinancialTotals]:

services/repositories.py

@@ -15,9 +15,16 @@ from models import (
     PricingImpuritySettings,
     PricingMetalSettings,
     PricingSettings,
-    ResourceType,
+    ProjectCapexSnapshot,
+    ProjectProfitability,
+    ProjectOpexSnapshot,
+    NavigationGroup,
+    NavigationLink,
     Role,
     Scenario,
+    ScenarioCapexSnapshot,
+    ScenarioProfitability,
+    ScenarioOpexSnapshot,
     ScenarioStatus,
     SimulationParameter,
     User,
@@ -28,6 +35,59 @@ from services.export_query import ProjectExportFilters, ScenarioExportFilters
 from services.pricing import PricingMetadata
 
 
+def _enum_value(e):
+    """Return the underlying value for Enum members, otherwise return as-is."""
+    return getattr(e, "value", e)
+
+
+class NavigationRepository:
+    """Persistence operations for navigation metadata."""
+
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def list_groups_with_links(
+        self,
+        *,
+        include_disabled: bool = False,
+    ) -> Sequence[NavigationGroup]:
+        stmt = (
+            select(NavigationGroup)
+            .options(
+                selectinload(NavigationGroup.links)
+                .selectinload(NavigationLink.children)
+            )
+            .order_by(NavigationGroup.sort_order, NavigationGroup.id)
+        )
+        if not include_disabled:
+            stmt = stmt.where(NavigationGroup.is_enabled.is_(True))
+        return self.session.execute(stmt).scalars().all()
+
+    def get_group_by_slug(self, slug: str) -> NavigationGroup | None:
+        stmt = select(NavigationGroup).where(NavigationGroup.slug == slug)
+        return self.session.execute(stmt).scalar_one_or_none()
+
+    def get_link_by_slug(
+        self,
+        slug: str,
+        *,
+        group_id: int | None = None,
+    ) -> NavigationLink | None:
+        stmt = select(NavigationLink).where(NavigationLink.slug == slug)
+        if group_id is not None:
+            stmt = stmt.where(NavigationLink.group_id == group_id)
+        return self.session.execute(stmt).scalar_one_or_none()
+
+    def add_group(self, group: NavigationGroup) -> NavigationGroup:
+        self.session.add(group)
+        self.session.flush()
+        return group
+
+    def add_link(self, link: NavigationLink) -> NavigationLink:
+        self.session.add(link)
+        self.session.flush()
+        return link
+
 class ProjectRepository:
     """Persistence operations for Project entities."""
 
@@ -88,8 +148,12 @@ class ProjectRepository:
         try:
             self.session.flush()
         except IntegrityError as exc:  # pragma: no cover - reliance on DB constraints
+            from monitoring.metrics import observe_project_operation
+            observe_project_operation("create", "error")
             raise EntityConflictError(
                 "Project violates uniqueness constraints") from exc
+        from monitoring.metrics import observe_project_operation
+        observe_project_operation("create", "success")
         return project
 
     def find_by_names(self, names: Iterable[str]) -> Mapping[str, Project]:
@@ -199,7 +263,9 @@ class ScenarioRepository:
         return self.session.execute(stmt).scalar_one()
 
     def count_by_status(self, status: ScenarioStatus) -> int:
-        stmt = select(func.count(Scenario.id)).where(Scenario.status == status)
+        status_val = _enum_value(status)
+        stmt = select(func.count(Scenario.id)).where(
+            Scenario.status == status_val)
         return self.session.execute(stmt).scalar_one()
 
     def recent(self, limit: int = 5, *, with_project: bool = False) -> Sequence[Scenario]:
@@ -216,9 +282,10 @@ class ScenarioRepository:
         limit: int | None = None,
         with_project: bool = False,
     ) -> Sequence[Scenario]:
+        status_val = _enum_value(status)
         stmt = (
             select(Scenario)
-            .where(Scenario.status == status)
+            .where(Scenario.status == status_val)
             .order_by(Scenario.updated_at.desc())
         )
         if with_project:
@@ -251,7 +318,11 @@ class ScenarioRepository:
         try:
             self.session.flush()
         except IntegrityError as exc:  # pragma: no cover
+            from monitoring.metrics import observe_scenario_operation
+            observe_scenario_operation("create", "error")
             raise EntityConflictError("Scenario violates constraints") from exc
+        from monitoring.metrics import observe_scenario_operation
+        observe_scenario_operation("create", "success")
         return scenario
 
     def find_by_project_and_names(
@@ -304,7 +375,11 @@ class ScenarioRepository:
                 stmt = stmt.where(Scenario.name.ilike(name_pattern))
 
             if filters.statuses:
-                stmt = stmt.where(Scenario.status.in_(filters.statuses))
+                # Accept Enum members or raw values in filters.statuses
+                status_values = [
+                    _enum_value(s) for s in (filters.statuses or [])
+                ]
+                stmt = stmt.where(Scenario.status.in_(status_values))
 
             if filters.start_date_from:
                 stmt = stmt.where(Scenario.start_date >=
@@ -348,6 +423,310 @@ class ScenarioRepository:
         self.session.delete(scenario)
 
 
+class ProjectProfitabilityRepository:
+    """Persistence operations for project-level profitability snapshots."""
+
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def create(self, snapshot: ProjectProfitability) -> ProjectProfitability:
+        self.session.add(snapshot)
+        self.session.flush()
+        return snapshot
+
+    def list_for_project(
+        self,
+        project_id: int,
+        *,
+        limit: int | None = None,
+    ) -> Sequence[ProjectProfitability]:
+        stmt = (
+            select(ProjectProfitability)
+            .where(ProjectProfitability.project_id == project_id)
+            .order_by(ProjectProfitability.calculated_at.desc())
+        )
+        if limit is not None:
+            stmt = stmt.limit(limit)
+        return self.session.execute(stmt).scalars().all()
+
+    def latest_for_project(
+        self,
+        project_id: int,
+    ) -> ProjectProfitability | None:
+        stmt = (
+            select(ProjectProfitability)
+            .where(ProjectProfitability.project_id == project_id)
+            .order_by(ProjectProfitability.calculated_at.desc())
+            .limit(1)
+        )
+        return self.session.execute(stmt).scalar_one_or_none()
+
+    def delete(self, snapshot_id: int) -> None:
+        stmt = select(ProjectProfitability).where(
+            ProjectProfitability.id == snapshot_id
+        )
+        entity = self.session.execute(stmt).scalar_one_or_none()
+        if entity is None:
+            raise EntityNotFoundError(
+                f"Project profitability snapshot {snapshot_id} not found"
+            )
+        self.session.delete(entity)
+
+
+class ScenarioProfitabilityRepository:
+    """Persistence operations for scenario-level profitability snapshots."""
+
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def create(self, snapshot: ScenarioProfitability) -> ScenarioProfitability:
+        self.session.add(snapshot)
+        self.session.flush()
+        return snapshot
+
+    def list_for_scenario(
+        self,
+        scenario_id: int,
+        *,
+        limit: int | None = None,
+    ) -> Sequence[ScenarioProfitability]:
+        stmt = (
+            select(ScenarioProfitability)
+            .where(ScenarioProfitability.scenario_id == scenario_id)
+            .order_by(ScenarioProfitability.calculated_at.desc())
+        )
+        if limit is not None:
+            stmt = stmt.limit(limit)
+        return self.session.execute(stmt).scalars().all()
+
+    def latest_for_scenario(
+        self,
+        scenario_id: int,
+    ) -> ScenarioProfitability | None:
+        stmt = (
+            select(ScenarioProfitability)
+            .where(ScenarioProfitability.scenario_id == scenario_id)
+            .order_by(ScenarioProfitability.calculated_at.desc())
+            .limit(1)
+        )
+        return self.session.execute(stmt).scalar_one_or_none()
+
+    def delete(self, snapshot_id: int) -> None:
+        stmt = select(ScenarioProfitability).where(
+            ScenarioProfitability.id == snapshot_id
+        )
+        entity = self.session.execute(stmt).scalar_one_or_none()
+        if entity is None:
+            raise EntityNotFoundError(
+                f"Scenario profitability snapshot {snapshot_id} not found"
+            )
+        self.session.delete(entity)
+
+
+class ProjectCapexRepository:
+    """Persistence operations for project-level capex snapshots."""
+
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def create(self, snapshot: ProjectCapexSnapshot) -> ProjectCapexSnapshot:
+        self.session.add(snapshot)
+        self.session.flush()
+        return snapshot
+
+    def list_for_project(
+        self,
+        project_id: int,
+        *,
+        limit: int | None = None,
+    ) -> Sequence[ProjectCapexSnapshot]:
+        stmt = (
+            select(ProjectCapexSnapshot)
+            .where(ProjectCapexSnapshot.project_id == project_id)
+            .order_by(ProjectCapexSnapshot.calculated_at.desc())
+        )
+        if limit is not None:
+            stmt = stmt.limit(limit)
+        return self.session.execute(stmt).scalars().all()
+
+    def latest_for_project(
+        self,
+        project_id: int,
+    ) -> ProjectCapexSnapshot | None:
+        stmt = (
+            select(ProjectCapexSnapshot)
+            .where(ProjectCapexSnapshot.project_id == project_id)
+            .order_by(ProjectCapexSnapshot.calculated_at.desc())
+            .limit(1)
+        )
+        return self.session.execute(stmt).scalar_one_or_none()
+
+    def delete(self, snapshot_id: int) -> None:
+        stmt = select(ProjectCapexSnapshot).where(
+            ProjectCapexSnapshot.id == snapshot_id
+        )
+        entity = self.session.execute(stmt).scalar_one_or_none()
+        if entity is None:
+            raise EntityNotFoundError(
+                f"Project capex snapshot {snapshot_id} not found"
+            )
+        self.session.delete(entity)
+
+
+class ScenarioCapexRepository:
+    """Persistence operations for scenario-level capex snapshots."""
+
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def create(self, snapshot: ScenarioCapexSnapshot) -> ScenarioCapexSnapshot:
+        self.session.add(snapshot)
+        self.session.flush()
+        return snapshot
+
+    def list_for_scenario(
+        self,
+        scenario_id: int,
+        *,
+        limit: int | None = None,
+    ) -> Sequence[ScenarioCapexSnapshot]:
+        stmt = (
+            select(ScenarioCapexSnapshot)
+            .where(ScenarioCapexSnapshot.scenario_id == scenario_id)
+            .order_by(ScenarioCapexSnapshot.calculated_at.desc())
+        )
+        if limit is not None:
+            stmt = stmt.limit(limit)
+        return self.session.execute(stmt).scalars().all()
+
+    def latest_for_scenario(
+        self,
+        scenario_id: int,
+    ) -> ScenarioCapexSnapshot | None:
+        stmt = (
+            select(ScenarioCapexSnapshot)
+            .where(ScenarioCapexSnapshot.scenario_id == scenario_id)
+            .order_by(ScenarioCapexSnapshot.calculated_at.desc())
+            .limit(1)
+        )
+        return self.session.execute(stmt).scalar_one_or_none()
+
+    def delete(self, snapshot_id: int) -> None:
+        stmt = select(ScenarioCapexSnapshot).where(
+            ScenarioCapexSnapshot.id == snapshot_id
+        )
+        entity = self.session.execute(stmt).scalar_one_or_none()
+        if entity is None:
+            raise EntityNotFoundError(
+                f"Scenario capex snapshot {snapshot_id} not found"
+            )
+        self.session.delete(entity)
+
+
+class ProjectOpexRepository:
+    """Persistence operations for project-level opex snapshots."""
+
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def create(
+        self, snapshot: ProjectOpexSnapshot
+    ) -> ProjectOpexSnapshot:
+        self.session.add(snapshot)
+        self.session.flush()
+        return snapshot
+
+    def list_for_project(
+        self,
+        project_id: int,
+        *,
+        limit: int | None = None,
+    ) -> Sequence[ProjectOpexSnapshot]:
+        stmt = (
+            select(ProjectOpexSnapshot)
+            .where(ProjectOpexSnapshot.project_id == project_id)
+            .order_by(ProjectOpexSnapshot.calculated_at.desc())
+        )
+        if limit is not None:
+            stmt = stmt.limit(limit)
+        return self.session.execute(stmt).scalars().all()
+
+    def latest_for_project(
+        self,
+        project_id: int,
+    ) -> ProjectOpexSnapshot | None:
+        stmt = (
+            select(ProjectOpexSnapshot)
+            .where(ProjectOpexSnapshot.project_id == project_id)
+            .order_by(ProjectOpexSnapshot.calculated_at.desc())
+            .limit(1)
+        )
+        return self.session.execute(stmt).scalar_one_or_none()
+
+    def delete(self, snapshot_id: int) -> None:
+        stmt = select(ProjectOpexSnapshot).where(
+            ProjectOpexSnapshot.id == snapshot_id
+        )
+        entity = self.session.execute(stmt).scalar_one_or_none()
+        if entity is None:
+            raise EntityNotFoundError(
+                f"Project opex snapshot {snapshot_id} not found"
+            )
+        self.session.delete(entity)
+
+
+class ScenarioOpexRepository:
+    """Persistence operations for scenario-level opex snapshots."""
+
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def create(
+        self, snapshot: ScenarioOpexSnapshot
+    ) -> ScenarioOpexSnapshot:
+        self.session.add(snapshot)
+        self.session.flush()
+        return snapshot
+
+    def list_for_scenario(
+        self,
+        scenario_id: int,
+        *,
+        limit: int | None = None,
+    ) -> Sequence[ScenarioOpexSnapshot]:
+        stmt = (
+            select(ScenarioOpexSnapshot)
+            .where(ScenarioOpexSnapshot.scenario_id == scenario_id)
+            .order_by(ScenarioOpexSnapshot.calculated_at.desc())
+        )
+        if limit is not None:
+            stmt = stmt.limit(limit)
+        return self.session.execute(stmt).scalars().all()
+
+    def latest_for_scenario(
+        self,
+        scenario_id: int,
+    ) -> ScenarioOpexSnapshot | None:
+        stmt = (
+            select(ScenarioOpexSnapshot)
+            .where(ScenarioOpexSnapshot.scenario_id == scenario_id)
+            .order_by(ScenarioOpexSnapshot.calculated_at.desc())
+            .limit(1)
+        )
+        return self.session.execute(stmt).scalar_one_or_none()
+
+    def delete(self, snapshot_id: int) -> None:
+        stmt = select(ScenarioOpexSnapshot).where(
+            ScenarioOpexSnapshot.id == snapshot_id
+        )
+        entity = self.session.execute(stmt).scalar_one_or_none()
+        if entity is None:
+            raise EntityNotFoundError(
+                f"Scenario opex snapshot {snapshot_id} not found"
+            )
+        self.session.delete(entity)
+
+
 class FinancialInputRepository:
     """Persistence operations for FinancialInput entities."""
 

services/scenario_evaluation.py

@@ -1,9 +1,9 @@
-from __future__ import annotations
-
 """Scenario evaluation services including pricing integration."""
 
+from __future__ import annotations
+
 from dataclasses import dataclass
-from typing import Iterable, Mapping
+from typing import Iterable
 
 from models.scenario import Scenario
 from services.pricing import (

services/security.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 from datetime import datetime, timedelta, timezone
+from hmac import compare_digest
 from typing import Any, Dict, Iterable, Literal, Type
 
 from jose import ExpiredSignatureError, JWTError, jwt
@@ -176,6 +177,14 @@ def _decode_token(
     except JWTError as exc:  # pragma: no cover - jose error bubble
         raise TokenDecodeError("Unable to decode token") from exc
 
+    expected_token = jwt.encode(
+        decoded,
+        settings.secret_key,
+        algorithm=settings.algorithm,
+    )
+    if not compare_digest(token, expected_token):
+        raise TokenDecodeError("Token contents have been altered.")
+
     try:
         payload = _model_validate(TokenPayload, decoded)
     except ValidationError as exc:

services/session.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Literal, Optional, TYPE_CHECKING
+from typing import Iterable, Literal, Optional, TYPE_CHECKING
 
 from fastapi import Request, Response
 
@@ -67,6 +67,7 @@ class AuthSession:
     tokens: SessionTokens
     user: Optional["User"] = None
     scopes: tuple[str, ...] = ()
+    role_slugs: tuple[str, ...] = ()
     issued_access_token: Optional[str] = None
     issued_refresh_token: Optional[str] = None
     clear_cookies: bool = False
@@ -77,7 +78,10 @@ class AuthSession:
 
     @classmethod
     def anonymous(cls) -> "AuthSession":
-        return cls(tokens=SessionTokens(access_token=None, refresh_token=None))
+        return cls(
+            tokens=SessionTokens(access_token=None, refresh_token=None),
+            role_slugs=(),
+        )
 
     def issue_tokens(
         self,
@@ -100,6 +104,10 @@ class AuthSession:
         self.tokens = SessionTokens(access_token=None, refresh_token=None)
         self.user = None
         self.scopes = ()
+        self.role_slugs = ()
+
+    def set_role_slugs(self, roles: Iterable[str]) -> None:
+        self.role_slugs = tuple(dict.fromkeys(role.strip().lower() for role in roles if role))
 
 
 def extract_session_tokens(request: Request, strategy: SessionStrategy) -> SessionTokens:

services/simulation.py

@@ -2,7 +2,8 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from enum import Enum
-from typing import Any, Dict, Iterable, Mapping, Sequence
+from typing import Any, Dict, Mapping, Sequence
+import time
 
 import numpy as np
 from numpy.random import Generator, default_rng
@@ -15,6 +16,7 @@ from .financial import (
     net_present_value,
     payback_period,
 )
+from monitoring.metrics import observe_simulation
 
 
 class DistributionConfigError(ValueError):
@@ -120,60 +122,79 @@ def run_monte_carlo(
         if pct < 0.0 or pct > 100.0:
             raise ValueError("percentiles must be within [0, 100]")
 
-    generator = rng or default_rng(config.seed)
+    start_time = time.time()
+    try:
+        generator = rng or default_rng(config.seed)
 
-    metric_arrays: Dict[SimulationMetric, np.ndarray] = {
-        metric: np.empty(config.iterations, dtype=float)
-        for metric in config.metrics
-    }
+        metric_arrays: Dict[SimulationMetric, np.ndarray] = {
+            metric: np.empty(config.iterations, dtype=float)
+            for metric in config.metrics
+        }
 
-    for idx in range(config.iterations):
-        iteration_flows = [
-            _realise_cash_flow(
-                spec,
-                generator,
-                scenario_context=scenario_context,
-                metadata=metadata,
-            )
-            for spec in cash_flows
-        ]
+        for idx in range(config.iterations):
+            iteration_flows = [
+                _realise_cash_flow(
+                    spec,
+                    generator,
+                    scenario_context=scenario_context,
+                    metadata=metadata,
+                )
+                for spec in cash_flows
+            ]
 
-        if SimulationMetric.NPV in metric_arrays:
-            metric_arrays[SimulationMetric.NPV][idx] = net_present_value(
-                config.discount_rate,
-                iteration_flows,
-                residual_value=config.residual_value,
-                residual_periods=config.residual_periods,
-                compounds_per_year=config.compounds_per_year,
-            )
-        if SimulationMetric.IRR in metric_arrays:
-            try:
-                metric_arrays[SimulationMetric.IRR][idx] = internal_rate_of_return(
+            if SimulationMetric.NPV in metric_arrays:
+                metric_arrays[SimulationMetric.NPV][idx] = net_present_value(
+                    config.discount_rate,
                     iteration_flows,
+                    residual_value=config.residual_value,
+                    residual_periods=config.residual_periods,
                     compounds_per_year=config.compounds_per_year,
                 )
-            except (ValueError, ConvergenceError):
-                metric_arrays[SimulationMetric.IRR][idx] = np.nan
-        if SimulationMetric.PAYBACK in metric_arrays:
-            try:
-                metric_arrays[SimulationMetric.PAYBACK][idx] = payback_period(
-                    iteration_flows,
-                    compounds_per_year=config.compounds_per_year,
-                )
-            except (ValueError, PaybackNotReachedError):
-                metric_arrays[SimulationMetric.PAYBACK][idx] = np.nan
+            if SimulationMetric.IRR in metric_arrays:
+                try:
+                    metric_arrays[SimulationMetric.IRR][idx] = internal_rate_of_return(
+                        iteration_flows,
+                        compounds_per_year=config.compounds_per_year,
+                    )
+                except (ValueError, ConvergenceError):
+                    metric_arrays[SimulationMetric.IRR][idx] = np.nan
+            if SimulationMetric.PAYBACK in metric_arrays:
+                try:
+                    metric_arrays[SimulationMetric.PAYBACK][idx] = payback_period(
+                        iteration_flows,
+                        compounds_per_year=config.compounds_per_year,
+                    )
+                except (ValueError, PaybackNotReachedError):
+                    metric_arrays[SimulationMetric.PAYBACK][idx] = np.nan
 
-    summaries = {
-        metric: _summarise(metric_arrays[metric], config.percentiles)
-        for metric in metric_arrays
-    }
+        summaries = {
+            metric: _summarise(metric_arrays[metric], config.percentiles)
+            for metric in metric_arrays
+        }
 
-    samples = metric_arrays if config.return_samples else None
-    return SimulationResult(
-        iterations=config.iterations,
-        summaries=summaries,
-        samples=samples,
-    )
+        samples = metric_arrays if config.return_samples else None
+        result = SimulationResult(
+            iterations=config.iterations,
+            summaries=summaries,
+            samples=samples,
+        )
+
+        # Record successful simulation
+        duration = time.time() - start_time
+        observe_simulation(
+            status="success",
+            duration_seconds=duration,
+        )
+        return result
+
+    except Exception:
+        # Record failed simulation
+        duration = time.time() - start_time
+        observe_simulation(
+            status="error",
+            duration_seconds=duration,
+        )
+        raise
 
 
 def _realise_cash_flow(

services/unit_of_work.py

@@ -13,14 +13,21 @@ from services.repositories import (
     PricingSettingsRepository,
     PricingSettingsSeedResult,
     ProjectRepository,
+    ProjectProfitabilityRepository,
+    ProjectOpexRepository,
+    ProjectCapexRepository,
     RoleRepository,
     ScenarioRepository,
+    ScenarioProfitabilityRepository,
+    ScenarioOpexRepository,
+    ScenarioCapexRepository,
     SimulationParameterRepository,
     UserRepository,
     ensure_admin_user as ensure_admin_user_record,
     ensure_default_pricing_settings,
     ensure_default_roles,
     pricing_settings_to_metadata,
+    NavigationRepository,
 )
 from services.scenario_validation import ScenarioComparisonValidator
 
@@ -36,9 +43,16 @@ class UnitOfWork(AbstractContextManager["UnitOfWork"]):
         self.scenarios: ScenarioRepository | None = None
         self.financial_inputs: FinancialInputRepository | None = None
         self.simulation_parameters: SimulationParameterRepository | None = None
+        self.project_profitability: ProjectProfitabilityRepository | None = None
+        self.project_capex: ProjectCapexRepository | None = None
+        self.project_opex: ProjectOpexRepository | None = None
+        self.scenario_profitability: ScenarioProfitabilityRepository | None = None
+        self.scenario_capex: ScenarioCapexRepository | None = None
+        self.scenario_opex: ScenarioOpexRepository | None = None
         self.users: UserRepository | None = None
         self.roles: RoleRepository | None = None
         self.pricing_settings: PricingSettingsRepository | None = None
+        self.navigation: NavigationRepository | None = None
 
     def __enter__(self) -> "UnitOfWork":
         self.session = self._session_factory()
@@ -47,9 +61,21 @@ class UnitOfWork(AbstractContextManager["UnitOfWork"]):
         self.financial_inputs = FinancialInputRepository(self.session)
         self.simulation_parameters = SimulationParameterRepository(
             self.session)
+        self.project_profitability = ProjectProfitabilityRepository(
+            self.session)
+        self.project_capex = ProjectCapexRepository(self.session)
+        self.project_opex = ProjectOpexRepository(
+            self.session)
+        self.scenario_profitability = ScenarioProfitabilityRepository(
+            self.session
+        )
+        self.scenario_capex = ScenarioCapexRepository(self.session)
+        self.scenario_opex = ScenarioOpexRepository(
+            self.session)
         self.users = UserRepository(self.session)
         self.roles = RoleRepository(self.session)
         self.pricing_settings = PricingSettingsRepository(self.session)
+        self.navigation = NavigationRepository(self.session)
         self._scenario_validator = ScenarioComparisonValidator()
         return self
 
@@ -65,9 +91,16 @@ class UnitOfWork(AbstractContextManager["UnitOfWork"]):
         self.scenarios = None
         self.financial_inputs = None
         self.simulation_parameters = None
+        self.project_profitability = None
+        self.project_capex = None
+        self.project_opex = None
+        self.scenario_profitability = None
+        self.scenario_capex = None
+        self.scenario_opex = None
         self.users = None
         self.roles = None
         self.pricing_settings = None
+        self.navigation = None
 
     def flush(self) -> None:
         if not self.session:

static/css/dashboard.css

@@ -2,17 +2,6 @@
   --dashboard-gap: 1.5rem;
 }
 
-.dashboard-header {
-  align-items: center;
-}
-
-.header-actions {
-  display: flex;
-  gap: 0.75rem;
-  flex-wrap: wrap;
-  justify-content: flex-end;
-}
-
 .dashboard-metrics {
   display: grid;
   gap: var(--dashboard-gap);
@@ -20,36 +9,6 @@
   margin-bottom: 2rem;
 }
 
-.metric-card {
-  background: var(--card);
-  border-radius: var(--radius);
-  padding: 1.5rem;
-  box-shadow: var(--shadow);
-  border: 1px solid var(--color-border);
-  display: flex;
-  flex-direction: column;
-  gap: 0.35rem;
-}
-
-.metric-card h2 {
-  margin: 0;
-  font-size: 1rem;
-  color: var(--muted);
-  text-transform: uppercase;
-  letter-spacing: 0.08em;
-}
-
-.metric-value {
-  font-size: 2rem;
-  font-weight: 700;
-  margin: 0;
-}
-
-.metric-caption {
-  color: var(--color-text-subtle);
-  font-size: 0.85rem;
-}
-
 .dashboard-grid {
   display: grid;
   gap: var(--dashboard-gap);
@@ -67,16 +26,6 @@
   gap: var(--dashboard-gap);
 }
 
-.table-link {
-  color: var(--brand-2);
-  text-decoration: none;
-}
-
-.table-link:hover,
-.table-link:focus {
-  text-decoration: underline;
-}
-
 .timeline {
   list-style: none;
   margin: 0;
@@ -107,7 +56,9 @@
   padding: 0.75rem;
   border-radius: var(--radius-sm);
   background: rgba(209, 75, 75, 0.16);
+  background: color-mix(in srgb, var(--color-danger) 16%, transparent);
   border: 1px solid rgba(209, 75, 75, 0.3);
+  border: 1px solid color-mix(in srgb, var(--color-danger) 30%, transparent);
 }
 
 .links-list a {
@@ -128,23 +79,4 @@
   .grid-sidebar {
     grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
   }
-
-  .header-actions {
-    justify-content: flex-start;
-  }
-}
-
-@media (max-width: 640px) {
-  .metric-card {
-    padding: 1.25rem;
-  }
-
-  .metric-value {
-    font-size: 1.75rem;
-  }
-
-  .header-actions {
-    flex-direction: column;
-    align-items: stretch;
-  }
 }

static/css/forms.css

@@ -0,0 +1,111 @@
+.form {
+	display: flex;
+	flex-direction: column;
+	gap: 1.25rem;
+}
+
+.form-grid {
+	display: grid;
+	grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+	gap: 1.25rem;
+}
+
+.form-group {
+	display: flex;
+	flex-direction: column;
+	gap: 0.5rem;
+}
+
+.form-group label {
+	font-weight: 600;
+	color: var(--text);
+	color: var(--color-text-primary);
+}
+
+.form-group input,
+.form-group select,
+.form-group textarea {
+	padding: 0.75rem 0.85rem;
+	border-radius: var(--radius-sm);
+	border: 1px solid var(--card-border);
+	background: rgba(8, 12, 19, 0.78);
+	background: color-mix(in srgb, var(--color-bg-elevated) 78%, transparent);
+	color: var(--text);
+	color: var(--color-text-primary);
+	transition: border-color 0.15s ease, background 0.2s ease,
+		box-shadow 0.2s ease;
+}
+
+.form-group textarea {
+	resize: vertical;
+	min-height: 120px;
+}
+
+.form-group input:focus,
+.form-group select:focus,
+.form-group textarea:focus {
+	outline: 2px solid var(--brand-2);
+	outline: 2px solid var(--color-brand-bright);
+	outline-offset: 1px;
+}
+
+.form-group input:disabled,
+.form-group select:disabled,
+.form-group textarea:disabled {
+	cursor: not-allowed;
+	opacity: 0.6;
+}
+
+.form-group--error input,
+.form-group--error select,
+.form-group--error textarea {
+	border-color: rgba(209, 75, 75, 0.6);
+	border-color: color-mix(in srgb, var(--color-danger) 60%, transparent);
+	box-shadow: 0 0 0 1px rgba(209, 75, 75, 0.3);
+	box-shadow: 0 0 0 1px color-mix(in srgb, var(--color-danger) 30%, transparent);
+}
+
+.field-help {
+	margin: 0;
+	font-size: 0.85rem;
+	color: var(--color-text-subtle);
+}
+
+.field-error {
+	margin: 0;
+	font-size: 0.85rem;
+	color: var(--danger);
+	color: var(--color-danger);
+}
+
+.form-actions {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 0.75rem;
+	justify-content: flex-end;
+}
+
+.form-fieldset {
+	border: 1px solid var(--color-border);
+	border-radius: var(--radius);
+	background: rgba(21, 27, 35, 0.85);
+	background: var(--color-surface-overlay);
+	box-shadow: var(--shadow);
+	padding: 1.5rem;
+	display: flex;
+	flex-direction: column;
+	gap: 1.25rem;
+}
+
+.form-fieldset legend {
+	font-weight: 700;
+	padding: 0 0.5rem;
+	color: var(--text);
+	color: var(--color-text-primary);
+}
+
+@media (max-width: 640px) {
+	.form-actions {
+		justify-content: stretch;
+	}
+}

static/css/imports.css

@@ -1,7 +1,8 @@
 .import-upload {
-  background-color: var(--surface-color);
-  border: 1px dashed var(--border-color);
-  border-radius: var(--radius-md);
+  background-color: rgba(21, 27, 35, 0.85);
+  background-color: var(--color-surface-overlay);
+  border: 1px dashed var(--color-border);
+  border-radius: var(--radius);
   padding: 1.5rem;
   margin-bottom: 1.5rem;
 }
@@ -11,7 +12,7 @@
 }
 
 .import-upload__dropzone {
-  border: 2px dashed var(--border-color);
+  border: 2px dashed var(--color-border);
   border-radius: var(--radius-sm);
   padding: 2rem;
   text-align: center;
@@ -19,8 +20,10 @@
 }
 
 .import-upload__dropzone.dragover {
-  border-color: var(--primary-color);
-  background-color: rgba(0, 123, 255, 0.05);
+  border-color: #f6c648;
+  border-color: var(--color-brand-bright);
+  background-color: rgba(241, 178, 26, 0.08);
+  background-color: var(--color-highlight);
 }
 
 .import-upload__actions {
@@ -35,18 +38,6 @@
   gap: 0.5rem;
 }
 
-.btn-ghost {
-  background: transparent;
-  border: none;
-  cursor: pointer;
-  padding: 0.25rem 0.5rem;
-  color: var(--text-muted);
-}
-
-.btn-ghost:hover {
-  color: var(--primary-color);
-}
-
 .toast {
   position: fixed;
   right: 1rem;
@@ -55,9 +46,9 @@
   align-items: center;
   gap: 0.75rem;
   padding: 1rem 1.25rem;
-  border-radius: var(--radius-md);
-  color: #fff;
-  box-shadow: var(--shadow-lg);
+  border-radius: var(--radius);
+  color: var(--color-text-invert);
+  box-shadow: var(--shadow);
   z-index: 1000;
 }
 
@@ -66,15 +57,18 @@
 }
 
 .toast--success {
-  background-color: #198754;
+  background-color: var(--success);
+  background-color: var(--color-success);
 }
 
 .toast--error {
-  background-color: #dc3545;
+  background-color: var(--danger);
+  background-color: var(--color-danger);
 }
 
 .toast--info {
-  background-color: #0d6efd;
+  background-color: var(--info);
+  background-color: var(--color-info);
 }
 
 .toast__close {

static/css/main.css

@@ -1,3 +1,80 @@
+:root {
+  /* Radii & layout */
+  --radius: 14px;
+  --radius-sm: 10px;
+  --panel-radius: var(--radius);
+  --table-radius: var(--radius-sm);
+  --container: 1180px;
+
+  /* Spacing & typography */
+  --space-2xs: 0.25rem;
+  --space-xs: 0.5rem;
+  --space-sm: 0.75rem;
+  --space-md: 1rem;
+  --space-lg: 1.5rem;
+  --space-xl: 2rem;
+  --space-2xl: 3rem;
+
+  --font-size-xs: 0.75rem;
+  --font-size-sm: 0.875rem;
+  --font-size-base: 1rem;
+  --font-size-lg: 1.25rem;
+  --font-size-xl: 1.5rem;
+  --font-size-2xl: 2rem;
+}
+
+html,
+body {
+  height: 100%;
+}
+
+body {
+  margin: 0;
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", "Roboto",
+    Helvetica, Arial, "Apple Color Emoji", "Segoe UI Emoji";
+  color: var(--text);
+  background: linear-gradient(180deg, var(--bg) 0%, var(--bg-2) 100%);
+  line-height: 1.45;
+}
+
+.header-actions {
+  display: flex;
+  gap: 0.75rem;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  margin: 0 0 0.5rem 0;
+  font-weight: 700;
+  line-height: 1.2;
+}
+
+h1 {
+  font-size: var(--font-size-2xl);
+}
+
+h2 {
+  font-size: var(--font-size-xl);
+}
+
+h3 {
+  font-size: var(--font-size-lg);
+}
+
+p {
+  margin: 0 0 1rem 0;
+}
+
+a {
+  color: var(--brand);
+}
+
 .report-overview {
   margin-bottom: 2.5rem;
 }
@@ -25,6 +102,16 @@
   margin-top: 3rem;
 }
 
+.chart-container {
+  width: 100%;
+  height: 400px;
+  background: rgba(15, 20, 27, 0.8);
+  border-radius: var(--radius-sm);
+  border: 1px solid rgba(255, 255, 255, 0.05);
+  box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.06);
+  margin-bottom: 1rem;
+}
+
 .section-header {
   margin-bottom: 1.25rem;
 }
@@ -64,6 +151,36 @@
   color: var(--text);
 }
 
+.metric-card {
+  background: var(--color-surface-overlay);
+  border-radius: var(--radius);
+  padding: 1.5rem;
+  box-shadow: var(--shadow);
+  border: 1px solid var(--color-border);
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+
+.metric-card h2 {
+  margin: 0;
+  font-size: 1rem;
+  color: var(--color-text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.metric-value {
+  font-size: 2rem;
+  font-weight: 700;
+  margin: 0;
+}
+
+.metric-caption {
+  color: var(--color-text-subtle);
+  font-size: 0.85rem;
+}
+
 .metrics-table {
   width: 100%;
   border-collapse: collapse;
@@ -81,7 +198,7 @@
 
 .metrics-table th {
   font-weight: 600;
-  color: var(--text);
+  color: var(--color-text-dark);
 }
 
 .metrics-table tr:last-child td,
@@ -92,23 +209,30 @@
 .definition-list {
   margin: 0;
   display: grid;
-  gap: 0.75rem;
+  gap: 1.25rem 2rem;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
 }
 
 .definition-list div {
   display: grid;
-  grid-template-columns: 140px 1fr;
+  grid-template-columns: minmax(140px, 0.6fr) minmax(0, 1fr);
   gap: 0.5rem;
   align-items: baseline;
 }
 
 .definition-list dt {
-  color: var(--muted);
+  margin: 0;
   font-weight: 600;
+  color: var(--color-text-muted);
+  text-transform: uppercase;
+  font-size: 0.75rem;
+  letter-spacing: 0.08em;
 }
 
 .definition-list dd {
   margin: 0;
+  font-size: 1rem;
+  color: var(--color-text-primary);
 }
 
 .scenario-card {
@@ -138,6 +262,13 @@
 }
 
 .scenario-meta {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+  gap: 1.25rem;
+}
+
+.scenario-card .scenario-meta {
+  display: block;
   text-align: right;
 }
 
@@ -183,6 +314,201 @@
   color: var(--muted);
 }
 
+.quick-link-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.quick-link-list li a {
+  font-weight: 600;
+  color: var(--brand-2);
+  text-decoration: none;
+}
+
+.quick-link-list li a:hover,
+.quick-link-list li a:focus {
+  text-decoration: underline;
+}
+
+.quick-link-list p {
+  margin: 0.25rem 0 0;
+  color: var(--color-text-subtle);
+  font-size: 0.9rem;
+}
+
+.scenario-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.scenario-item {
+  background: rgba(21, 27, 35, 0.85);
+  background: color-mix(in srgb, var(--color-surface-default) 85%, transparent);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius);
+  padding: 1.25rem;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.scenario-item__body {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.scenario-item__header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.75rem;
+  justify-content: space-between;
+}
+
+.scenario-item__header h3 {
+  margin: 0;
+  font-size: 1.1rem;
+}
+
+.scenario-item__header a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.scenario-item__header a:hover,
+.scenario-item__header a:focus {
+  text-decoration: underline;
+}
+
+.scenario-item__meta {
+  display: grid;
+  gap: 0.75rem;
+  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+}
+
+.scenario-item__meta dt {
+  margin: 0;
+  font-size: 0.75rem;
+  color: var(--color-text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.scenario-item__meta dd {
+  margin: 0;
+  font-size: 0.95rem;
+}
+
+.scenario-item__actions {
+  display: flex;
+  gap: 0.75rem;
+  flex-wrap: wrap;
+}
+
+.scenario-item__actions .btn--link {
+  padding: 0;
+}
+
+.status-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  padding: 0.35rem 0.85rem;
+  border-radius: 999px;
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.status-pill--draft {
+  background: rgba(59, 130, 246, 0.15);
+  color: #93c5fd;
+  background: color-mix(in srgb, var(--color-info) 18%, transparent);
+  color: color-mix(in srgb, var(--color-info) 70%, white);
+}
+
+.status-pill--active {
+  background: rgba(34, 197, 94, 0.18);
+  color: #86efac;
+  background: color-mix(in srgb, var(--color-success) 18%, transparent);
+  color: color-mix(in srgb, var(--color-success) 70%, white);
+}
+
+.status-pill--archived {
+  background: rgba(148, 163, 184, 0.24);
+  color: #cbd5f5;
+  background: color-mix(in srgb, var(--color-text-muted) 24%, transparent);
+  color: color-mix(in srgb, var(--color-text-muted) 60%, white);
+}
+
+.empty-state {
+  color: var(--color-text-muted);
+  font-style: italic;
+}
+
+.table {
+  width: 100%;
+  border-collapse: collapse;
+  border-radius: var(--table-radius);
+  overflow: hidden;
+  box-shadow: var(--shadow);
+}
+
+.table th,
+.table td {
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid var(--color-border);
+  background: rgba(21, 27, 35, 0.85);
+  background: color-mix(in srgb, var(--color-surface-default) 85%, transparent);
+}
+
+.table tbody tr:hover {
+  background: rgba(241, 178, 26, 0.12);
+  background: var(--color-highlight);
+}
+
+.table-link {
+  color: var(--brand-2);
+  text-decoration: none;
+  margin-left: 0.5rem;
+}
+
+.table-link:hover,
+.table-link:focus {
+  text-decoration: underline;
+}
+
+.table-responsive {
+  width: 100%;
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+  border-radius: var(--table-radius);
+  margin: 0;
+}
+
+.table-responsive .table {
+  min-width: 640px;
+}
+
+.table-responsive::-webkit-scrollbar {
+  height: 6px;
+}
+
+.table-responsive::-webkit-scrollbar-thumb {
+  background: rgba(255, 255, 255, 0.2);
+  background: color-mix(in srgb, var(--color-text-invert) 20%, transparent);
+  border-radius: 999px;
+}
+
 .page-actions .button {
   text-decoration: none;
   background: transparent;
@@ -199,69 +525,25 @@
   background: rgba(241, 178, 26, 0.14);
   border-color: var(--brand);
 }
-:root {
-  --bg: #0b0f14;
-  --bg-2: #0f141b;
-  --card: #151b23;
-  --text: #e6edf3;
-  --muted: #a9b4c0;
-  --brand: #f1b21a;
-  --brand-2: #f6c648;
-  --brand-3: #f9d475;
-  --accent: #2ba58f;
-  --danger: #d14b4b;
-  --shadow: 0 10px 30px rgba(0, 0, 0, 0.35);
-  --radius: 14px;
-  --radius-sm: 10px;
-  --container: 1180px;
-  --muted: var(--muted);
-  --color-text-subtle: rgba(169, 180, 192, 0.6);
-  --color-text-invert: #ffffff;
-  --color-text-dark: #0f172a;
-  --color-text-strong: #111827;
-  --color-border: rgba(255, 255, 255, 0.08);
-  --color-border-strong: rgba(255, 255, 255, 0.12);
-  --color-highlight: rgba(241, 178, 26, 0.08);
-  --color-panel-shadow: rgba(0, 0, 0, 0.25);
-  --color-panel-shadow-deep: rgba(0, 0, 0, 0.35);
-  --color-surface-alt: rgba(21, 27, 35, 0.7);
-  --space-2xs: 0.25rem;
-  --space-xs: 0.5rem;
-  --space-sm: 0.75rem;
-  --space-md: 1rem;
-  --space-lg: 1.5rem;
-  --space-xl: 2rem;
-  --space-2xl: 3rem;
-  --font-size-xs: 0.75rem;
-  --font-size-sm: 0.875rem;
-  --font-size-base: 1rem;
-  --font-size-lg: 1.25rem;
-  --font-size-xl: 1.5rem;
-  --font-size-2xl: 2rem;
-  --panel-radius: var(--radius);
-  --table-radius: var(--radius-sm);
+
+.breadcrumb {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.9rem;
+  color: var(--muted);
+  margin-bottom: 1.2rem;
 }
 
-* {
-  box-sizing: border-box;
+.breadcrumb a {
+  color: var(--brand-2);
+  text-decoration: none;
 }
 
-html,
-body {
-  height: 100%;
-}
-
-body {
-  margin: 0;
-  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", "Roboto",
-    Helvetica, Arial, "Apple Color Emoji", "Segoe UI Emoji";
-  color: var(--text);
-  background: linear-gradient(180deg, var(--bg) 0%, var(--bg-2) 100%);
-  line-height: 1.45;
-}
-
-a {
-  color: var(--brand);
+.breadcrumb a::after {
+  content: ">";
+  margin-left: 0.5rem;
+  color: var(--muted);
 }
 
 .app-layout {
@@ -294,20 +576,58 @@ a {
   display: flex;
   align-items: center;
   gap: 1rem;
+  padding: 0.5rem 1rem;
+  border-radius: 0.75rem;
+}
+a.sidebar-brand {
+  text-decoration: none;
+}
+a.sidebar-brand:hover,
+a.sidebar-brand:focus {
+  color: var(--color-text-invert);
+  background-color: rgba(148, 197, 255, 0.18);
+}
+
+.sidebar-nav-controls {
+  display: flex;
+  justify-content: center;
+  gap: 1rem;
+  margin: 0;
+}
+
+.nav-chevron {
+  width: 5rem;
+  height: 5rem;
+  border: none;
+  background: rgba(0, 0, 0, 0.5);
+  color: rgba(255, 255, 255, 0.88);
+  font-size: 4.5rem;
+  font-weight: bold;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: background 0.2s ease, transform 0.2s ease;
+}
+
+.nav-chevron:hover,
+.nav-chevron:focus {
+  background: rgba(0, 0, 0, 0.1);
+  color: rgba(255, 255, 255, 1);
+  transform: scale(0.9);
+}
+
+.nav-chevron:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  transform: none;
 }
 
 .brand-logo {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
   width: 44px;
   height: 44px;
   border-radius: 12px;
-  background: linear-gradient(0deg, var(--brand-3), var(--accent));
-  color: var(--color-text-invert);
-  font-weight: 700;
-  font-size: 1.1rem;
-  letter-spacing: 1px;
+  object-fit: cover;
 }
 
 .brand-text {
@@ -449,7 +769,7 @@ a {
 
 .dashboard-header {
   display: flex;
-  align-items: flex-start;
+  align-items: center;
   justify-content: space-between;
   gap: 1.5rem;
   margin-bottom: 2rem;
@@ -791,36 +1111,6 @@ a {
   font-size: var(--font-size-lg);
 }
 
-.form-grid {
-  display: grid;
-  gap: var(--space-md);
-  max-width: 480px;
-}
-
-.form-grid label {
-  display: flex;
-  flex-direction: column;
-  gap: var(--space-sm);
-  font-weight: 600;
-  color: var(--text);
-}
-
-.form-grid input,
-.form-grid textarea,
-.form-grid select {
-  padding: 0.6rem var(--space-sm);
-  border: 1px solid var(--color-border-strong);
-  border-radius: 8px;
-  font-size: var(--font-size-base);
-}
-
-.form-grid input:focus,
-.form-grid textarea:focus,
-.form-grid select:focus {
-  outline: 2px solid var(--brand-2);
-  outline-offset: 1px;
-}
-
 .btn {
   display: inline-flex;
   align-items: center;
@@ -828,28 +1118,101 @@ a {
   gap: 0.5rem;
   padding: 0.65rem 1.25rem;
   border-radius: 999px;
-  border: none;
+  border: 1px solid var(--btn-secondary-border);
   cursor: pointer;
   font-weight: 600;
-  background-color: var(--color-border);
-  color: var(--color-text-dark);
-  transition: transform 0.15s ease, box-shadow 0.15s ease;
+  background-color: var(--btn-secondary-bg);
+  color: var(--btn-secondary-color);
+  text-decoration: none;
+  transition: transform 0.15s ease, box-shadow 0.15s ease,
+    background-color 0.2s ease, border-color 0.2s ease;
 }
 
 .btn:hover,
 .btn:focus {
   transform: translateY(-1px);
   box-shadow: 0 4px 10px var(--color-panel-shadow);
+  background-color: var(--btn-secondary-hover);
 }
 
-.btn.primary {
-  background-color: var(--brand-2);
-  color: var(--color-text-invert);
+.btn--primary,
+.btn.primary,
+.btn.btn-primary {
+  background-color: var(--btn-primary-bg);
+  border-color: transparent;
+  color: var(--btn-primary-color);
 }
 
+.btn--primary:hover,
+.btn--primary:focus,
 .btn.primary:hover,
-.btn.primary:focus {
-  background-color: var(--brand-3);
+.btn.primary:focus,
+.btn.btn-primary:hover,
+.btn.btn-primary:focus {
+  background-color: var(--btn-primary-hover);
+}
+
+.btn--secondary,
+.btn.secondary,
+.btn.btn-secondary {
+  background-color: var(--btn-secondary-bg);
+  border-color: var(--btn-secondary-border);
+  color: var(--btn-secondary-color);
+}
+
+.btn--secondary:hover,
+.btn--secondary:focus,
+.btn.secondary:hover,
+.btn.secondary:focus,
+.btn.btn-secondary:hover,
+.btn.btn-secondary:focus {
+  background-color: var(--btn-secondary-hover);
+}
+
+.btn--link,
+.btn.btn-link,
+.btn.link {
+  padding: 0.25rem 0;
+  border: none;
+  background: transparent;
+  color: var(--btn-link-color);
+  margin: 0;
+  box-shadow: none;
+}
+
+.btn--link:hover,
+.btn--link:focus,
+.btn.btn-link:hover,
+.btn.btn-link:focus,
+.btn.link:hover,
+.btn.link:focus {
+  transform: none;
+  box-shadow: none;
+  color: var(--btn-link-hover);
+  text-decoration: underline;
+}
+
+.btn--ghost {
+  background: transparent;
+  border: 1px solid transparent;
+  color: var(--btn-ghost-color);
+}
+
+.btn--ghost:hover,
+.btn--ghost:focus {
+  background: rgba(255, 255, 255, 0.1);
+  border-color: rgba(255, 255, 255, 0.2);
+}
+
+.btn--icon {
+  padding: 0.4rem;
+  border-radius: 50%;
+  line-height: 0;
+}
+
+.btn--icon:hover,
+.btn--icon:focus {
+  transform: none;
 }
 
 .result-output {
@@ -927,9 +1290,27 @@ tbody tr:nth-child(even) {
   color: var(--danger);
 }
 
+.alert {
+  padding: 0.75rem 1rem;
+  border-radius: var(--radius-sm);
+  margin-bottom: 1rem;
+}
+
+.alert-error {
+  background: rgba(209, 75, 75, 0.2);
+  border: 1px solid rgba(209, 75, 75, 0.4);
+  color: var(--color-text-invert);
+}
+
+.alert-info {
+  background: rgba(43, 168, 143, 0.2);
+  border: 1px solid rgba(43, 168, 143, 0.4);
+  color: var(--color-text-invert);
+}
+
 .site-footer {
   background-color: var(--brand);
-  color: var(--color-text-invert);
+  color: var(--color-text-strong);
   margin-top: 3rem;
 }
 
@@ -939,6 +1320,32 @@ tbody tr:nth-child(even) {
   justify-content: center;
   padding: 1rem 0;
   font-size: 0.9rem;
+  gap: 1rem;
+}
+
+.footer-logo {
+  display: flex;
+  align-items: center;
+}
+
+.footer-logo-img {
+  width: 32px;
+  height: 32px;
+  border-radius: 8px;
+  object-fit: cover;
+}
+
+footer p {
+  margin: 0;
+}
+footer a {
+  font-weight: 600;
+  color: var(--color-text-dark);
+  text-decoration: underline;
+}
+footer a:hover,
+footer a:focus {
+  color: var(--color-text-strong);
 }
 
 .sidebar-toggle {
@@ -1007,10 +1414,62 @@ tbody tr:nth-child(even) {
   transition: opacity 0.25s ease;
 }
 
+@media (min-width: 720px) {
+  .table-responsive .table {
+    min-width: 100%;
+  }
+}
+
+@media (max-width: 640px) {
+  .table th,
+  .table td {
+    padding: 0.55rem 0.65rem;
+    font-size: 0.9rem;
+    white-space: nowrap;
+  }
+
+  .table tbody tr {
+    border-radius: var(--radius-sm);
+  }
+
+  .metric-card {
+    padding: 1.25rem;
+  }
+
+  .metric-value {
+    font-size: 1.75rem;
+  }
+
+  .header-actions {
+    flex-direction: column;
+    align-items: stretch;
+  }
+}
+
+@media (min-width: 960px) {
+  .header-actions {
+    justify-content: flex-start;
+  }
+
+  .scenario-item {
+    flex-direction: row;
+    justify-content: space-between;
+    align-items: center;
+  }
+
+  .scenario-item__body {
+    max-width: 70%;
+  }
+}
+
 @media (max-width: 1024px) {
   .app-sidebar {
     width: 240px;
   }
+
+  .header-actions {
+    justify-content: flex-start;
+  }
 }
 
 @media (max-width: 900px) {
@@ -1040,8 +1499,16 @@ tbody tr:nth-child(even) {
     justify-content: center;
   }
 
+  .sidebar-nav-controls {
+    display: none;
+  }
+
+  .sidebar-link-block {
+    align-items: center;
+  }
+
   .sidebar-link {
-    flex: 1 1 140px;
+    flex: 1 1 40px;
     justify-content: center;
   }
 
@@ -1071,6 +1538,10 @@ tbody tr:nth-child(even) {
     overflow: hidden;
   }
 
+  body.sidebar-open .app-main {
+    position: relative;
+    z-index: 1;
+  }
   body.sidebar-open .app-sidebar {
     display: block;
     position: fixed;
@@ -1079,7 +1550,7 @@ tbody tr:nth-child(even) {
     width: min(320px, 82vw);
     height: 100vh;
     overflow-y: auto;
-    z-index: 900;
+    z-index: 999;
     box-shadow: 0 12px 30px rgba(8, 14, 25, 0.4);
   }
 
@@ -1087,9 +1558,4 @@ tbody tr:nth-child(even) {
     opacity: 1;
     pointer-events: auto;
   }
-
-  body.sidebar-open .app-main {
-    position: relative;
-    z-index: 950;
-  }
 }

static/css/projects.css

@@ -1,14 +1,103 @@
-:root {
-  --card-bg: rgba(21, 27, 35, 0.8);
-  --card-border: rgba(255, 255, 255, 0.08);
-  --hover-highlight: rgba(241, 178, 26, 0.12);
+.projects-grid {
+  display: grid;
+  gap: 1.5rem;
+  grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
+  margin-top: 1.5rem;
 }
 
-.header-actions {
+.project-card {
+  background: var(--color-surface-overlay);
+  border: 1px solid var(--color-border);
+  box-shadow: var(--shadow);
+  border-radius: var(--radius);
+  padding: 1.5rem;
+  display: flex;
+  flex-direction: column;
+  gap: 1.25rem;
+  transition: transform 0.2s ease, box-shadow 0.2s ease;
+}
+
+.project-card:hover,
+.project-card:focus-within {
+  transform: translateY(-2px);
+  box-shadow: 0 22px 45px var(--color-panel-shadow-deep);
+}
+
+.project-card__header {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.project-card__title {
+  margin: 0;
+  font-size: 1.25rem;
+}
+
+.project-card__title a {
+  color: var(--brand);
+  text-decoration: none;
+}
+
+.project-card__title a:hover,
+.project-card__title a:focus {
+  text-decoration: underline;
+}
+
+.project-card__type {
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.project-card__description {
+  margin: 0;
+  color: var(--color-text-subtle);
+  min-height: 3rem;
+}
+
+.project-card__meta {
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+}
+
+.project-card__meta div {
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+
+.project-card__meta dt {
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  color: var(--color-text-muted);
+  letter-spacing: 0.08em;
+}
+
+.project-card__meta dd {
+  margin: 0;
+  font-size: 0.95rem;
+}
+
+.project-card__footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  flex-wrap: wrap;
+}
+
+.project-card__links {
   display: flex;
   gap: 0.75rem;
   flex-wrap: wrap;
-  justify-content: flex-end;
+}
+
+.project-card__links .btn--link {
+  padding: 3px 4px;
+  border-radius: 8px;
 }
 
 .project-metrics {
@@ -18,39 +107,9 @@
   margin-bottom: 2rem;
 }
 
-.metric-card {
-  background: var(--card-bg);
-  border-radius: var(--radius);
-  padding: 1.5rem;
-  box-shadow: var(--shadow);
-  border: 1px solid var(--card-border);
-  display: flex;
-  flex-direction: column;
-  gap: 0.35rem;
-}
-
-.metric-card h2 {
-  margin: 0;
-  font-size: 1rem;
-  color: var(--muted);
-  text-transform: uppercase;
-  letter-spacing: 0.08em;
-}
-
-.metric-value {
-  font-size: 2rem;
-  font-weight: 700;
-  margin: 0;
-}
-
-.metric-caption {
-  color: var(--color-text-subtle);
-  font-size: 0.85rem;
-}
-
 .project-form {
-  background: var(--card-bg);
-  border: 1px solid var(--card-border);
+  background: var(--color-surface-overlay);
+  border: 1px solid var(--color-border);
   border-radius: var(--radius);
   box-shadow: var(--shadow);
   padding: 1.75rem;
@@ -59,34 +118,43 @@
   gap: 1.5rem;
 }
 
-.definition-list {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
-  gap: 1.25rem 2rem;
-}
-
-.definition-list dt {
-  font-weight: 600;
-  color: var(--muted);
-  margin-bottom: 0.2rem;
-  text-transform: uppercase;
-  font-size: 0.75rem;
-}
-
-.definition-list dd {
-  margin: 0;
-  font-size: 1rem;
-}
-
 .card {
-  background: var(--card-bg);
-  border: 1px solid var(--card-border);
+  background: var(--color-surface-overlay);
+  border: 1px solid var(--color-border);
   box-shadow: var(--shadow);
   border-radius: var(--radius);
   padding: 1.5rem;
   margin-bottom: 2rem;
 }
 
+.project-column {
+  display: grid;
+  gap: 1.5rem;
+}
+
+.project-actions-card {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.project-scenarios-card {
+  display: flex;
+  flex-direction: column;
+  gap: 1.5rem;
+}
+
+.project-scenarios-card__header {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.project-scenarios-card__header h2 {
+  margin: 0;
+}
+
 .card-header {
   display: flex;
   align-items: center;
@@ -103,41 +171,6 @@
   gap: 1.5rem;
 }
 
-.table-responsive {
-  overflow-x: auto;
-  border-radius: var(--table-radius);
-}
-
-.table {
-  width: 100%;
-  border-collapse: collapse;
-  border-radius: var(--table-radius);
-  overflow: hidden;
-  box-shadow: var(--shadow);
-}
-
-.table th,
-.table td {
-  padding: 0.75rem 1rem;
-  border-bottom: 1px solid var(--card-border);
-  background: rgba(21, 27, 35, 0.85);
-}
-
-.table tbody tr:hover {
-  background: var(--hover-highlight);
-}
-
-.table-link {
-  color: var(--brand-2);
-  text-decoration: none;
-  margin-left: 0.5rem;
-}
-
-.table-link:hover,
-.table-link:focus {
-  text-decoration: underline;
-}
-
 .text-right {
   text-align: right;
 }
@@ -147,54 +180,4 @@
     grid-template-columns: 1.1fr 1.9fr;
     align-items: start;
   }
-
-  .header-actions {
-    justify-content: flex-start;
-  }
-}
-
-.alert {
-  padding: 0.75rem 1rem;
-  border-radius: var(--radius-sm);
-  margin-bottom: 1rem;
-}
-
-.alert-error {
-  background: rgba(209, 75, 75, 0.2);
-  border: 1px solid rgba(209, 75, 75, 0.4);
-  color: var(--color-text-invert);
-}
-
-.form {
-  display: flex;
-  flex-direction: column;
-  gap: 1.25rem;
-}
-
-.form-grid {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
-  gap: 1.25rem;
-}
-
-.form-group {
-  display: flex;
-  flex-direction: column;
-  gap: 0.5rem;
-}
-
-.form-group input,
-.form-group select,
-.form-group textarea {
-  padding: 0.75rem 0.85rem;
-  border-radius: var(--radius-sm);
-  border: 1px solid var(--card-border);
-  background: rgba(8, 12, 19, 0.75);
-  color: var(--text);
-}
-
-.form-actions {
-  display: flex;
-  gap: 0.75rem;
-  justify-content: flex-end;
 }

static/css/scenarios.css

@@ -1,49 +1,3 @@
-.scenario-meta {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
-  gap: 1.25rem;
-}
-
-.table {
-  width: 100%;
-  border-collapse: collapse;
-  border-radius: var(--table-radius);
-  overflow: hidden;
-  box-shadow: var(--shadow);
-}
-
-.table th,
-.table td {
-  padding: 0.75rem 1rem;
-  border-bottom: 1px solid var(--color-border);
-  background: rgba(21, 27, 35, 0.85);
-}
-
-.table tbody tr:hover {
-  background: rgba(43, 165, 143, 0.12);
-}
-
-.breadcrumb {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-  font-size: 0.9rem;
-  color: var(--muted);
-  margin-bottom: 1.2rem;
-}
-
-.breadcrumb a {
-  color: var(--brand-2);
-  text-decoration: none;
-}
-
-.header-actions {
-  display: flex;
-  gap: 0.75rem;
-  flex-wrap: wrap;
-  justify-content: flex-end;
-}
-
 .scenario-metrics {
   display: grid;
   gap: 1.5rem;
@@ -51,36 +5,6 @@
   margin-bottom: 2rem;
 }
 
-.metric-card {
-  background: rgba(21, 27, 35, 0.85);
-  border-radius: var(--radius);
-  padding: 1.5rem;
-  box-shadow: var(--shadow);
-  border: 1px solid var(--color-border);
-  display: flex;
-  flex-direction: column;
-  gap: 0.35rem;
-}
-
-.metric-card h2 {
-  margin: 0;
-  font-size: 1rem;
-  color: var(--muted);
-  text-transform: uppercase;
-  letter-spacing: 0.08em;
-}
-
-.metric-value {
-  font-size: 2rem;
-  font-weight: 700;
-  margin: 0;
-}
-
-.metric-caption {
-  color: var(--color-text-subtle);
-  font-size: 0.85rem;
-}
-
 .scenario-filters {
   display: grid;
   gap: 0.75rem;
@@ -107,11 +31,13 @@
   border-radius: var(--radius-sm);
   border: 1px solid var(--color-border);
   background: rgba(8, 12, 19, 0.75);
-  color: var(--text);
+  background: color-mix(in srgb, var(--color-bg-elevated) 75%, transparent);
+  color: var(--color-text-primary);
 }
 
 .scenario-form {
   background: rgba(21, 27, 35, 0.85);
+  background: var(--color-surface-overlay);
   border: 1px solid var(--color-border);
   border-radius: var(--radius);
   box-shadow: var(--shadow);
@@ -121,25 +47,85 @@
   gap: 1.5rem;
 }
 
-.table-responsive {
-  width: 100%;
-  overflow-x: auto;
-  -webkit-overflow-scrolling: touch;
-  border-radius: var(--table-radius);
+.scenario-form .card {
+  background: rgba(21, 27, 35, 0.9);
+  background: color-mix(in srgb, var(--color-surface-default) 90%, transparent);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius);
+  padding: 1.5rem;
+  display: flex;
+  flex-direction: column;
+  gap: 1.25rem;
+}
+
+.scenario-form .card h2 {
   margin: 0;
 }
 
-.table-responsive .table {
-  min-width: 640px;
+.scenario-layout {
+  display: grid;
+  gap: 1.5rem;
 }
 
-.table-responsive::-webkit-scrollbar {
-  height: 6px;
+.scenario-column {
+  display: grid;
+  gap: 1.5rem;
 }
 
-.table-responsive::-webkit-scrollbar-thumb {
-  background: rgba(255, 255, 255, 0.2);
-  border-radius: 999px;
+.quick-actions-card {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.scenario-portfolio {
+  display: flex;
+  flex-direction: column;
+  gap: 1.5rem;
+}
+
+.scenario-portfolio__header {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.scenario-context-card {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.scenario-context-card .definition-list {
+  margin: 0;
+}
+
+.scenario-defaults {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: grid;
+  gap: 0.75rem;
+}
+
+.scenario-defaults li {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.scenario-defaults li strong {
+  font-size: 0.9rem;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--color-text-muted);
+}
+
+.scenario-layout .table tbody tr:hover,
+.scenario-portfolio .table tbody tr:hover {
+  background: rgba(43, 165, 143, 0.12);
+  background: color-mix(in srgb, var(--color-accent) 18%, transparent);
 }
 
 @media (min-width: 720px) {
@@ -151,10 +137,6 @@
   .scenario-filters .filter-actions {
     justify-content: flex-end;
   }
-
-  .table-responsive .table {
-    min-width: 100%;
-  }
 }
 
 @media (max-width: 640px) {
@@ -162,34 +144,9 @@
     flex-wrap: wrap;
     gap: 0.35rem;
   }
-
-  .table th,
-  .table td {
-    padding: 0.55rem 0.65rem;
-    font-size: 0.9rem;
-    white-space: nowrap;
-  }
-
-  .table tbody tr {
-    border-radius: var(--radius-sm);
-  }
-}
-
-.scenario-layout {
-  display: grid;
-  gap: 1.5rem;
-}
-
-.empty-state {
-  color: var(--muted);
-  font-style: italic;
 }
 
 @media (min-width: 960px) {
-  .header-actions {
-    justify-content: flex-start;
-  }
-
   .scenario-layout {
     grid-template-columns: 1.1fr 1.9fr;
     align-items: start;