# chinhean/natify-app architecture

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

- Interactive diagram: https://gitdiagram.com/chinhean/natify-app
- Repository: https://github.com/chinhean/natify-app

## Overview

Natify is a Streamlit Indonesian-pronunciation coach. A learner selects a difficulty and sentence, listens to reference audio, records an attempt, and receives speech-recognition, phoneme, and acoustic feedback; session counters track attempts and success. The README also describes visual comparison and custom sentence collections. The graph follows the documented workflow and sampled entry, data, and analysis code; some UI-to-analysis wiring and unsampled capabilities are shown only where the app structure or README supports them.

Main entry points: [`app/main.py`](https://github.com/chinhean/natify-app/blob/master/app/main.py) (Streamlit app), [`app/ml_logic/speech.py`](https://github.com/chinhean/natify-app/blob/master/app/ml_logic/speech.py) (Speech recognition), [`app/interface/audio.py`](https://github.com/chinhean/natify-app/blob/master/app/interface/audio.py) (Recording and playback), [`app/interface/feedback.py`](https://github.com/chinhean/natify-app/blob/master/app/interface/feedback.py) (Feedback display)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Practice experience"]
  node_main["Streamlit app<br/>[main.py]"]
  node_sidebar["Practice settings<br/>[sidebar.py]"]
  node_audio_ui["Recording and playback<br/>[audio.py]"]
  node_feedback["Feedback display<br/>[feedback.py]"]
end

subgraph group_content["Sentence and audio data"]
  node_sentences["Sentence catalog<br/>[sentences.py]"]
  node_gcs_data["Cloud data access<br/>[gcs.py]"]
  node_phoneme_data["Phoneme guidance<br/>[phonemes.py]"]
end

subgraph group_analysis["Pronunciation analysis"]
  node_audio_processing["Audio preparation"]
  node_models["Model loading<br/>[models.py]"]
  node_speech["Speech recognition<br/>[speech.py]"]
  node_phonemes["Phoneme analysis<br/>[phonemes.py]"]
  node_acoustic["Acoustic comparison"]
  node_translations["Translation utilities<br/>[translations.py]"]
end

subgraph group_state["Session progress"]
  node_state[("Practice state<br/>[session_state.py]")]
end

node_learner(("Learner"))
node_gcs[("Google Cloud Storage")]
node_speech_service(("Speech recognition service"))

node_learner -->|"uses"| node_main
node_main -->|"renders"| node_sidebar
node_main -->|"initializes"| node_state
node_main -->|"loads sentences"| node_gcs_data
node_gcs_data -.->|"reads sentence data"| node_gcs
node_main -->|"selects practice"| node_sentences
node_main -->|"requests recording"| node_audio_ui
node_audio_ui -->|"prepares audio"| node_audio_processing
node_main -->|"recognizes attempt"| node_speech
node_speech -->|"loads Whisper"| node_models
node_speech -.->|"sends audio"| node_speech_service
node_main -->|"compares phonemes"| node_phonemes
node_phonemes -->|"uses wav2vec2"| node_models
node_main -->|"compares audio"| node_acoustic
node_main -->|"shows results"| node_feedback
node_feedback -->|"reads sound tips"| node_phoneme_data
node_main -.->|"requests translation"| node_translations
node_main -->|"updates progress"| node_state

click node_main "https://github.com/chinhean/natify-app/blob/master/app/main.py"
click node_sidebar "https://github.com/chinhean/natify-app/blob/master/app/interface/sidebar.py"
click node_audio_ui "https://github.com/chinhean/natify-app/blob/master/app/interface/audio.py"
click node_feedback "https://github.com/chinhean/natify-app/blob/master/app/interface/feedback.py"
click node_sentences "https://github.com/chinhean/natify-app/blob/master/app/data/sentences.py"
click node_gcs_data "https://github.com/chinhean/natify-app/blob/master/app/data/gcs.py"
click node_phoneme_data "https://github.com/chinhean/natify-app/blob/master/app/data/phonemes.py"
click node_audio_processing "https://github.com/chinhean/natify-app/blob/master/app/utils/audio_processing.py"
click node_models "https://github.com/chinhean/natify-app/blob/master/app/ml_logic/models.py"
click node_speech "https://github.com/chinhean/natify-app/blob/master/app/ml_logic/speech.py"
click node_phonemes "https://github.com/chinhean/natify-app/blob/master/app/ml_logic/phonemes.py"
click node_acoustic "https://github.com/chinhean/natify-app/blob/master/app/utils/audio_processing.py"
click node_translations "https://github.com/chinhean/natify-app/blob/master/app/utils/translations.py"
click node_state "https://github.com/chinhean/natify-app/blob/master/app/utils/session_state.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_main,node_sidebar,node_audio_ui,node_feedback toneBlue
class node_sentences,node_gcs_data,node_phoneme_data,node_gcs toneAmber
class node_audio_processing,node_models,node_speech,node_phonemes,node_acoustic,node_translations toneMint
class node_state toneRose
class node_learner,node_speech_service toneIndigo
```

## Components

### Practice experience

- [Streamlit app](https://github.com/chinhean/natify-app/blob/master/app/main.py): `app/main.py`
- [Practice settings](https://github.com/chinhean/natify-app/blob/master/app/interface/sidebar.py): `app/interface/sidebar.py`
- [Recording and playback](https://github.com/chinhean/natify-app/blob/master/app/interface/audio.py): `app/interface/audio.py`
- [Feedback display](https://github.com/chinhean/natify-app/blob/master/app/interface/feedback.py): `app/interface/feedback.py`

### Sentence and audio data

- [Sentence catalog](https://github.com/chinhean/natify-app/blob/master/app/data/sentences.py): `app/data/sentences.py`
- [Cloud data access](https://github.com/chinhean/natify-app/blob/master/app/data/gcs.py): `app/data/gcs.py`
- [Phoneme guidance](https://github.com/chinhean/natify-app/blob/master/app/data/phonemes.py): `app/data/phonemes.py`

### Pronunciation analysis

- [Audio preparation](https://github.com/chinhean/natify-app/blob/master/app/utils/audio_processing.py): `app/utils/audio_processing.py`
- [Model loading](https://github.com/chinhean/natify-app/blob/master/app/ml_logic/models.py): `app/ml_logic/models.py`
- [Speech recognition](https://github.com/chinhean/natify-app/blob/master/app/ml_logic/speech.py): `app/ml_logic/speech.py`
- [Phoneme analysis](https://github.com/chinhean/natify-app/blob/master/app/ml_logic/phonemes.py): `app/ml_logic/phonemes.py`
- [Acoustic comparison](https://github.com/chinhean/natify-app/blob/master/app/utils/audio_processing.py): `app/utils/audio_processing.py`
- [Translation utilities](https://github.com/chinhean/natify-app/blob/master/app/utils/translations.py): `app/utils/translations.py`

### Session progress

- [Practice state](https://github.com/chinhean/natify-app/blob/master/app/utils/session_state.py): `app/utils/session_state.py`

### Other components

- **Learner**
- **Google Cloud Storage**
- **Speech recognition service**

## Connections

- Learner → Streamlit app: uses
- Streamlit app → Practice settings: renders
- Streamlit app → Practice state: initializes
- Streamlit app → Cloud data access: loads sentences
- Cloud data access → Google Cloud Storage: reads sentence data
- Streamlit app → Sentence catalog: selects practice
- Streamlit app → Recording and playback: requests recording
- Recording and playback → Audio preparation: prepares audio
- Streamlit app → Speech recognition: recognizes attempt
- Speech recognition → Model loading: loads Whisper
- Speech recognition → Speech recognition service: sends audio
- Streamlit app → Phoneme analysis: compares phonemes
- Phoneme analysis → Model loading: uses wav2vec2
- Streamlit app → Acoustic comparison: compares audio
- Streamlit app → Feedback display: shows results
- Feedback display → Phoneme guidance: reads sound tips
- Streamlit app → Translation utilities: requests translation
- Streamlit app → Practice state: updates progress