Local development

Backend

Requires Python 3.10+ (3.12 recommended — macOS system Python is 3.9 and will not work).


cd backend
python3.12 -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip     # old pip cannot do editable pyproject installs
pip install -e ".[dev]"
uvicorn app.main:create_app --factory --port 8000 --reload
URLWhat
<http://localhost:8000/>Web app
<http://localhost:8000/guide>Documentation site (this page)
<http://localhost:8000/docs>OpenAPI / Swagger
<http://localhost:8000/v1/health>Runtime status

If you see a 404 at the root, you are probably opening index.html from the filesystem instead of through the server.

Optional capabilities

Everything degrades gracefully; none of this is required.


# Local LLM — enables AI explanations and the advisor chat
brew install ollama
ollama serve                 # keep running in its own terminal
ollama pull qwen3:8b         # ~5 GB, one-time
                             # slower machine? qwen3:4b + OLLAMA_MODEL=qwen3:4b

# Local voice transcription — enables the "Voice file" button
pip install -e ".[voice]"    # first upload downloads a ~75 MB model

Without Ollama you get rules-only verdicts (all critical alerts still work). Without faster-whisper the voice endpoint returns a clear 503.

Configuration

All settings are environment variables or a backend/.env file. Defaults are chosen for private local use.

VariableDefaultNotes
DATABASE_URLsqlite:///./scamguard.dbPostgres via docker-compose.yml
LLM_ENABLEDtruefalse skips the LLM tier entirely
OLLAMA_MODELqwen3:8bSmaller model = faster live-call analysis
WHISPER_MODELbasetiny / small trade speed for accuracy
WEB_INTEL_ENABLEDfalseExternal scam-report search — off by default
RDAP_ENABLEDfalseExternal domain-age lookups — off by default
API_KEYS(empty)Comma-separated; when set, review routes need X-API-Key
CORS_ORIGINS(empty)Needed for mobile clients on a device
MAX_UPLOAD_BYTES2621440025 MB
MAX_AUDIO_SECONDS60010 minutes
PSEUDONYM_KEY(dev key)Secret for keyed sender/message fingerprints. Set once in production, never change
PUBLIC_CONTACT_EMAIL(empty)Shown on the web app's Privacy and Terms pages
DOCS_SHOW_INTERNALtruefalse hides strategy docs (plan, roadmap, competitor) from /guide

Even with WEB_INTEL_ENABLED=true, external lookups still require per-request user_consent_online_checks — see safety invariants.

Tests


cd backend && python -m pytest

Fully offline: no network, no Ollama, no API keys. If a change makes a test need any of those, that is the bug.


python -m pytest tests/test_docs.py     # documentation freshness only
python -m pytest -k livecall            # one area
python -m pytest -q --tb=short          # quieter output

Operating a deployment


python -m app.ops check              # launch readiness — exits 1 on any FAIL
python -m app.ops stats --days 7     # checks, feedback, false reassurance vs false alarm
python -m app.ops misses --days 7    # every "you missed a scam", with the message if shared

They read the same .env as the server, so they check what will actually run. Production settings start from backend/.env.production.example; server and proxy config are in deploy/.

Mobile clients against a local backend


uvicorn app.main:create_app --factory --host 0.0.0.0 --port 8000

Both platforms block cleartext HTTP in release builds — the dev exceptions (NSAppTransportSecurity, network_security_config.xml) must never ship.

Troubleshooting

command not found: uvicorn — the venv is not active. source .venv/bin/activate.

Package 'scamguard' requires a different Python — the venv was built with Python 3.9. Delete .venv and recreate it with 3.10+.

ERROR: File "setup.py" not found — pip is too old for editable pyproject.toml installs. python -m pip install --upgrade pip.

sqlite3.OperationalError: disk I/O error — the database path is on a filesystem that cannot lock (some network/virtual mounts). Point DATABASE_URL at local disk, e.g. sqlite:////tmp/scamguard.db.

Live call stuck on "listening" — browser speech recognition pauses during silence and restarts automatically. Chrome is most reliable; Safari needs macOS Dictation enabled. The status line under the caller ID reports the recognizer's actual state.

Docs test failing after an API change — that is the test doing its job. Update docs/api-reference.md and docs/changelog.md in the same commit.

Caller check with web lookups

Local caller checks (number type, registry, community reports) always run. To let the caller check search the web — the number on the claimed organisation's own site, and scam reports — set in backend/.env:


WEB_INTEL_ENABLED=true
SEARCH_PROVIDER=auto          # DuckDuckGo without a key; BRAVE_SEARCH_API_KEY or TAVILY_API_KEY for a keyed API

Restart the server, then tick Also check this number on the web on the Live call tab. From a terminal: python -m app.ops caller-check 600540000 --claim emirates_nbd.