# alisolphp/echotalk architecture

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

- Interactive diagram: https://gitdiagram.com/alisolphp/echotalk
- Repository: https://github.com/alisolphp/echotalk

## Overview

EchoTalk is an offline-first language shadowing practice PWA. Learners choose a language and sentence, configure practice, listen and repeat phrase-by-phrase, optionally record themselves, then review practice history and recordings. The app coordinates dedicated practice, audio, data, UI, and AI-prompt services. README capabilities include streak tracking, word-level learning tools, and AI-assisted exercises; their details are not all present in the sampled source, so uncertain internal wiring is omitted. AI assistance is prompt-based rather than a direct AI-service call.

Main entry points: [`src/app.ts`](https://github.com/alisolphp/echotalk/blob/main/src/app.ts) (App Coordinator), [`src/services/practice.service.ts`](https://github.com/alisolphp/echotalk/blob/main/src/services/practice.service.ts) (Practice Flow), [`src/services/data.service.ts`](https://github.com/alisolphp/echotalk/blob/main/src/services/data.service.ts) (History and Samples), [`src/services/audio.service.ts`](https://github.com/alisolphp/echotalk/blob/main/src/services/audio.service.ts) (Speech and Recording)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_practice["Shadowing Practice"]
  node_app["App Coordinator<br/>[app.ts]"]
  node_practice_service["Practice Flow"]
  node_ui["Practice UI<br/>[ui.service.ts]"]
  node_audio["Speech and Recording<br/>[audio.service.ts]"]
  node_utilities["Phrase Utilities<br/>[util.service.ts]"]
end

subgraph group_learning["Learning Tools"]
  node_sample_data["Sentence Packs"]
  node_ai_service["AI Learning Prompts<br/>[ai.service.ts]"]
  node_prompts["Prompt Templates<br/>[prompts.service.ts]"]
end

subgraph group_persistence["Local Data"]
  node_data_service["History and Samples<br/>[data.service.ts]"]
  node_database[("IndexedDB")]
end

subgraph group_platform["Browser Platform"]
  node_browser_speech["Speech Synthesis"]
  node_microphone["Microphone"]
  node_clipboard["System Clipboard"]
end

node_learner(("Learner"))
node_ai_assistant(("External AI Assistant"))
node_translation(("Google Translate"))

node_learner -->|"uses"| node_app
node_app -->|"coordinates"| node_ui
node_app -->|"loads samples"| node_data_service
node_data_service -->|"fetches pack"| node_sample_data
node_app -->|"starts practice"| node_practice_service
node_practice_service -->|"gets phrase bounds"| node_utilities
node_practice_service -->|"controls recording"| node_audio
node_practice_service -->|"saves practice"| node_database
node_audio -->|"speaks phrases"| node_browser_speech
node_audio -->|"records audio"| node_microphone
node_data_service -->|"reads history"| node_database
node_data_service -->|"stores recordings"| node_database
node_learner -->|"requests learning help"| node_ai_service
node_ai_service -->|"builds prompts"| node_prompts
node_ai_service -->|"copies prompt"| node_clipboard
node_learner -.->|"uses copied prompt"| node_ai_assistant
node_ui -.->|"opens translation"| node_translation

click node_app "https://github.com/alisolphp/echotalk/blob/main/src/app.ts"
click node_practice_service "https://github.com/alisolphp/echotalk/blob/main/src/services/practice.service.ts"
click node_ui "https://github.com/alisolphp/echotalk/blob/main/src/services/ui.service.ts"
click node_audio "https://github.com/alisolphp/echotalk/blob/main/src/services/audio.service.ts"
click node_sample_data "https://github.com/alisolphp/echotalk/tree/main/public/data/sentences"
click node_data_service "https://github.com/alisolphp/echotalk/blob/main/src/services/data.service.ts"
click node_ai_service "https://github.com/alisolphp/echotalk/blob/main/src/services/ai.service.ts"
click node_prompts "https://github.com/alisolphp/echotalk/blob/main/src/services/prompts.service.ts"
click node_utilities "https://github.com/alisolphp/echotalk/blob/main/src/services/util.service.ts"

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_app,node_practice_service,node_ui,node_audio,node_utilities toneBlue
class node_sample_data,node_ai_service,node_prompts toneAmber
class node_data_service,node_database toneMint
class node_browser_speech,node_microphone,node_clipboard toneRose
class node_learner,node_ai_assistant,node_translation toneIndigo
```

## Components

### Shadowing Practice

- [App Coordinator](https://github.com/alisolphp/echotalk/blob/main/src/app.ts): `src/app.ts`
- [Practice Flow](https://github.com/alisolphp/echotalk/blob/main/src/services/practice.service.ts): `src/services/practice.service.ts`
- [Practice UI](https://github.com/alisolphp/echotalk/blob/main/src/services/ui.service.ts): `src/services/ui.service.ts`
- [Speech and Recording](https://github.com/alisolphp/echotalk/blob/main/src/services/audio.service.ts): `src/services/audio.service.ts`
- [Phrase Utilities](https://github.com/alisolphp/echotalk/blob/main/src/services/util.service.ts): `src/services/util.service.ts`

### Learning Tools

- [Sentence Packs](https://github.com/alisolphp/echotalk/tree/main/public/data/sentences): `public/data/sentences`
- [AI Learning Prompts](https://github.com/alisolphp/echotalk/blob/main/src/services/ai.service.ts): `src/services/ai.service.ts`
- [Prompt Templates](https://github.com/alisolphp/echotalk/blob/main/src/services/prompts.service.ts): `src/services/prompts.service.ts`

### Local Data

- [History and Samples](https://github.com/alisolphp/echotalk/blob/main/src/services/data.service.ts): `src/services/data.service.ts`
- **IndexedDB**

### Browser Platform

- **Speech Synthesis**
- **Microphone**
- **System Clipboard**

### Other components

- **Learner**
- **External AI Assistant**
- **Google Translate**

## Connections

- Learner → App Coordinator: uses
- App Coordinator → Practice UI: coordinates
- App Coordinator → History and Samples: loads samples
- History and Samples → Sentence Packs: fetches pack
- App Coordinator → Practice Flow: starts practice
- Practice Flow → Phrase Utilities: gets phrase bounds
- Practice Flow → Speech and Recording: controls recording
- Practice Flow → IndexedDB: saves practice
- Speech and Recording → Speech Synthesis: speaks phrases
- Speech and Recording → Microphone: records audio
- History and Samples → IndexedDB: reads history
- History and Samples → IndexedDB: stores recordings
- Learner → AI Learning Prompts: requests learning help
- AI Learning Prompts → Prompt Templates: builds prompts
- AI Learning Prompts → System Clipboard: copies prompt
- Learner → External AI Assistant: uses copied prompt
- Practice UI → Google Translate: opens translation