Skip to content

Runtime

Process model

The backend runs as a single FastAPI process:

  • app creation in app/main.py
  • Docker startup command uvicorn app.main:app --host 0.0.0.0 --port ${PORT}
  • health endpoint at /health
  • CORS configured from CORS_ALLOWED_ORIGINS in production and open in non-prod

There is no dedicated worker deployment in render.yaml. Long-running ingestion work is started through FastAPI BackgroundTasks, and periodic tasks are registered with APScheduler during startup.

Request pipeline

The request path is:

  1. RequestIDMiddleware assigns or propagates X-Request-ID.
  2. RateLimitMiddleware applies in-memory per-path limits.
  3. FastAPI routes dispatch into the relevant router.
  4. Auth dependencies validate Supabase JWTs when required.
  5. Routers call shared services from app/core/dependencies.py.

Important runtime characteristics:

  • rate limiting is process-local and resets on restart
  • metrics are in-memory, not backed by Prometheus client storage
  • dependency instances are module singletons, created at import time

Dependency wiring

app/core/dependencies.py initializes:

  • OpenAI client
  • Supabase service-role client
  • Pinecone adapter
  • retrieval pipeline and quiz generator
  • wallet service
  • scraping and ingestion services

This keeps router code short, but it also means misconfigured environment variables usually fail at import time, not only at first request.

Environment variables in active use

The runtime directly consumes values from app/core/config.py, including:

  • OPENAI_API_KEY, OPENAI_CHAT_MODEL, OPENAI_REASONING_MODEL, OPENAI_RERANK_MODEL, OPENAI_EMBEDDING_MODEL
  • PINECONE_API_KEY, PINECONE_INDEX_NAME, PINECONE_NAMESPACE_DEFAULT
  • SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, SUPABASE_JWT_SECRET
  • BASE_CHAT_COST, TOKEN_BUFFER
  • RETRIEVAL_TOP_K, RERANK_TOP_N
  • CHUNK_SIZE, CHUNK_OVERLAP
  • ENV, CORS_ALLOWED_ORIGINS

.env.example contains additional values that are planned or historical; the settings class in app/core/config.py is the reliable list of app-level configuration currently loaded by code.

Background execution

Two background patterns exist today:

  • request-scoped ingestion execution via BackgroundTasks in admin routes
  • process-scoped scheduled work via app/services/background_jobs.py

Operational note:

  • the scheduled reservation reconciliation code path is present but not aligned with the current wallet service implementation, so it should not be assumed healthy without explicit verification