# sharko2025/note-voice architecture

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

- Interactive diagram: https://gitdiagram.com/sharko2025/note-voice
- Repository: https://github.com/sharko2025/note-voice

## Overview

Note Cá Mập is a voice-first Android task and notes app backed by a FastAPI service. The main workflow records speech, queues it for upload, and the backend transcribes and parses it into normalized tasks or notes; users can then manage those results and reminders. The graph also covers typed task/note APIs, local caching, offline upload support, and reminder scheduling. Edges follow excerpts, source-index references, or API endpoint declarations; unsampled implementations and undocumented links are not inferred.

Main entry points: [`backend/app/routers/voice.py`](https://github.com/sharko2025/note-voice/blob/main/backend/app/routers/voice.py) (Voice endpoint), [`android/app/src/main/java/com/sitpro/notevoice/AppContainer.kt`](https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/AppContainer.kt) (App services), [`android/app/src/main/java/com/sitpro/notevoice/api/ApiService.kt`](https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/api/ApiService.kt) (API client), [`backend/app/main.py`](https://github.com/sharko2025/note-voice/blob/main/backend/app/main.py) (API application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android["Android app"]
  node_activity["Activity entry<br/>[MainActivity.kt]"]
  node_app_shell["App shell<br/>[AppShell.kt]"]
  node_viewmodels["Screen state<br/>[MainViewModel.kt]"]
  node_recording["Recording controller"]
  node_recorder["Audio capture<br/>[Recorder.kt]"]
  node_silence["Speech detection<br/>[SilenceDetector.kt]"]
  node_container["App services<br/>[AppContainer.kt]"]
end

subgraph group_sync["Sync and reminders"]
  node_api_client["API client<br/>[ApiService.kt]"]
  node_upload["Upload processor<br/>[UploadProcessor.kt]"]
  node_result_router["Result routing<br/>[ResultRouter.kt]"]
  node_reminder_scheduler["Reminder scheduling"]
  node_reminder_notifier["Reminder notifications"]
end

subgraph group_backend["Backend API"]
  node_api_entry["API application<br/>[main.py]"]
  node_auth["Token authentication<br/>[auth.py]"]
  node_voice_routes["Voice endpoint<br/>[voice.py]"]
  node_task_routes["Task endpoints<br/>[tasks.py]"]
  node_note_routes["Note endpoints<br/>[notes.py]"]
end

subgraph group_processing["Voice processing"]
  node_voice_service["Voice workflow<br/>[voice.py]"]
  node_stt["Speech transcription<br/>[stt.py]"]
  node_parser["Task and note parser<br/>[parser.py]"]
  node_normalize["Result normalization<br/>[normalize.py]"]
end

subgraph group_storage["Data storage"]
  node_local_data[("Local cache and queue<br/>[AppDatabase.kt]")]
  node_backend_db["Database connection<br/>[db.py]"]
  node_models[("Task and note records<br/>[models.py]")]
end

node_user(("User"))
node_openai{{"OpenAI services"}}

node_user -->|"uses"| node_activity
node_activity -->|"shows"| node_app_shell
node_activity -->|"creates"| node_viewmodels
node_activity -->|"starts"| node_recording
node_app_shell -->|"observes"| node_viewmodels
node_recording -->|"captures audio"| node_recorder
node_recording -->|"detects speech"| node_silence
node_recording -->|"submits recording"| node_container
node_container -->|"stores uploads"| node_local_data
node_container -->|"creates client"| node_api_client
node_container -->|"configures"| node_upload
node_container -->|"configures"| node_result_router
node_container -->|"configures"| node_reminder_scheduler
node_reminder_scheduler -->|"reads reminders"| node_local_data
node_reminder_scheduler -->|"notifies"| node_reminder_notifier
node_upload -->|"uploads recording"| node_api_client
node_api_client -->|"posts voice"| node_voice_routes
node_api_client -->|"calls task APIs"| node_task_routes
node_api_client -->|"calls note APIs"| node_note_routes
node_api_entry -->|"protects routes"| node_auth
node_api_entry -->|"registers"| node_voice_routes
node_api_entry -->|"registers"| node_task_routes
node_api_entry -->|"registers"| node_note_routes
node_voice_routes -->|"delegates"| node_voice_service
node_voice_routes -->|"uses session"| node_backend_db
node_voice_routes -->|"uses parser"| node_parser
node_voice_routes -->|"uses transcription"| node_stt
node_voice_routes -->|"persists records"| node_models
node_task_routes -->|"queries"| node_backend_db
node_task_routes -->|"reads and writes"| node_models
node_note_routes -->|"uses session"| node_backend_db
node_note_routes -->|"reads and writes"| node_models
node_voice_service -->|"transcribes"| node_stt
node_voice_service -->|"parses transcript"| node_parser
node_voice_service -->|"normalizes results"| node_normalize
node_stt -->|"requests transcription"| node_openai
node_parser -->|"requests structured parse"| node_openai

click node_activity "https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/MainActivity.kt"
click node_app_shell "https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/ui/AppShell.kt"
click node_viewmodels "https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/ui/MainViewModel.kt"
click node_recording "https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/ui/RecordController.kt"
click node_recorder "https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/audio/Recorder.kt"
click node_silence "https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/audio/SilenceDetector.kt"
click node_container "https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/AppContainer.kt"
click node_api_client "https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/api/ApiService.kt"
click node_local_data "https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/data/AppDatabase.kt"
click node_upload "https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/sync/UploadProcessor.kt"
click node_result_router "https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/sync/ResultRouter.kt"
click node_reminder_scheduler "https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/reminder/ReminderScheduler.kt"
click node_reminder_notifier "https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/notify/ReminderNotifier.kt"
click node_api_entry "https://github.com/sharko2025/note-voice/blob/main/backend/app/main.py"
click node_auth "https://github.com/sharko2025/note-voice/blob/main/backend/app/auth.py"
click node_voice_routes "https://github.com/sharko2025/note-voice/blob/main/backend/app/routers/voice.py"
click node_task_routes "https://github.com/sharko2025/note-voice/blob/main/backend/app/routers/tasks.py"
click node_note_routes "https://github.com/sharko2025/note-voice/blob/main/backend/app/routers/notes.py"
click node_voice_service "https://github.com/sharko2025/note-voice/blob/main/backend/app/services/voice.py"
click node_stt "https://github.com/sharko2025/note-voice/blob/main/backend/app/services/stt.py"
click node_parser "https://github.com/sharko2025/note-voice/blob/main/backend/app/services/parser.py"
click node_normalize "https://github.com/sharko2025/note-voice/blob/main/backend/app/services/normalize.py"
click node_backend_db "https://github.com/sharko2025/note-voice/blob/main/backend/app/db.py"
click node_models "https://github.com/sharko2025/note-voice/blob/main/backend/app/models.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_activity,node_app_shell,node_viewmodels,node_recording,node_recorder,node_silence,node_container,node_user toneBlue
class node_api_client,node_upload,node_result_router,node_reminder_scheduler,node_reminder_notifier toneAmber
class node_api_entry,node_auth,node_voice_routes,node_task_routes,node_note_routes toneMint
class node_voice_service,node_stt,node_parser,node_normalize toneRose
class node_local_data,node_backend_db,node_models,node_openai toneIndigo
```

## Components

### Android app

- [Activity entry](https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/MainActivity.kt): `android/app/src/main/java/com/sitpro/notevoice/MainActivity.kt`
- [App shell](https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/ui/AppShell.kt): `android/app/src/main/java/com/sitpro/notevoice/ui/AppShell.kt`
- [Screen state](https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/ui/MainViewModel.kt): `android/app/src/main/java/com/sitpro/notevoice/ui/MainViewModel.kt`
- [Recording controller](https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/ui/RecordController.kt): `android/app/src/main/java/com/sitpro/notevoice/ui/RecordController.kt`
- [Audio capture](https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/audio/Recorder.kt): `android/app/src/main/java/com/sitpro/notevoice/audio/Recorder.kt`
- [Speech detection](https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/audio/SilenceDetector.kt): `android/app/src/main/java/com/sitpro/notevoice/audio/SilenceDetector.kt`
- [App services](https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/AppContainer.kt): `android/app/src/main/java/com/sitpro/notevoice/AppContainer.kt`

### Sync and reminders

- [API client](https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/api/ApiService.kt): `android/app/src/main/java/com/sitpro/notevoice/api/ApiService.kt`
- [Upload processor](https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/sync/UploadProcessor.kt): `android/app/src/main/java/com/sitpro/notevoice/sync/UploadProcessor.kt`
- [Result routing](https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/sync/ResultRouter.kt): `android/app/src/main/java/com/sitpro/notevoice/sync/ResultRouter.kt`
- [Reminder scheduling](https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/reminder/ReminderScheduler.kt): `android/app/src/main/java/com/sitpro/notevoice/reminder/ReminderScheduler.kt`
- [Reminder notifications](https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/notify/ReminderNotifier.kt): `android/app/src/main/java/com/sitpro/notevoice/notify/ReminderNotifier.kt`

### Backend API

- [API application](https://github.com/sharko2025/note-voice/blob/main/backend/app/main.py): `backend/app/main.py`
- [Token authentication](https://github.com/sharko2025/note-voice/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [Voice endpoint](https://github.com/sharko2025/note-voice/blob/main/backend/app/routers/voice.py): `backend/app/routers/voice.py`
- [Task endpoints](https://github.com/sharko2025/note-voice/blob/main/backend/app/routers/tasks.py): `backend/app/routers/tasks.py`
- [Note endpoints](https://github.com/sharko2025/note-voice/blob/main/backend/app/routers/notes.py): `backend/app/routers/notes.py`

### Voice processing

- [Voice workflow](https://github.com/sharko2025/note-voice/blob/main/backend/app/services/voice.py): `backend/app/services/voice.py`
- [Speech transcription](https://github.com/sharko2025/note-voice/blob/main/backend/app/services/stt.py): `backend/app/services/stt.py`
- [Task and note parser](https://github.com/sharko2025/note-voice/blob/main/backend/app/services/parser.py): `backend/app/services/parser.py`
- [Result normalization](https://github.com/sharko2025/note-voice/blob/main/backend/app/services/normalize.py): `backend/app/services/normalize.py`

### Data storage

- [Local cache and queue](https://github.com/sharko2025/note-voice/blob/main/android/app/src/main/java/com/sitpro/notevoice/data/AppDatabase.kt): `android/app/src/main/java/com/sitpro/notevoice/data/AppDatabase.kt`
- [Database connection](https://github.com/sharko2025/note-voice/blob/main/backend/app/db.py): `backend/app/db.py`
- [Task and note records](https://github.com/sharko2025/note-voice/blob/main/backend/app/models.py): `backend/app/models.py`

### Other components

- **User**
- **OpenAI services**

## Connections

- User → Activity entry: uses
- Activity entry → App shell: shows (evidence: `android/app/src/main/java/com/sitpro/notevoice/MainActivity.kt`)
- Activity entry → Screen state: creates (evidence: `android/app/src/main/java/com/sitpro/notevoice/MainActivity.kt`)
- Activity entry → Recording controller: starts (evidence: `android/app/src/main/java/com/sitpro/notevoice/MainActivity.kt`)
- App shell → Screen state: observes (evidence: `android/app/src/main/java/com/sitpro/notevoice/ui/AppShell.kt`)
- Recording controller → Audio capture: captures audio (evidence: `android/app/src/main/java/com/sitpro/notevoice/ui/RecordController.kt`)
- Recording controller → Speech detection: detects speech (evidence: `android/app/src/main/java/com/sitpro/notevoice/ui/RecordController.kt`)
- Recording controller → App services: submits recording (evidence: `android/app/src/main/java/com/sitpro/notevoice/ui/RecordController.kt`)
- App services → Local cache and queue: stores uploads (evidence: `android/app/src/main/java/com/sitpro/notevoice/AppContainer.kt`)
- App services → API client: creates client (evidence: `android/app/src/main/java/com/sitpro/notevoice/AppContainer.kt`)
- App services → Upload processor: configures (evidence: `android/app/src/main/java/com/sitpro/notevoice/AppContainer.kt`)
- App services → Result routing: configures (evidence: `android/app/src/main/java/com/sitpro/notevoice/AppContainer.kt`)
- App services → Reminder scheduling: configures (evidence: `android/app/src/main/java/com/sitpro/notevoice/AppContainer.kt`)
- Reminder scheduling → Local cache and queue: reads reminders (evidence: `android/app/src/main/java/com/sitpro/notevoice/reminder/ReminderScheduler.kt`)
- Reminder scheduling → Reminder notifications: notifies (evidence: `android/app/src/main/java/com/sitpro/notevoice/reminder/ReminderScheduler.kt`)
- Upload processor → API client: uploads recording (evidence: `android/app/src/main/java/com/sitpro/notevoice/sync/UploadProcessor.kt`)
- API client → Voice endpoint: posts voice (evidence: `android/app/src/main/java/com/sitpro/notevoice/api/ApiService.kt`)
- API client → Task endpoints: calls task APIs (evidence: `android/app/src/main/java/com/sitpro/notevoice/api/ApiService.kt`)
- API client → Note endpoints: calls note APIs (evidence: `android/app/src/main/java/com/sitpro/notevoice/api/ApiService.kt`)
- API application → Token authentication: protects routes (evidence: `backend/app/main.py`)
- API application → Voice endpoint: registers (evidence: `backend/app/main.py`)
- API application → Task endpoints: registers (evidence: `backend/app/main.py`)
- API application → Note endpoints: registers (evidence: `backend/app/main.py`)
- Voice endpoint → Voice workflow: delegates (evidence: `backend/app/routers/voice.py`)
- Voice endpoint → Database connection: uses session (evidence: `backend/app/routers/voice.py`)
- Voice endpoint → Task and note parser: uses parser (evidence: `backend/app/routers/voice.py`)
- Voice endpoint → Speech transcription: uses transcription (evidence: `backend/app/routers/voice.py`)
- Voice endpoint → Task and note records: persists records (evidence: `backend/app/routers/voice.py`)
- Task endpoints → Database connection: queries (evidence: `backend/app/routers/tasks.py`)
- Task endpoints → Task and note records: reads and writes (evidence: `backend/app/routers/tasks.py`)
- Note endpoints → Database connection: uses session (evidence: `backend/app/routers/notes.py`)
- Note endpoints → Task and note records: reads and writes (evidence: `backend/app/routers/notes.py`)
- Voice workflow → Speech transcription: transcribes (evidence: `backend/app/services/voice.py`)
- Voice workflow → Task and note parser: parses transcript (evidence: `backend/app/services/voice.py`)
- Voice workflow → Result normalization: normalizes results (evidence: `backend/app/services/voice.py`)
- Speech transcription → OpenAI services: requests transcription (evidence: `backend/app/services/stt.py`)
- Task and note parser → OpenAI services: requests structured parse (evidence: `backend/app/services/parser.py`)