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
| URL | What |
|---|---|
| <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.
| Variable | Default | Notes |
|---|---|---|
DATABASE_URL | sqlite:///./scamguard.db | Postgres via docker-compose.yml |
LLM_ENABLED | true | false skips the LLM tier entirely |
OLLAMA_MODEL | qwen3:8b | Smaller model = faster live-call analysis |
WHISPER_MODEL | base | tiny / small trade speed for accuracy |
WEB_INTEL_ENABLED | false | External scam-report search — off by default |
RDAP_ENABLED | false | External 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_BYTES | 26214400 | 25 MB |
MAX_AUDIO_SECONDS | 600 | 10 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_INTERNAL | true | false 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
- iOS simulator:
http://localhost:8000 - Android emulator:
http://10.0.2.2:8000 - Physical device: your Mac's LAN IP, plus
CORS_ORIGINSset in.env
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.