Infrastructure Requirements

Decisions that informed this section: ADR-006 (Fly.io + Neon + Cloudflare)

---

Compute

All runtime compute is provided by Fly.io (fra, Frankfurt). There are two distinct runtime workloads: the Chat API (always-on, request-driven) and the daily backup job (scheduled, short-lived).

Chat API Machine

Cold start behaviour. When the Machine is suspended and a new request arrives, Fly.io wakes it in approximately 300–500ms. The Chat API then takes an additional ~200ms to initialise the FastAPI application and the LangGraph checkpointer connection. Total cold start: ~500–700ms. This is within the TTFT budget (p95 < 3s, Section 7) for first-turn requests. Subsequent turns in the same session are served from a warm Machine.

Scaling review trigger. If Phase 5 load testing reveals that a single Machine instance cannot sustain the target p95 TTFT under concurrent load, min_machines_running = 1 (disable scale-to-zero) and max_machines = 2 are the first configuration changes. No code changes are required. See ADR-006 — Review Triggers.

Backup Cron Machine

The backup Machine shares the DATABASE_URL secret with the Chat API Machine. It requires three additional secrets: TIGRIS_BUCKET_NAME, TIGRIS_ACCESS_KEY_ID, and TIGRIS_SECRET_ACCESS_KEY. See the Environment Variables section and the deployment runbook.

Indexing Pipeline

The knowledge base indexing pipeline (document chunking, embedding, pgvector
insertion) runs as a one-off Fly Machine invoked manually during Phase 2
and whenever the knowledge base is updated. It is not a persistent service.
It uses the same container image as the Chat API, invoked with a different
entrypoint (python -m scripts.index).

---

Storage

All persistent storage is provided by Neon Serverless Postgres
(eu-central-1, Frankfurt) on the free tier. The database serves two roles:
pgvector knowledge index (ADR-003) and LangGraph session state checkpointer
(ADR-004). Both roles share the same Neon project and connection string in v1.

Database Tables and Sizing

Total estimated MVP storage: < 50 MB. This is well within Neon’s free tier
limit of 512 MB.

Retention enforcement. A scheduled cleanup job (co-located with the backup
cron Machine, running weekly) deletes rows from checkpoints,
checkpoint_writes, and messages where the associated session’s
closed_at timestamp is older than 90 days. handoff_records are retained
indefinitely and deleted only on explicit GDPR erasure requests processed
manually by the data controller.

pgvector Index

Backup Strategy

Neon free tier provides 24-hour point-in-time recovery (PITR). The PRD
requires 90-day retention of conversation data (§6.3). To bridge this gap,
a daily pg_dump backup is written to Tigris object storage.

Backup process:

1. The backup cron Machine runs daily at 02:00 CET/CEST.
2. It executes pg_dump against the Neon database, compressing output with
   gzip.
3. The compressed archive is uploaded to the backups/ prefix in the
   configured Tigris bucket, named backup-YYYY-MM-DD.sql.gz.
4. Tigris object lifecycle policy retains archives for 90 days, then
   deletes automatically.

Recovery procedure. In the event of data loss beyond the 24-hour PITR
window, the on-call engineer downloads the most recent daily archive from
Tigris, restores it to a new Neon database branch, and updates
CHECKPOINT_DB_URL to point to the restored branch.

Accepted risk. Up to 24 hours of conversation data may be lost in a
catastrophic failure scenario (hardware loss beyond PITR coverage). This is
an accepted risk for the MVP. If the system enters production under formal
SLA commitments, upgrading to Neon Launch plan (~$19/month, 7-day PITR) is
the remediation path. See ADR-006 — Review Triggers.

Backup failure alerting. If the backup cron Machine exits with a non-zero
code, Fly.io emits a machine exit event. This event must be routed to the
observability layer (Section 9) as a backup_failed alert. Configuration
of this alert is part of the Phase 3 observability setup.

Static Asset Storage

The compiled chat.js widget bundle is stored in Tigris (Fly-native
S3-compatible object storage) and served via Cloudflare CDN. The widget
bundle contains no personal data and is not subject to GDPR retention rules.

---

Networking

TLS

CORS

The Chat API must allow cross-origin requests from the host website where the
<growth-chat> widget is embedded. CORS is configured at the FastAPI
application level.

# FastAPI CORS configuration
origins = [
    os.environ["ALLOWED_ORIGIN"],   # e.g. "https://www.company.com"
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_methods=["POST", "GET"],
    allow_headers=["Content-Type", "X-Widget-Token"],
)

ALLOWED_ORIGIN is a required environment variable (see Section 6.4). Wildcard
origins (*) must not be used in staging or production — only in local
development.

Client IP Resolution

Cloudflare proxies all inbound traffic. The Fly Machine sees Cloudflare’s
egress IP in the socket, not the visitor’s IP. The Chat API must read the
CF-Connecting-IP header as the authoritative client IP for per-IP rate
limiting in slowapi.

def get_client_ip(request: Request) -> str:
    return request.headers.get("CF-Connecting-IP") or request.client.host

This function is used as the key function in all slowapi rate limit
decorators. Using X-Forwarded-For is not sufficient — it may contain
multiple IPs in proxy chains.

Ports and Domains

Production domain names are defined at deployment time and documented in the
deployment runbook. They are not hardcoded in the application.

---

Environment Variables

This section is the single authoritative reference for all environment
variables consumed by the system. Variables are grouped by the component that
reads them. All variables marked Required cause the service to refuse to
start if unset.

Secret management. All variables marked as secrets must be stored in
Fly.io Secrets (fly secrets set KEY=value) and must never be committed to
source control. Variables marked as build-time are set in the Fly.io build
environment or as VITE_* variables in the widget build pipeline.

---

LLM — Anthropic

---

RAG — OpenAI Embeddings

---

Conversation Orchestrator

---

Persistence

---

Human Handoff Subsystem

---

Business Hours Detection

---

Chat API — Application

---

Backup Cron Machine Variables

DATABASE_URL is shared with the Chat API Machine via the same Fly.io app
secrets and does not need to be declared separately for the backup job.

---

Widget — Build-time (VITE_*)

These variables are injected at widget build time and compiled into the
chat.js bundle. They are not runtime environment variables. They are set
in the CI/CD pipeline environment for each deployment target.

---

Quick Reference — Required Variables Checklist

The following variables have no default and cause the service to refuse to
start (or behave incorrectly) if unset. This list is the minimum viable
configuration for a deployment.

Chat API runtime (Fly secrets):

ANTHROPIC_API_KEY
OPENAI_API_KEY
RAG_RELEVANCE_THRESHOLD       # provisional: 0.70 for Phase 1-2 only
CHECKPOINT_DB_URL
SLACK_WEBHOOK_URL
SLACK_BOT_TOKEN
FALLBACK_EMAIL_ADDRESS
SMTP_HOST
SMTP_USERNAME
SMTP_PASSWORD
ALLOWED_ORIGIN
BUSINESS_HOURS_TIMEZONE       # example: Europe/Madrid

Backup cron Machine (Fly secrets):

TIGRIS_BUCKET_NAME
TIGRIS_ACCESS_KEY_ID
TIGRIS_SECRET_ACCESS_KEY

Widget build pipeline (CI environment):

VITE_API_URL
VITE_FALLBACK_URL
VITE_GDPR_NOTICE_TEXT

---

Engineering Concerns Resolved by This Section