# kitsumed/shizucallrecorder architecture

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

- Interactive diagram: https://gitdiagram.com/kitsumed/shizucallrecorder
- Repository: https://github.com/kitsumed/shizucallrecorder

## Overview

ShizuCallRecorder is an Android call-recording app that uses Shizuku to obtain shell-level access for audio capture. Its main workflow detects a call, evaluates automatic-recording rules, starts a foreground recording session, and delegates capture and encoding to a shell-side engine. The README also documents codec choices, split uplink/downlink audio, call exclusions, and Shizuku security controls. Several subsystem paths are included from the repository tree and README, but their internal links are omitted where the sampled source does not establish them.

Main entry points: [`app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingForegroundService.kt`](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingForegroundService.kt) (Recording service), [`app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/recording/ShellRecordingEngine.kt`](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/recording/ShellRecordingEngine.kt) (Recording engine), [`app/src/main/java/com/kitsumed/shizucallrecorder/services/RecordingDecisionEngine.kt`](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/RecordingDecisionEngine.kt) (Recording rules), [`app/src/main/java/com/kitsumed/shizucallrecorder/data/call/EnrichedCallData.kt`](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/data/call/EnrichedCallData.kt) (Call metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and settings"]
  node_ui["App UI"]
  node_prefs[("Preferences<br/>[AppPreferences.kt]")]
  node_call_data["Call metadata"]
  node_phone_numbers["Number parsing"]
end

subgraph group_detection["Call detection"]
  node_orchestrator["Detection mode"]
  node_incall["Telecom calls<br/>[InCallService.kt]"]
  node_phone_state["Phone state"]
  node_decision["Recording rules"]
end

subgraph group_session["Recording control"]
  node_foreground["Recording service"]
  node_plan["Plan resolution"]
  node_session_state["Session state"]
  node_session_owner["Recording session"]
  node_notifications["Notifications"]
end

subgraph group_shell["Shell audio engine"]
  node_shell_service["Shell service<br/>[ShellService.kt]"]
  node_engine["Recording engine"]
  node_capture["Audio capture<br/>[IAudioCapture.kt]"]
  node_processing["PCM processing<br/>[PcmProcessor.kt]"]
  node_encoder["Audio encoding<br/>[AudioEncoder.kt]"]
end

subgraph group_platform["Android integration"]
  node_shizuku["Shizuku binding"]
  node_storage["Recording files<br/>[SafHelper.kt]"]
  node_permission["Permission checks"]
end

node_caller(("Phone events"))

node_caller -->|"reports calls"| node_incall
node_incall -->|"evaluates call"| node_decision
node_phone_state -->|"evaluates state"| node_decision
node_decision -->|"starts service"| node_foreground
node_decision -->|"reads rules"| node_prefs
node_foreground -->|"resolves plan"| node_plan
node_foreground -->|"starts server"| node_shizuku
node_shizuku -->|"binds service"| node_shell_service
node_foreground -->|"updates state"| node_session_state
node_foreground -->|"manages notices"| node_notifications
node_shell_service -->|"starts engine"| node_engine
node_engine -->|"reads audio"| node_capture
node_engine -->|"processes PCM"| node_processing
node_engine -->|"encodes audio"| node_encoder
node_ui -.->|"configures options"| node_prefs
node_engine -.->|"writes recordings"| node_storage
node_decision -.->|"produces metadata"| node_call_data
node_call_data -.->|"normalizes number"| node_phone_numbers
node_foreground -.->|"owns session"| node_session_owner
node_foreground -.->|"checks access"| node_permission

click node_ui "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/AppNavigationScreen.kt"
click node_prefs "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/data/AppPreferences.kt"
click node_call_data "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/data/call/EnrichedCallData.kt"
click node_phone_numbers "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/utils/PhoneNumberManager.kt"
click node_orchestrator "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/callDetection/CallDetectionOrchestrator.kt"
click node_incall "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/callDetection/incall/InCallService.kt"
click node_phone_state "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/callDetection/phoneState/PhoneStateSessionManager.kt"
click node_decision "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/RecordingDecisionEngine.kt"
click node_foreground "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingForegroundService.kt"
click node_plan "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingPlanResolver.kt"
click node_session_state "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingServiceState.kt"
click node_session_owner "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingSession.kt"
click node_notifications "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingNotificationHelper.kt"
click node_shizuku "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/integrations/shizuku/ShizukuConnectionManager.kt"
click node_shell_service "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/ShellService.kt"
click node_engine "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/recording/ShellRecordingEngine.kt"
click node_capture "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/recording/capture/IAudioCapture.kt"
click node_processing "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/recording/processing/PcmProcessor.kt"
click node_encoder "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/recording/encoding/AudioEncoder.kt"
click node_storage "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/system/storage/SafHelper.kt"
click node_permission "https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/system/permissions/PermissionChecks.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_ui,node_prefs,node_call_data,node_phone_numbers toneBlue
class node_orchestrator,node_incall,node_phone_state,node_decision toneAmber
class node_foreground,node_plan,node_session_state,node_session_owner,node_notifications toneMint
class node_shell_service,node_engine,node_capture,node_processing,node_encoder toneRose
class node_shizuku,node_storage,node_permission,node_caller toneIndigo
```

## Components

### App and settings

- [App UI](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/AppNavigationScreen.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/AppNavigationScreen.kt`
- [Preferences](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/data/AppPreferences.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/data/AppPreferences.kt`
- [Call metadata](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/data/call/EnrichedCallData.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/data/call/EnrichedCallData.kt`
- [Number parsing](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/utils/PhoneNumberManager.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/utils/PhoneNumberManager.kt`

### Call detection

- [Detection mode](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/callDetection/CallDetectionOrchestrator.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/services/callDetection/CallDetectionOrchestrator.kt`
- [Telecom calls](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/callDetection/incall/InCallService.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/services/callDetection/incall/InCallService.kt`
- [Phone state](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/callDetection/phoneState/PhoneStateSessionManager.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/services/callDetection/phoneState/PhoneStateSessionManager.kt`
- [Recording rules](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/RecordingDecisionEngine.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/services/RecordingDecisionEngine.kt`

### Recording control

- [Recording service](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingForegroundService.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingForegroundService.kt`
- [Plan resolution](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingPlanResolver.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingPlanResolver.kt`
- [Session state](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingServiceState.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingServiceState.kt`
- [Recording session](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingSession.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingSession.kt`
- [Notifications](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingNotificationHelper.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingNotificationHelper.kt`

### Shell audio engine

- [Shell service](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/ShellService.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/ShellService.kt`
- [Recording engine](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/recording/ShellRecordingEngine.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/recording/ShellRecordingEngine.kt`
- [Audio capture](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/recording/capture/IAudioCapture.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/recording/capture/IAudioCapture.kt`
- [PCM processing](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/recording/processing/PcmProcessor.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/recording/processing/PcmProcessor.kt`
- [Audio encoding](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/recording/encoding/AudioEncoder.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/recording/encoding/AudioEncoder.kt`

### Android integration

- [Shizuku binding](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/integrations/shizuku/ShizukuConnectionManager.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/integrations/shizuku/ShizukuConnectionManager.kt`
- [Recording files](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/system/storage/SafHelper.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/system/storage/SafHelper.kt`
- [Permission checks](https://github.com/kitsumed/shizucallrecorder/blob/main/app/src/main/java/com/kitsumed/shizucallrecorder/system/permissions/PermissionChecks.kt): `app/src/main/java/com/kitsumed/shizucallrecorder/system/permissions/PermissionChecks.kt`

### Other components

- **Phone events**

## Connections

- Phone events → Telecom calls: reports calls (evidence: `app/src/main/java/com/kitsumed/shizucallrecorder/services/callDetection/incall/InCallService.kt`)
- Telecom calls → Recording rules: evaluates call (evidence: `app/src/main/java/com/kitsumed/shizucallrecorder/services/callDetection/incall/InCallService.kt`)
- Phone state → Recording rules: evaluates state (evidence: `app/src/main/java/com/kitsumed/shizucallrecorder/services/callDetection/phoneState/PhoneStateSessionManager.kt`)
- Recording rules → Recording service: starts service (evidence: `app/src/main/java/com/kitsumed/shizucallrecorder/services/RecordingDecisionEngine.kt`)
- Recording rules → Preferences: reads rules (evidence: `app/src/main/java/com/kitsumed/shizucallrecorder/services/RecordingDecisionEngine.kt`)
- Recording service → Plan resolution: resolves plan (evidence: `app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingForegroundService.kt`)
- Recording service → Shizuku binding: starts server (evidence: `app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingForegroundService.kt`)
- Shizuku binding → Shell service: binds service (evidence: `app/src/main/java/com/kitsumed/shizucallrecorder/integrations/shizuku/ShizukuConnectionManager.kt`)
- Recording service → Session state: updates state (evidence: `app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingForegroundService.kt`)
- Recording service → Notifications: manages notices (evidence: `app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingForegroundService.kt`)
- Shell service → Recording engine: starts engine (evidence: `app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/ShellService.kt`)
- Recording engine → Audio capture: reads audio (evidence: `app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/recording/ShellRecordingEngine.kt`)
- Recording engine → PCM processing: processes PCM (evidence: `app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/recording/ShellRecordingEngine.kt`)
- Recording engine → Audio encoding: encodes audio (evidence: `app/src/main/java/com/kitsumed/shizucallrecorder/services/shell/recording/ShellRecordingEngine.kt`)
- App UI → Preferences: configures options
- Recording engine → Recording files: writes recordings
- Recording rules → Call metadata: produces metadata (evidence: `app/src/main/java/com/kitsumed/shizucallrecorder/services/RecordingDecisionEngine.kt`)
- Call metadata → Number parsing: normalizes number (evidence: `app/src/main/java/com/kitsumed/shizucallrecorder/data/call/EnrichedCallData.kt`)
- Recording service → Recording session: owns session (evidence: `app/src/main/java/com/kitsumed/shizucallrecorder/services/recording/RecordingForegroundService.kt`)
- Recording service → Permission checks: checks access