# hcmdz/privnum architecture

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

- Interactive diagram: https://gitdiagram.com/hcmdz/privnum
- Repository: https://github.com/hcmdz/privnum

## Overview

Privnum is an offline Android private caller-ID and contact manager. Users keep multi-number contacts in encrypted app-local storage, then search, view, edit, import/export, or share them; incoming-call identification and on-demand call history are separate paths, with history matching against saved contacts. Settings cover language, appearance, security, and caller behavior. The graph follows documented capabilities and sampled imports/calls; some caller integrations and unsampled feature internals are represented only where the README supports them, otherwise links are omitted.

Main entry points: [`app/src/main/java/com/hcmdz/privnum/AppNav.kt`](https://github.com/hcmdz/privnum/blob/main/app/src/main/java/com/hcmdz/privnum/AppNav.kt) (App navigation), [`core/data/src/main/java/com/hcmdz/privnum/data/ContactRepository.kt`](https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/ContactRepository.kt) (Contact repository), [`feature/editor/src/main/java/com/hcmdz/privnum/editor/EditorScreen.kt`](https://github.com/hcmdz/privnum/blob/main/feature/editor/src/main/java/com/hcmdz/privnum/editor/EditorScreen.kt) (Contact editor), [`feature/preview/src/main/java/com/hcmdz/privnum/preview/PreviewScreen.kt`](https://github.com/hcmdz/privnum/blob/main/feature/preview/src/main/java/com/hcmdz/privnum/preview/PreviewScreen.kt) (Contact details)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App navigation"]
  node_main_activity["Main activity<br/>[MainActivity.kt]"]
  node_navigation["App navigation<br/>[AppNav.kt]"]
end

subgraph group_contacts["Contact workflows"]
  node_contacts_ui["Contact list<br/>[ContactsScreen.kt]"]
  node_search_ui["Contact search<br/>[SearchScreen.kt]"]
  node_editor_ui["Contact editor<br/>[EditorScreen.kt]"]
  node_preview_ui["Contact details<br/>[PreviewScreen.kt]"]
  node_vcf["VCF mapping<br/>[VcfMapper.kt]"]
end

subgraph group_data["Local data and security"]
  node_contact_model["Contact model<br/>[Contact.kt]"]
  node_phone_numbers["Number parsing"]
  node_contact_repository["Contact repository"]
  node_contact_dao["Contact DAO<br/>[ContactDao.kt]"]
  node_contact_db[("Encrypted contact database<br/>[PrivnumDatabase.kt]")]
  node_photo_store[("Encrypted photo store")]
end

subgraph group_calling["Caller and history"]
  node_caller_service["Call screening"]
  node_call_receiver["Call event receiver<br/>[CallReceiver.kt]"]
  node_directory_provider["Call directory provider"]
  node_call_history["Call history reader"]
  node_call_log_source["System call log"]
  node_history_ui["Call history screen<br/>[HistoryScreen.kt]"]
end

subgraph group_preferences["Settings and presentation"]
  node_settings_ui["Settings screen<br/>[SettingsScreen.kt]"]
  node_settings_store[("Preferences store<br/>[SettingsStore.kt]")]
  node_lock_ui["App lock<br/>[LockScreen.kt]"]
  node_passcode_store[("Passcode and biometrics<br/>[PasscodeStore.kt]")]
  node_ui_helpers["Shared UI helpers<br/>[ContactAvatar.kt]"]
end

node_user(("App user"))
node_android_calls(("Android call system"))
node_external_apps(("Phone and messaging apps"))

node_user -->|"opens"| node_main_activity
node_main_activity -->|"starts"| node_navigation
node_navigation -->|"routes to"| node_contacts_ui
node_navigation -->|"routes to"| node_search_ui
node_navigation -->|"routes to"| node_editor_ui
node_navigation -->|"routes to"| node_preview_ui
node_navigation -->|"routes to"| node_history_ui
node_navigation -->|"routes to"| node_settings_ui
node_navigation -->|"routes to"| node_lock_ui
node_contacts_ui -->|"imports exports"| node_vcf
node_preview_ui -->|"launches actions"| node_external_apps
node_contacts_ui -->|"uses model"| node_contact_model
node_editor_ui -->|"formats numbers"| node_phone_numbers
node_editor_ui -->|"renders avatars"| node_ui_helpers
node_preview_ui -->|"renders avatars"| node_ui_helpers
node_editor_ui -->|"saves contacts"| node_contact_repository
node_search_ui -->|"searches contacts"| node_contact_repository
node_preview_ui -->|"loads deletes"| node_contact_repository
node_contact_repository -->|"queries writes"| node_contact_dao
node_contact_repository -->|"opens"| node_contact_db
node_contact_repository -->|"manages photos"| node_photo_store
node_editor_ui -->|"stores photos"| node_photo_store
node_caller_service -->|"screens calls"| node_android_calls
node_caller_service -->|"references"| node_call_receiver
node_directory_provider -.->|"looks up callers"| node_contact_repository
node_call_history -->|"reads entries"| node_call_log_source
node_call_history -->|"matches numbers"| node_contact_repository
node_call_history -->|"reads region"| node_settings_store
node_history_ui -.->|"shows recent calls"| node_call_history
node_settings_ui -->|"updates preferences"| node_settings_store
node_settings_ui -->|"configures lock"| node_passcode_store
node_lock_ui -->|"verifies passcode"| node_passcode_store
node_settings_ui -.->|"configures caller ID"| node_caller_service

click node_main_activity "https://github.com/hcmdz/privnum/blob/main/app/src/main/java/com/hcmdz/privnum/MainActivity.kt"
click node_navigation "https://github.com/hcmdz/privnum/blob/main/app/src/main/java/com/hcmdz/privnum/AppNav.kt"
click node_contacts_ui "https://github.com/hcmdz/privnum/blob/main/feature/contacts/src/main/java/com/hcmdz/privnum/contacts/ContactsScreen.kt"
click node_search_ui "https://github.com/hcmdz/privnum/blob/main/feature/search/src/main/java/com/hcmdz/privnum/search/SearchScreen.kt"
click node_editor_ui "https://github.com/hcmdz/privnum/blob/main/feature/editor/src/main/java/com/hcmdz/privnum/editor/EditorScreen.kt"
click node_preview_ui "https://github.com/hcmdz/privnum/blob/main/feature/preview/src/main/java/com/hcmdz/privnum/preview/PreviewScreen.kt"
click node_vcf "https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/VcfMapper.kt"
click node_contact_model "https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/Contact.kt"
click node_phone_numbers "https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/PhoneNumberUtils.kt"
click node_contact_repository "https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/ContactRepository.kt"
click node_contact_dao "https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/db/ContactDao.kt"
click node_contact_db "https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/db/PrivnumDatabase.kt"
click node_photo_store "https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/ContactPhotoStore.kt"
click node_caller_service "https://github.com/hcmdz/privnum/blob/main/core/caller/src/main/java/com/hcmdz/privnum/caller/CallDetectScreeningService.kt"
click node_call_receiver "https://github.com/hcmdz/privnum/blob/main/core/caller/src/main/java/com/hcmdz/privnum/caller/CallReceiver.kt"
click node_directory_provider "https://github.com/hcmdz/privnum/blob/main/core/caller/src/main/java/com/hcmdz/privnum/caller/CallDirectoryProvider.kt"
click node_call_history "https://github.com/hcmdz/privnum/blob/main/core/caller/src/main/java/com/hcmdz/privnum/caller/CallHistoryRepository.kt"
click node_call_log_source "https://github.com/hcmdz/privnum/blob/main/core/caller/src/main/java/com/hcmdz/privnum/caller/CallLogDataSource.kt"
click node_history_ui "https://github.com/hcmdz/privnum/blob/main/feature/calllog/src/main/java/com/hcmdz/privnum/calllog/HistoryScreen.kt"
click node_settings_ui "https://github.com/hcmdz/privnum/blob/main/feature/settings/src/main/java/com/hcmdz/privnum/settings/SettingsScreen.kt"
click node_settings_store "https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/SettingsStore.kt"
click node_lock_ui "https://github.com/hcmdz/privnum/blob/main/feature/lock/src/main/java/com/hcmdz/privnum/lock/LockScreen.kt"
click node_passcode_store "https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/PasscodeStore.kt"
click node_ui_helpers "https://github.com/hcmdz/privnum/blob/main/core/ui/src/main/java/com/hcmdz/privnum/ui/ContactAvatar.kt"

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_main_activity,node_navigation,node_user toneBlue
class node_contacts_ui,node_search_ui,node_editor_ui,node_preview_ui,node_vcf toneAmber
class node_contact_model,node_phone_numbers,node_contact_repository,node_contact_dao,node_contact_db,node_photo_store toneMint
class node_caller_service,node_call_receiver,node_directory_provider,node_call_history,node_call_log_source,node_history_ui toneRose
class node_settings_ui,node_settings_store,node_lock_ui,node_passcode_store,node_ui_helpers,node_android_calls,node_external_apps toneIndigo
```

## Components

### App navigation

- [Main activity](https://github.com/hcmdz/privnum/blob/main/app/src/main/java/com/hcmdz/privnum/MainActivity.kt): `app/src/main/java/com/hcmdz/privnum/MainActivity.kt`
- [App navigation](https://github.com/hcmdz/privnum/blob/main/app/src/main/java/com/hcmdz/privnum/AppNav.kt): `app/src/main/java/com/hcmdz/privnum/AppNav.kt`

### Contact workflows

- [Contact list](https://github.com/hcmdz/privnum/blob/main/feature/contacts/src/main/java/com/hcmdz/privnum/contacts/ContactsScreen.kt): `feature/contacts/src/main/java/com/hcmdz/privnum/contacts/ContactsScreen.kt`
- [Contact search](https://github.com/hcmdz/privnum/blob/main/feature/search/src/main/java/com/hcmdz/privnum/search/SearchScreen.kt): `feature/search/src/main/java/com/hcmdz/privnum/search/SearchScreen.kt`
- [Contact editor](https://github.com/hcmdz/privnum/blob/main/feature/editor/src/main/java/com/hcmdz/privnum/editor/EditorScreen.kt): `feature/editor/src/main/java/com/hcmdz/privnum/editor/EditorScreen.kt`
- [Contact details](https://github.com/hcmdz/privnum/blob/main/feature/preview/src/main/java/com/hcmdz/privnum/preview/PreviewScreen.kt): `feature/preview/src/main/java/com/hcmdz/privnum/preview/PreviewScreen.kt`
- [VCF mapping](https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/VcfMapper.kt): `core/data/src/main/java/com/hcmdz/privnum/data/VcfMapper.kt`

### Local data and security

- [Contact model](https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/Contact.kt): `core/data/src/main/java/com/hcmdz/privnum/data/Contact.kt`
- [Number parsing](https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/PhoneNumberUtils.kt): `core/data/src/main/java/com/hcmdz/privnum/data/PhoneNumberUtils.kt`
- [Contact repository](https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/ContactRepository.kt): `core/data/src/main/java/com/hcmdz/privnum/data/ContactRepository.kt`
- [Contact DAO](https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/db/ContactDao.kt): `core/data/src/main/java/com/hcmdz/privnum/data/db/ContactDao.kt`
- [Encrypted contact database](https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/db/PrivnumDatabase.kt): `core/data/src/main/java/com/hcmdz/privnum/data/db/PrivnumDatabase.kt`
- [Encrypted photo store](https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/ContactPhotoStore.kt): `core/data/src/main/java/com/hcmdz/privnum/data/ContactPhotoStore.kt`

### Caller and history

- [Call screening](https://github.com/hcmdz/privnum/blob/main/core/caller/src/main/java/com/hcmdz/privnum/caller/CallDetectScreeningService.kt): `core/caller/src/main/java/com/hcmdz/privnum/caller/CallDetectScreeningService.kt`
- [Call event receiver](https://github.com/hcmdz/privnum/blob/main/core/caller/src/main/java/com/hcmdz/privnum/caller/CallReceiver.kt): `core/caller/src/main/java/com/hcmdz/privnum/caller/CallReceiver.kt`
- [Call directory provider](https://github.com/hcmdz/privnum/blob/main/core/caller/src/main/java/com/hcmdz/privnum/caller/CallDirectoryProvider.kt): `core/caller/src/main/java/com/hcmdz/privnum/caller/CallDirectoryProvider.kt`
- [Call history reader](https://github.com/hcmdz/privnum/blob/main/core/caller/src/main/java/com/hcmdz/privnum/caller/CallHistoryRepository.kt): `core/caller/src/main/java/com/hcmdz/privnum/caller/CallHistoryRepository.kt`
- [System call log](https://github.com/hcmdz/privnum/blob/main/core/caller/src/main/java/com/hcmdz/privnum/caller/CallLogDataSource.kt): `core/caller/src/main/java/com/hcmdz/privnum/caller/CallLogDataSource.kt`
- [Call history screen](https://github.com/hcmdz/privnum/blob/main/feature/calllog/src/main/java/com/hcmdz/privnum/calllog/HistoryScreen.kt): `feature/calllog/src/main/java/com/hcmdz/privnum/calllog/HistoryScreen.kt`

### Settings and presentation

- [Settings screen](https://github.com/hcmdz/privnum/blob/main/feature/settings/src/main/java/com/hcmdz/privnum/settings/SettingsScreen.kt): `feature/settings/src/main/java/com/hcmdz/privnum/settings/SettingsScreen.kt`
- [Preferences store](https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/SettingsStore.kt): `core/data/src/main/java/com/hcmdz/privnum/data/SettingsStore.kt`
- [App lock](https://github.com/hcmdz/privnum/blob/main/feature/lock/src/main/java/com/hcmdz/privnum/lock/LockScreen.kt): `feature/lock/src/main/java/com/hcmdz/privnum/lock/LockScreen.kt`
- [Passcode and biometrics](https://github.com/hcmdz/privnum/blob/main/core/data/src/main/java/com/hcmdz/privnum/data/PasscodeStore.kt): `core/data/src/main/java/com/hcmdz/privnum/data/PasscodeStore.kt`
- [Shared UI helpers](https://github.com/hcmdz/privnum/blob/main/core/ui/src/main/java/com/hcmdz/privnum/ui/ContactAvatar.kt): `core/ui/src/main/java/com/hcmdz/privnum/ui/ContactAvatar.kt`

### Other components

- **App user**
- **Android call system**
- **Phone and messaging apps**

## Connections

- App user → Main activity: opens (evidence: `README.md`)
- Main activity → App navigation: starts (evidence: `app/src/main/java/com/hcmdz/privnum/MainActivity.kt`)
- App navigation → Contact list: routes to (evidence: `app/src/main/java/com/hcmdz/privnum/AppNav.kt`)
- App navigation → Contact search: routes to (evidence: `app/src/main/java/com/hcmdz/privnum/AppNav.kt`)
- App navigation → Contact editor: routes to (evidence: `app/src/main/java/com/hcmdz/privnum/AppNav.kt`)
- App navigation → Contact details: routes to (evidence: `app/src/main/java/com/hcmdz/privnum/AppNav.kt`)
- App navigation → Call history screen: routes to (evidence: `app/src/main/java/com/hcmdz/privnum/AppNav.kt`)
- App navigation → Settings screen: routes to (evidence: `app/src/main/java/com/hcmdz/privnum/AppNav.kt`)
- App navigation → App lock: routes to (evidence: `app/src/main/java/com/hcmdz/privnum/AppNav.kt`)
- Contact list → VCF mapping: imports exports (evidence: `feature/contacts/src/main/java/com/hcmdz/privnum/contacts/ContactsScreen.kt`)
- Contact details → Phone and messaging apps: launches actions (evidence: `feature/preview/src/main/java/com/hcmdz/privnum/preview/PreviewScreen.kt`)
- Contact list → Contact model: uses model (evidence: `feature/contacts/src/main/java/com/hcmdz/privnum/contacts/ContactsScreen.kt`)
- Contact editor → Number parsing: formats numbers (evidence: `feature/editor/src/main/java/com/hcmdz/privnum/editor/EditorScreen.kt`)
- Contact editor → Shared UI helpers: renders avatars (evidence: `feature/editor/src/main/java/com/hcmdz/privnum/editor/EditorScreen.kt`)
- Contact details → Shared UI helpers: renders avatars (evidence: `feature/preview/src/main/java/com/hcmdz/privnum/preview/PreviewScreen.kt`)
- Contact editor → Contact repository: saves contacts
- Contact search → Contact repository: searches contacts
- Contact details → Contact repository: loads deletes
- Contact repository → Contact DAO: queries writes (evidence: `core/data/src/main/java/com/hcmdz/privnum/data/ContactRepository.kt`)
- Contact repository → Encrypted contact database: opens (evidence: `core/data/src/main/java/com/hcmdz/privnum/data/ContactRepository.kt`)
- Contact repository → Encrypted photo store: manages photos (evidence: `core/data/src/main/java/com/hcmdz/privnum/data/ContactRepository.kt`)
- Contact editor → Encrypted photo store: stores photos
- Call screening → Android call system: screens calls (evidence: `README.md`)
- Call screening → Call event receiver: references (evidence: `core/caller/src/main/java/com/hcmdz/privnum/caller/CallDetectScreeningService.kt`)
- Call directory provider → Contact repository: looks up callers
- Call history reader → System call log: reads entries (evidence: `core/caller/src/main/java/com/hcmdz/privnum/caller/CallHistoryRepository.kt`)
- Call history reader → Contact repository: matches numbers (evidence: `core/caller/src/main/java/com/hcmdz/privnum/caller/CallHistoryRepository.kt`)
- Call history reader → Preferences store: reads region (evidence: `core/caller/src/main/java/com/hcmdz/privnum/caller/CallHistoryRepository.kt`)
- Call history screen → Call history reader: shows recent calls
- Settings screen → Preferences store: updates preferences
- Settings screen → Passcode and biometrics: configures lock
- App lock → Passcode and biometrics: verifies passcode
- Settings screen → Call screening: configures caller ID
