# o24s/haqumei architecture

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

- Interactive diagram: https://gitdiagram.com/o24s/haqumei
- Repository: https://github.com/o24s/haqumei

## Overview

Haqumei is a Japanese grapheme-to-phoneme library. Its principal workflow accepts text through the Rust API, runs a frontend to obtain linguistic features, and exposes phoneme, reading, prosody, and structured word-analysis results. Separate capabilities include IPA conversion, reading candidates, English and unknown-kanji fallbacks, a CLI, and Python bindings. The graph reflects documented behavior and the shown API/frontend connection; unsampled implementation details are grouped conservatively rather than given speculative call chains.

Main entry points: [`haqumei/src/lib.rs`](https://github.com/o24s/haqumei/blob/main/haqumei/src/lib.rs) (Rust G2P API), [`haqumei/src/postprocess.rs`](https://github.com/o24s/haqumei/blob/main/haqumei/src/postprocess.rs) (Reading postprocess), [`haqumei-cli/src/main.rs`](https://github.com/o24s/haqumei/blob/main/haqumei-cli/src/main.rs) (Command-line tool), [`haqumei/src/open_jtalk.rs`](https://github.com/o24s/haqumei/blob/main/haqumei/src/open_jtalk.rs) (OpenJTalk frontend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["User Interfaces"]
  node_rust_api["Rust G2P API<br/>[lib.rs]"]
  node_cli["Command-line tool<br/>[main.rs]"]
  node_python["Python bindings<br/>[pyhaqumei.rs]"]
end

subgraph group_analysis["Text Analysis"]
  node_frontend["OpenJTalk frontend<br/>[open_jtalk.rs]"]
  node_postprocess["Reading postprocess<br/>[postprocess.rs]"]
  node_reading_context["Context reading<br/>[prepare.rs]"]
  node_options["G2P options<br/>[options.rs]"]
end

subgraph group_outputs["Pronunciation Outputs"]
  node_candidates["Reading candidates<br/>[candidates.rs]"]
  node_phonemes["Phoneme inventory<br/>[phoneme.rs]"]
  node_ipa["IPA transcription<br/>[ipa.rs]"]
  node_prosody["Prosody and mapping<br/>[prosody.rs]"]
end

subgraph group_fallbacks["Reading Fallbacks"]
  node_kanalizer["English kana fallback<br/>[lib.rs]"]
  node_unknown_kanji["Unknown-kanji fallback<br/>[unknown_kanji.rs]"]
end

node_users(("Text users"))

node_users -->|"submit text"| node_rust_api
node_users -->|"process text"| node_cli
node_rust_api -->|"runs frontend"| node_frontend
node_rust_api -.->|"applies postprocessing"| node_postprocess
node_postprocess -->|"prepares readings"| node_reading_context
node_rust_api -->|"provides candidates"| node_candidates
node_rust_api -->|"provides IPA"| node_ipa
node_rust_api -->|"provides prosody"| node_prosody
node_rust_api -->|"uses English fallback"| node_kanalizer
node_rust_api -->|"supports fallback"| node_unknown_kanji

click node_rust_api "https://github.com/o24s/haqumei/blob/main/haqumei/src/lib.rs"
click node_cli "https://github.com/o24s/haqumei/blob/main/haqumei-cli/src/main.rs"
click node_python "https://github.com/o24s/haqumei/blob/main/haqumei-python/src/pyhaqumei.rs"
click node_frontend "https://github.com/o24s/haqumei/blob/main/haqumei/src/open_jtalk.rs"
click node_postprocess "https://github.com/o24s/haqumei/blob/main/haqumei/src/postprocess.rs"
click node_reading_context "https://github.com/o24s/haqumei/blob/main/haqumei/src/postprocess/context_reading/prepare.rs"
click node_options "https://github.com/o24s/haqumei/blob/main/haqumei/src/options.rs"
click node_candidates "https://github.com/o24s/haqumei/blob/main/haqumei/src/candidates.rs"
click node_phonemes "https://github.com/o24s/haqumei/blob/main/haqumei/src/phoneme.rs"
click node_ipa "https://github.com/o24s/haqumei/blob/main/haqumei/src/ipa.rs"
click node_prosody "https://github.com/o24s/haqumei/blob/main/haqumei/src/prosody.rs"
click node_kanalizer "https://github.com/o24s/haqumei/blob/main/haqumei-kanalizer/src/lib.rs"
click node_unknown_kanji "https://github.com/o24s/haqumei/blob/main/haqumei/src/postprocess/unknown_kanji.rs"

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_rust_api,node_cli,node_python,node_users toneBlue
class node_frontend,node_postprocess,node_reading_context,node_options toneAmber
class node_candidates,node_phonemes,node_ipa,node_prosody toneMint
class node_kanalizer,node_unknown_kanji toneRose
```

## Components

### User Interfaces

- [Rust G2P API](https://github.com/o24s/haqumei/blob/main/haqumei/src/lib.rs): `haqumei/src/lib.rs`
- [Command-line tool](https://github.com/o24s/haqumei/blob/main/haqumei-cli/src/main.rs): `haqumei-cli/src/main.rs`
- [Python bindings](https://github.com/o24s/haqumei/blob/main/haqumei-python/src/pyhaqumei.rs): `haqumei-python/src/pyhaqumei.rs`

### Text Analysis

- [OpenJTalk frontend](https://github.com/o24s/haqumei/blob/main/haqumei/src/open_jtalk.rs): `haqumei/src/open_jtalk.rs`
- [Reading postprocess](https://github.com/o24s/haqumei/blob/main/haqumei/src/postprocess.rs): `haqumei/src/postprocess.rs`
- [Context reading](https://github.com/o24s/haqumei/blob/main/haqumei/src/postprocess/context_reading/prepare.rs): `haqumei/src/postprocess/context_reading/prepare.rs`
- [G2P options](https://github.com/o24s/haqumei/blob/main/haqumei/src/options.rs): `haqumei/src/options.rs`

### Pronunciation Outputs

- [Reading candidates](https://github.com/o24s/haqumei/blob/main/haqumei/src/candidates.rs): `haqumei/src/candidates.rs`
- [Phoneme inventory](https://github.com/o24s/haqumei/blob/main/haqumei/src/phoneme.rs): `haqumei/src/phoneme.rs`
- [IPA transcription](https://github.com/o24s/haqumei/blob/main/haqumei/src/ipa.rs): `haqumei/src/ipa.rs`
- [Prosody and mapping](https://github.com/o24s/haqumei/blob/main/haqumei/src/prosody.rs): `haqumei/src/prosody.rs`

### Reading Fallbacks

- [English kana fallback](https://github.com/o24s/haqumei/blob/main/haqumei-kanalizer/src/lib.rs): `haqumei-kanalizer/src/lib.rs`
- [Unknown-kanji fallback](https://github.com/o24s/haqumei/blob/main/haqumei/src/postprocess/unknown_kanji.rs): `haqumei/src/postprocess/unknown_kanji.rs`

### Other components

- **Text users**

## Connections

- Text users → Rust G2P API: submit text (evidence: `README.md`)
- Text users → Command-line tool: process text (evidence: `README.md`)
- Rust G2P API → OpenJTalk frontend: runs frontend (evidence: `haqumei/src/lib.rs`)
- Rust G2P API → Reading postprocess: applies postprocessing (evidence: `haqumei/src/lib.rs`)
- Reading postprocess → Context reading: prepares readings
- Rust G2P API → Reading candidates: provides candidates (evidence: `haqumei/src/lib.rs`)
- Rust G2P API → IPA transcription: provides IPA (evidence: `README.md`)
- Rust G2P API → Prosody and mapping: provides prosody (evidence: `README.md`)
- Rust G2P API → English kana fallback: uses English fallback (evidence: `README.md`)
- Rust G2P API → Unknown-kanji fallback: supports fallback (evidence: `README.md`)
