OWC

FastAPI Postgres App

Documentation

• API
• Architecture
• Data model
• Deployment
• Environment variables
• Railway environments
• Score calculation

Deployment

Schema migrations are centralized in scripts/schema_migrations.py and are executed by:

• app startup in main.py
• manual runner scripts/apply_migrations.py

Start with migrations

Linux/macOS:

chmod +x scripts/start_with_migrations.sh
PORT=8000 scripts/start_with_migrations.sh

Windows (PowerShell):

.\scripts\start_with_migrations.ps1

Railway

• Procfile uses: bash scripts/start_with_migrations.sh
• Dockerfile CMD uses: bash scripts/start_with_migrations.sh

Environment setup

• Local development: copy .env.local.example to .env.local (or use .env.example as a base).
• Railway test: use .env.test.example as the variable blueprint.
• Railway production: use .env.production.example as the variable blueprint.
• Railway does not read your local .env files automatically.

Canonical documentation:

• Variable meanings, defaults, and validation: docs/ENVIRONMENT_VARIABLES.md
• Railway test/prod setup examples and rollout guidance: docs/railway-environments.md

Smoke test

Run a quick endpoint health check after deploy:

python scripts/smoke_test.py --base-url https://your-railway-api.up.railway.app

Local example:

python scripts/smoke_test.py --base-url http://127.0.0.1:8000

Testing

Unit tests (no running server needed):

pip install -r requirements-dev.txt
pytest

Playwright tests (in playwright/, Node/TypeScript): API checks plus a browser test that drives the real Wordpress code/*.html pages. The pages use configured URL constants for API calls and redirects, so update those page constants when switching environments. These need the app running separately:

cd playwright
npm install
npx playwright install chromium

uvicorn main:app --port 8000   # in one terminal, from the repo root

cd playwright                  # in another terminal
npm test                       # headless run
npm run test:ui                # interactive UI mode - test list + live browser preview
npm run test:headed            # watch it run in a visible browser

API_BASE_URL overrides the target API (defaults to http://127.0.0.1:8000), e.g. to run against a deployed environment:

API_BASE_URL=https://your-railway-api.up.railway.app npm test