# Enterprise Docker Infrastructure & Container Topology

This directory contains production-hardened container manifests, multi-stage Dockerfiles, reverse proxy configurations, cold-start database schemas, and observability provisioning for the **Privacy-Preserving Cross-Bank Fraud Detection Platform (CFI)**.

---

## 1. Directory Structure

```text
docker/
├── Dockerfile.backend                 # Multi-stage hardened Python 3.12 API & FL runtime (non-root UID 1000, libpq drivers)
├── Dockerfile.frontend                # Multi-stage Node 22 / Nginx 1.27 Alpine SPA container
├── nginx/
│   ├── nginx.conf                     # Enterprise reverse proxy, WebSocket upgrade map & security headers
│   └── frontend-nginx.conf            # SPA routing fallback, gzip compression & static asset caching
├── postgres/
│   └── 01-init.sql                    # PostgreSQL 16 cold-start DDL, extensions, schemas & consortium seed
├── otel/
│   └── otel-collector-config.yaml     # OpenTelemetry Collector pipeline (OTLP receiver, Prometheus exporter)
├── prometheus/
│   └── prometheus.yml                 # Prometheus 2.50 scrape configurations for API & OTel collector
└── grafana/
    └── provisioning/
        ├── datasources/
        │   └── prometheus.yaml        # Automated Prometheus datasource link
        └── dashboards/
            ├── dashboards.yaml        # Dashboard provider specification
            └── fl_platform_dashboard.json # Pre-configured FL metrics, drift (PSI), latency & alerts
```

---

## 2. Multi-Stage Dockerfiles

### 2.1 Backend API & FL Engine (`Dockerfile.backend`)
- **Stage 1 (Builder)**: `python:3.12-slim-bookworm` utilizing `uv` with `libpq-dev` for reproducible, sub-second dependency installation into `/opt/venv`.
- **Stage 2 (Runtime)**: Minimal slim image with pre-compiled wheels, `libpq5` shared libraries, and zero build tools (`gcc`/`git` stripped).
- **Security Posture**: Enforces non-root user `user:user` (UID `1000`, GID `1000`) with strict directory ownership.
- **Ports Exposed**: `8000` (FastAPI HTTP / WebSocket) and `50051` (gRPC Mutual TLS Consortium Coordinator).
- **Healthcheck Probe**: `curl -f http://127.0.0.1:8000/health || exit 1` (`interval=10s`, `timeout=3s`, `retries=3`).

### 2.2 Frontend SPA (`Dockerfile.frontend`)
- **Stage 1 (Builder)**: `node:22-alpine` compiling React 19 + TypeScript bundle via `npm ci` and `npm run build`.
- **Stage 2 (Runtime)**: `nginx:1.27-alpine-slim` hardened web server serving compiled static assets.
- **Routing**: Client-side SPA routing fallback (`try_files $uri $uri/ /index.html;`) with immutable cache headers for `/assets/`.
- **Healthcheck Probe**: `wget -qO- http://127.0.0.1/health || exit 1` (supports `/health`, `/ready`, and `/live`).

---

## 3. Nginx Reverse Proxy & Routing Blueprint (`docker/nginx/`)

The outer gateway (`cfi-gateway`) terminates HTTP/HTTPS traffic and routes requests through an internal bridge network (`cfi-network`):

| Route Path | Upstream Target | Protocol / Purpose |
|:---|:---|:---|
| `/api/*` | `http://backend_api` (`cfi-api-server:8000`) | REST API with connection pooling (`keepalive 32`) |
| `/ws/*` | `http://backend_api` (`cfi-api-server:8000`) | Bidirectional WebSockets with `Upgrade` headers & `86400s` timeout |
| `/docs`, `/redoc`, `/scalar`, `/openapi.json` | `http://backend_api` (`cfi-api-server:8000`) | Interactive OpenAPI, Swagger, ReDoc & Scalar documentation & schema |
| `/health`, `/ready`, `/live` | `http://backend_api` (`cfi-api-server:8000`) | Health, readiness, and liveness probe endpoints |
| `/gateway-health` | Local Nginx response | Gateway healthcheck probe (HTTP `200 "cfi_gateway_healthy"`) |
| `/*` (Root Fallback) | `http://frontend_spa` (`cfi-frontend:80`) | Frontend Single Page Application |

### Security Headers Enforced
- `X-Frame-Options: SAMEORIGIN` (Clickjacking defense)
- `X-Content-Type-Options: nosniff` (MIME sniffing prevention)
- `X-XSS-Protection: 1; mode=block`
- `Referrer-Policy: strict-origin-when-cross-origin`
- `Permissions-Policy: geolocation=(), microphone=(), camera=()`

---

## 4. Cold-Start Database Initialization (`docker/postgres/01-init.sql`)

Mounted to `/docker-entrypoint-initdb.d/01-init.sql:ro` inside PostgreSQL 16:
1. **Extensions**: Installs `uuid-ossp` and `pg_trgm` for trigram similarity fuzzy matching on transaction narratives.
2. **Dedicated Schema**: Isolates consortium tables under schema `cfi_fraud`.
3. **Core Entities**:
   - `cfi_fraud.banks`: Consortium registry (`bank_id`, `name`, `tier`, `jurisdiction`, `connector_type`).
   - `cfi_fraud.simulations`: Federated training run metadata (`simulation_id`, `champion_auc`, `privacy_epsilon`, `aggregation_strategy`).
   - `cfi_fraud.alerts`: Anti-money laundering alerts with JSONB feature payloads.
   - `cfi_fraud.cases`: Four-Eyes investigation cases with SAR narrative drafts.
   - `cfi_fraud.audit_chain`: Append-only cryptographic audit trail with SHA-256 payload hashes and digital signatures.
4. **Idempotent Seeding**: Seeds initial consortium members (`bank_alpha`, `bank_beta`, `bank_gamma`) using `ON CONFLICT (bank_id) DO UPDATE`.

---

## 5. Telemetry & Observability Pipeline

- **OpenTelemetry Collector (`docker/otel/`)**: Listens on gRPC `4317` and HTTP `4318`, applies 1-second batching, and exports metrics to Prometheus (`0.0.0.0:8889`) and traces to logs.
- **Prometheus (`docker/prometheus/`)**: Scrapes `cfi-api-server:8000` (`/metrics`) and `otel-collector:8889` on a 5-second interval.
- **Grafana (`docker/grafana/`)**: Automatically provisions Prometheus datasource and loads the `Cross-Bank FL Intelligence Platform Dashboard` featuring:
  - Federated Learning Loss Convergence (`cfi_fl_round_loss`)
  - Feature Drift Population Stability Index (`cfi_model_drift_psi`)
  - Inference Latency SLA P95/P99 (`cfi_http_request_duration_seconds_bucket`)
  - Active Cross-Bank Fraud Risk Alert Counter (`cfi_active_alerts_total`)

---

## 6. Execution & Docker Compose Profiles

```bash
# Standard Production Stack (Gateway, Frontend, Backend API, PostgreSQL, Redis)
docker compose up -d --build

# With Observability Stack (Adds OTel Collector, Prometheus, Grafana)
docker compose --profile monitoring up -d --build

# With Enterprise Security (Adds HashiCorp Vault KMS)
docker compose --profile enterprise up -d --build

# Full Enterprise Consortium Stack (All services)
docker compose --profile monitoring --profile enterprise --profile storage --profile ml up -d --build
```

---

## 7. Verification

Validate all deployment manifests, Dockerfiles, Nginx directives, healthchecks, and environment parity with the automated suite:

```bash
python scripts/verify_docker_deployment.py
```