# Core Backend API

## Overview

The core backend lives in `backend/app/` and is built with FastAPI. It is the central service that the Shield (TRINETRA) mobile app talks to for most protection features, and it acts as an orchestrator that proxies some work (like heavy APK static analysis) out to dedicated microservices. All routes are mounted under the `/api/v1` prefix unless noted otherwise.

## Router list

- `apk_routes` — `/apk/*` — upload and analyze APK files. This router does not run the heavy analysis engines itself; it forwards the APK to the dedicated APK scanner microservice and returns the enriched verdict.
- `case_routes` — case-management endpoints tied to flagged incidents.
- `demo_routes` — endpoints used to drive demo/staging scenarios (e.g. for hackathon or stakeholder demos) without touching real user data paths.
- `device_routes` — `/device/analyze` — device-level security posture checks (root/jailbreak-style signals, device integrity).
- `event_routes` — `GET /events` and `POST /events` — the threat-history sync endpoint. The Flutter app's local `ThreatHistoryNotifier` (a Riverpod-managed, SharedPreferences-persisted list capped at 200 entries) pushes and pulls events here so a user's protection history survives an app reinstall.
- `infrastructure_routes` — internal/infra-facing endpoints (health/config style checks beyond the top-level `/health`).
- `qr_routes` — `/qr/*` — QR code payload analysis for payment-QR-related scam detection.
- `risk_routes` — `/risk/*` — general risk-scoring endpoints.
- `url_routes` — `/url/scan` — URL/link risk scanning, used both directly by the app and by the Guardian WhatsApp microservice for its URL-risk component.
- `transaction` router — `/transaction/analyze` — transaction-pattern risk analysis.
- `behaviour` router — `/behaviour/*` — behavioural-signal analysis endpoints (device/usage behaviour submitted by the Android SDK).
- `immunity` router — `/immunity/score` — computes an aggregate "immunity" style risk score for a device/user.
- `smishing_intel` router — `/smishing/analyze` — SMS phishing (smishing) text classification, also used by the Guardian WhatsApp service's message-urgency scoring.

In addition to these domain routers, the app exposes `GET /health` for liveness checks and `GET /` at the root, which returns basic service info.

## Authentication

Every sensitive endpoint requires an `X-API-Key` header that must match a single shared secret, enforced by the `require_api_key` dependency in `app/security.py`. This is a shared, service-wide key — not a per-user credential. There is currently no per-user JWT or OAuth layer on this backend. This is explicitly called out in the codebase as a stop-gap for the pilot stage, adopted because there are no backend user accounts yet (the app's Supabase Auth sign-in is a separate, currently-unconnected identity system — see `auth-and-data-model.md` for details).

## Rate limiting

Some endpoints additionally apply a Redis-backed per-IP rate limit. This limiter is designed to fail open: if Redis is unreachable, requests are allowed through rather than being blocked, so a Redis outage degrades rate-limiting rather than taking down the API.

## Caching

Redis is also used as a best-effort cache for analysis results, keyed by APK hash, with a configurable `ANALYSIS_CACHE_TTL`. This is an optimization, not a hard dependency — if Redis is down, the backend falls back to recomputing/re-proxying analysis rather than failing the request.

## Data layer

The backend uses async SQLAlchemy with the `asyncpg` driver against a Postgres database. In the current deployment, that Postgres instance is Supabase-hosted, but the backend talks to it purely as a Postgres database via SQLAlchemy — it does not use Supabase's client SDK or Supabase Auth on the backend side.

## Relationship to other services

The core backend is a hub: it proxies APK analysis to the APK scanner microservice (`APK_SCANNER_URL`), and it is called by the Guardian Call service (for fresh malicious-APK notifications) and by the Guardian WhatsApp service (for URL scanning, smishing classification, and APK analysis) as part of their own workflows.