# jharlan-hash/gospell architecture

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

- Interactive diagram: https://gitdiagram.com/jharlan-hash/gospell
- Repository: https://github.com/jharlan-hash/gospell

## Overview

GoSpell is a terminal spelling-practice app. The main workflow selects a word, presents its cached definition, speaks it, checks the submitted spelling, updates the streak, and selects another word; the TUI also reports WPM and supports definition navigation and audio replay. The graph separates interaction, word selection, definition lookup, and speech/audio. Source excerpts show the main orchestration and these runtime calls; other links are omitted where evidence is unavailable.

Main entry points: [`gospell.go`](https://github.com/jharlan-hash/gospell/blob/main/gospell.go) (Practice session), [`internal/tts/tts.go`](https://github.com/jharlan-hash/gospell/blob/main/internal/tts/tts.go) (Speech synthesis), [`internal/api/api.go`](https://github.com/jharlan-hash/gospell/blob/main/internal/api/api.go) (Random word picker), [`internal/definition/definitions.go`](https://github.com/jharlan-hash/gospell/blob/main/internal/definition/definitions.go) (Definition navigation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_practice["Practice interface"]
  node_session["Practice session<br/>[gospell.go]"]
end

subgraph group_words["Word selection"]
  node_wordlist["Word list<br/>[wordlist.txt]"]
  node_wordpicker["Random word picker<br/>[api.go]"]
end

subgraph group_definitions["Definitions"]
  node_definitionstate["Definition navigation<br/>[definitions.go]"]
  node_definitioncache["Cache loader<br/>[cache.go]"]
  node_dictionary["Dictionary entries<br/>[types.go]"]
  node_wordmap[("Embedded word map<br/>[wordmap.gob]")]
end

subgraph group_speech["Speech and audio"]
  node_tts["Speech synthesis<br/>[tts.go]"]
  node_googletts["Google Cloud TTS"]
  node_audio["Audio playback"]
end

subgraph group_metrics["Progress metrics"]
  node_wpm["WPM calculation<br/>[wpm.go]"]
end

node_learner(("Learner"))

node_learner -->|"enters spelling"| node_session
node_session -->|"selects word"| node_wordpicker
node_wordpicker -->|"chooses from"| node_wordlist
node_session -->|"looks up definition"| node_definitionstate
node_definitionstate -->|"loads cache"| node_definitioncache
node_definitioncache -->|"decodes embedded data"| node_wordmap
node_session -->|"requests speech"| node_tts
node_tts -->|"synthesizes speech"| node_googletts
node_tts -->|"plays audio"| node_audio
node_session -->|"calculates WPM"| node_wpm

click node_session "https://github.com/jharlan-hash/gospell/blob/main/gospell.go"
click node_wordlist "https://github.com/jharlan-hash/gospell/blob/main/internal/api/wordlist.txt"
click node_wordpicker "https://github.com/jharlan-hash/gospell/blob/main/internal/api/api.go"
click node_definitionstate "https://github.com/jharlan-hash/gospell/blob/main/internal/definition/definitions.go"
click node_definitioncache "https://github.com/jharlan-hash/gospell/blob/main/internal/definition/cache.go"
click node_dictionary "https://github.com/jharlan-hash/gospell/blob/main/internal/definition/types.go"
click node_wordmap "https://github.com/jharlan-hash/gospell/blob/main/internal/definition/wordmap.gob"
click node_tts "https://github.com/jharlan-hash/gospell/blob/main/internal/tts/tts.go"
click node_wpm "https://github.com/jharlan-hash/gospell/blob/main/internal/wpm/wpm.go"

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_session toneBlue
class node_wordlist,node_wordpicker toneAmber
class node_definitionstate,node_definitioncache,node_dictionary,node_wordmap toneMint
class node_tts,node_googletts,node_audio toneRose
class node_wpm,node_learner toneIndigo
```

## Components

### Practice interface

- [Practice session](https://github.com/jharlan-hash/gospell/blob/main/gospell.go): `gospell.go`

### Word selection

- [Word list](https://github.com/jharlan-hash/gospell/blob/main/internal/api/wordlist.txt): `internal/api/wordlist.txt`
- [Random word picker](https://github.com/jharlan-hash/gospell/blob/main/internal/api/api.go): `internal/api/api.go`

### Definitions

- [Definition navigation](https://github.com/jharlan-hash/gospell/blob/main/internal/definition/definitions.go): `internal/definition/definitions.go`
- [Cache loader](https://github.com/jharlan-hash/gospell/blob/main/internal/definition/cache.go): `internal/definition/cache.go`
- [Dictionary entries](https://github.com/jharlan-hash/gospell/blob/main/internal/definition/types.go): `internal/definition/types.go`
- [Embedded word map](https://github.com/jharlan-hash/gospell/blob/main/internal/definition/wordmap.gob): `internal/definition/wordmap.gob`

### Speech and audio

- [Speech synthesis](https://github.com/jharlan-hash/gospell/blob/main/internal/tts/tts.go): `internal/tts/tts.go`
- **Google Cloud TTS**
- **Audio playback**

### Progress metrics

- [WPM calculation](https://github.com/jharlan-hash/gospell/blob/main/internal/wpm/wpm.go): `internal/wpm/wpm.go`

### Other components

- **Learner**

## Connections

- Learner → Practice session: enters spelling (evidence: `README.md`)
- Practice session → Random word picker: selects word (evidence: `gospell.go`)
- Random word picker → Word list: chooses from (evidence: `internal/api/api.go`)
- Practice session → Definition navigation: looks up definition (evidence: `gospell.go`)
- Definition navigation → Cache loader: loads cache (evidence: `internal/definition/definitions.go`)
- Cache loader → Embedded word map: decodes embedded data (evidence: `internal/definition/cache.go`)
- Practice session → Speech synthesis: requests speech (evidence: `gospell.go`)
- Speech synthesis → Google Cloud TTS: synthesizes speech (evidence: `internal/tts/tts.go`)
- Speech synthesis → Audio playback: plays audio (evidence: `internal/tts/tts.go`)
- Practice session → WPM calculation: calculates WPM (evidence: `gospell.go`)
