# keormel/safecall architecture

> Architecture diagram of the GitHub repository keormel/safecall, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/keormel/safecall
- Repository: https://github.com/keormel/safecall

## Overview

SafeCall combines a mobile caller-protection client, a FastAPI service that turns user reports into risk scores and scam campaigns, and a separate administration console. The principal loop is incoming-number screening from the local database, refreshed by server delta sync; reports feed the server’s scoring and campaign analysis, which informs later checks and updates. The README documents product capabilities beyond the sampled code, so those links are cited to it; implementation details for unsampled Flutter and admin subsystems are represented only at supported directory level.

Main entry points: [`backend/app/services/report_service.py`](https://github.com/keormel/safecall/blob/main/backend/app/services/report_service.py) (Report processing), [`backend/app/main.py`](https://github.com/keormel/safecall/blob/main/backend/app/main.py) (API routing), [`backend/app/routers/sync.py`](https://github.com/keormel/safecall/blob/main/backend/app/routers/sync.py) (Delta sync), [`mobile/android/app/src/main/kotlin/com/safecall/safecall/SafeCallScreeningService.kt`](https://github.com/keormel/safecall/blob/main/mobile/android/app/src/main/kotlin/com/safecall/safecall/SafeCallScreeningService.kt) (Call screening)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile protection"]
  node_mobile_app["Mobile app"]
  node_screening["Call screening"]
  node_call_store[("Local number DB<br/>[CallStore.kt]")]
  node_call_notice["Call notices"]
  node_ios_directory["iOS call directory"]
end

subgraph group_backend["Risk intelligence API"]
  node_api["API routing<br/>[main.py]"]
  node_auth["Device auth<br/>[auth.py]"]
  node_number_check["Number checks<br/>[numbers.py]"]
  node_report_routes["Report intake<br/>[reports.py]"]
  node_report_service["Report processing<br/>[report_service.py]"]
  node_fingerprints["Fingerprinting<br/>[fingerprint.py]"]
  node_risk["Risk scoring<br/>[risk_engine.py]"]
  node_campaigns["Campaign analysis<br/>[campaign_engine.py]"]
  node_sync["Delta sync<br/>[sync.py]"]
  node_assistant["In-app assistant<br/>[assistant.py]"]
  node_gemini["Gemini service<br/>[gemini.py]"]
  node_jobs["Scheduled jobs<br/>[jobs.py]"]
  node_models["Domain records<br/>[models.py]"]
  node_database[("PostgreSQL<br/>[db.py]")]
end

subgraph group_admin["Administration"]
  node_admin_ui["Admin console<br/>[App.tsx]"]
  node_admin_client["Admin API client<br/>[client.ts]"]
  node_admin_api["Admin API<br/>[main.py]"]
  node_admin_data["Admin data access<br/>[db_client.py]"]
end

node_caller(("Caller"))

node_caller -->|"incoming call"| node_screening
node_screening -->|"checks number"| node_call_store
node_screening -->|"shows notice"| node_call_notice
node_mobile_app -->|"fetches deltas"| node_sync
node_sync -->|"updates local DB"| node_call_store
node_mobile_app -->|"checks and reports"| node_api
node_ios_directory -.->|"uses local data"| node_call_store
node_api -->|"routes requests"| node_auth
node_api -->|"routes requests"| node_number_check
node_api -->|"routes requests"| node_report_routes
node_api -->|"routes requests"| node_sync
node_number_check -->|"checks number"| node_report_service
node_report_routes -.->|"records report"| node_report_service
node_report_service -->|"builds fingerprint"| node_fingerprints
node_report_service -->|"recalculates risk"| node_risk
node_report_service -->|"refreshes campaign"| node_campaigns
node_risk -->|"reads and updates"| node_models
node_campaigns -->|"assigns numbers"| node_models
node_report_service -.->|"persists report"| node_database
node_sync -->|"reads changed numbers"| node_database
node_jobs -->|"recalculates scores"| node_risk
node_jobs -->|"maintains campaigns"| node_campaigns
node_assistant -->|"answers questions"| node_gemini
node_fingerprints -->|"classifies complaints"| node_gemini
node_admin_ui -->|"uses API client"| node_admin_client
node_admin_client -.->|"sends requests"| node_admin_api
node_admin_api -.->|"loads admin data"| node_admin_data
node_admin_data -.->|"reads shared records"| node_database

click node_mobile_app "https://github.com/keormel/safecall/tree/main/mobile"
click node_screening "https://github.com/keormel/safecall/blob/main/mobile/android/app/src/main/kotlin/com/safecall/safecall/SafeCallScreeningService.kt"
click node_call_store "https://github.com/keormel/safecall/blob/main/mobile/android/app/src/main/kotlin/com/safecall/safecall/CallStore.kt"
click node_call_notice "https://github.com/keormel/safecall/blob/main/mobile/android/app/src/main/kotlin/com/safecall/safecall/NotificationHelper.kt"
click node_ios_directory "https://github.com/keormel/safecall/blob/main/mobile/ios/CallDirectory/CallDirectoryHandler.swift"
click node_api "https://github.com/keormel/safecall/blob/main/backend/app/main.py"
click node_auth "https://github.com/keormel/safecall/blob/main/backend/app/routers/auth.py"
click node_number_check "https://github.com/keormel/safecall/blob/main/backend/app/routers/numbers.py"
click node_report_routes "https://github.com/keormel/safecall/blob/main/backend/app/routers/reports.py"
click node_report_service "https://github.com/keormel/safecall/blob/main/backend/app/services/report_service.py"
click node_fingerprints "https://github.com/keormel/safecall/blob/main/backend/app/services/fingerprint.py"
click node_risk "https://github.com/keormel/safecall/blob/main/backend/app/services/risk_engine.py"
click node_campaigns "https://github.com/keormel/safecall/blob/main/backend/app/services/campaign_engine.py"
click node_sync "https://github.com/keormel/safecall/blob/main/backend/app/routers/sync.py"
click node_assistant "https://github.com/keormel/safecall/blob/main/backend/app/services/assistant.py"
click node_gemini "https://github.com/keormel/safecall/blob/main/backend/app/services/gemini.py"
click node_jobs "https://github.com/keormel/safecall/blob/main/backend/app/jobs.py"
click node_models "https://github.com/keormel/safecall/blob/main/backend/app/models.py"
click node_database "https://github.com/keormel/safecall/blob/main/backend/app/db.py"
click node_admin_ui "https://github.com/keormel/safecall/blob/main/admin-morda-sasha/frontend/src/App.tsx"
click node_admin_client "https://github.com/keormel/safecall/blob/main/admin-morda-sasha/frontend/src/api/client.ts"
click node_admin_api "https://github.com/keormel/safecall/blob/main/admin-morda-sasha/app/main.py"
click node_admin_data "https://github.com/keormel/safecall/blob/main/admin-morda-sasha/app/db_client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mobile_app,node_screening,node_call_store,node_call_notice,node_ios_directory toneBlue
class node_api,node_auth,node_number_check,node_report_routes,node_report_service,node_fingerprints,node_risk,node_campaigns,node_sync,node_assistant,node_gemini,node_jobs,node_models,node_database toneAmber
class node_admin_ui,node_admin_client,node_admin_api,node_admin_data toneMint
class node_caller toneIndigo
```

## Components

### Mobile protection

- [Mobile app](https://github.com/keormel/safecall/tree/main/mobile): `mobile`
- [Call screening](https://github.com/keormel/safecall/blob/main/mobile/android/app/src/main/kotlin/com/safecall/safecall/SafeCallScreeningService.kt): `mobile/android/app/src/main/kotlin/com/safecall/safecall/SafeCallScreeningService.kt`
- [Local number DB](https://github.com/keormel/safecall/blob/main/mobile/android/app/src/main/kotlin/com/safecall/safecall/CallStore.kt): `mobile/android/app/src/main/kotlin/com/safecall/safecall/CallStore.kt`
- [Call notices](https://github.com/keormel/safecall/blob/main/mobile/android/app/src/main/kotlin/com/safecall/safecall/NotificationHelper.kt): `mobile/android/app/src/main/kotlin/com/safecall/safecall/NotificationHelper.kt`
- [iOS call directory](https://github.com/keormel/safecall/blob/main/mobile/ios/CallDirectory/CallDirectoryHandler.swift): `mobile/ios/CallDirectory/CallDirectoryHandler.swift`

### Risk intelligence API

- [API routing](https://github.com/keormel/safecall/blob/main/backend/app/main.py): `backend/app/main.py`
- [Device auth](https://github.com/keormel/safecall/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Number checks](https://github.com/keormel/safecall/blob/main/backend/app/routers/numbers.py): `backend/app/routers/numbers.py`
- [Report intake](https://github.com/keormel/safecall/blob/main/backend/app/routers/reports.py): `backend/app/routers/reports.py`
- [Report processing](https://github.com/keormel/safecall/blob/main/backend/app/services/report_service.py): `backend/app/services/report_service.py`
- [Fingerprinting](https://github.com/keormel/safecall/blob/main/backend/app/services/fingerprint.py): `backend/app/services/fingerprint.py`
- [Risk scoring](https://github.com/keormel/safecall/blob/main/backend/app/services/risk_engine.py): `backend/app/services/risk_engine.py`
- [Campaign analysis](https://github.com/keormel/safecall/blob/main/backend/app/services/campaign_engine.py): `backend/app/services/campaign_engine.py`
- [Delta sync](https://github.com/keormel/safecall/blob/main/backend/app/routers/sync.py): `backend/app/routers/sync.py`
- [In-app assistant](https://github.com/keormel/safecall/blob/main/backend/app/services/assistant.py): `backend/app/services/assistant.py`
- [Gemini service](https://github.com/keormel/safecall/blob/main/backend/app/services/gemini.py): `backend/app/services/gemini.py`
- [Scheduled jobs](https://github.com/keormel/safecall/blob/main/backend/app/jobs.py): `backend/app/jobs.py`
- [Domain records](https://github.com/keormel/safecall/blob/main/backend/app/models.py): `backend/app/models.py`
- [PostgreSQL](https://github.com/keormel/safecall/blob/main/backend/app/db.py): `backend/app/db.py`

### Administration

- [Admin console](https://github.com/keormel/safecall/blob/main/admin-morda-sasha/frontend/src/App.tsx): `admin-morda-sasha/frontend/src/App.tsx`
- [Admin API client](https://github.com/keormel/safecall/blob/main/admin-morda-sasha/frontend/src/api/client.ts): `admin-morda-sasha/frontend/src/api/client.ts`
- [Admin API](https://github.com/keormel/safecall/blob/main/admin-morda-sasha/app/main.py): `admin-morda-sasha/app/main.py`
- [Admin data access](https://github.com/keormel/safecall/blob/main/admin-morda-sasha/app/db_client.py): `admin-morda-sasha/app/db_client.py`

### Other components

- **Caller**

## Connections

- Caller → Call screening: incoming call
- Call screening → Local number DB: checks number (evidence: `mobile/android/app/src/main/kotlin/com/safecall/safecall/SafeCallScreeningService.kt`)
- Call screening → Call notices: shows notice (evidence: `mobile/android/app/src/main/kotlin/com/safecall/safecall/SafeCallScreeningService.kt`)
- Mobile app → Delta sync: fetches deltas
- Delta sync → Local number DB: updates local DB
- Mobile app → API routing: checks and reports
- iOS call directory → Local number DB: uses local data
- API routing → Device auth: routes requests (evidence: `backend/app/main.py`)
- API routing → Number checks: routes requests (evidence: `backend/app/main.py`)
- API routing → Report intake: routes requests (evidence: `backend/app/main.py`)
- API routing → Delta sync: routes requests (evidence: `backend/app/main.py`)
- Number checks → Report processing: checks number (evidence: `backend/app/routers/numbers.py`)
- Report intake → Report processing: records report
- Report processing → Fingerprinting: builds fingerprint (evidence: `backend/app/services/report_service.py`)
- Report processing → Risk scoring: recalculates risk (evidence: `backend/app/services/report_service.py`)
- Report processing → Campaign analysis: refreshes campaign (evidence: `backend/app/services/report_service.py`)
- Risk scoring → Domain records: reads and updates (evidence: `backend/app/services/risk_engine.py`)
- Campaign analysis → Domain records: assigns numbers (evidence: `backend/app/services/campaign_engine.py`)
- Report processing → PostgreSQL: persists report
- Delta sync → PostgreSQL: reads changed numbers (evidence: `backend/app/routers/sync.py`)
- Scheduled jobs → Risk scoring: recalculates scores (evidence: `backend/app/jobs.py`)
- Scheduled jobs → Campaign analysis: maintains campaigns (evidence: `backend/app/jobs.py`)
- In-app assistant → Gemini service: answers questions
- Fingerprinting → Gemini service: classifies complaints (evidence: `backend/app/services/fingerprint.py`)
- Admin console → Admin API client: uses API client (evidence: `admin-morda-sasha/frontend/src/App.tsx`)
- Admin API client → Admin API: sends requests
- Admin API → Admin data access: loads admin data
- Admin data access → PostgreSQL: reads shared records
