How sadlil/go-avro-phonetic works
1. What this repo is
- A Go module that converts Romanized Bangla text into Bangla script using Avro Phonetic rules.
- It has two deliverables: a reusable library in the root package and a small CLI in avrocli/.
2. Core library boundary
- The root package (parser.go, parse.go) is the main API surface.
- It exposes the parsing entry points used by applications: Parse, MustParse, and ParseWith.
- This layer is the public boundary for “Roman input in, Bangla output out.”
3. Parsing subsystem
- The parser takes a text string and resolves it against Avro phonetic rules/dictionary entries.
- The code is structured around dictionary-driven lookup rather than hardcoded transliteration rules alone.
- This is the central data-processing path in the repo.
4. Dictionary subsystem
- The data/ package contains the Avro dictionary data and the loading machinery.
- data/dictionary.json is the rule source, while data/dictionary.go and data/bindata.go support loading/embedding it into the Go binary.
- data/dictionary_test.go validates dictionary behavior independently of the parser.
5. Custom parsing extension point
- ParseWith is the main architectural seam for alternate rules.
- It accepts a Dictionary implementation, so callers can override the default phonetic mapping without changing parser internals.
- data.LoadJSON() is the supporting input path for loading custom dictionaries from JSON.
6. CLI subsystem
- avrocli/main.go and avrocli/parse.go provide a separate command-line entry point.
- The CLI wraps the library parser and offers two input modes: inline text and file parsing.
- File mode writes a new .bn.txt output alongside the source file, so the CLI is a thin adapter over the library.
7. Data flow from input to output
- For library use: caller text -> parser -> dictionary lookup -> Bangla string returned to caller.
- For CLI use: command args or file contents -> CLI wrapper -> library parser -> stdout or generated output file.
- The dictionary is the key shared dependency across both paths.
8. Embedded assets and generation
- data/bindata.go indicates generated embedding of static dictionary assets into Go code.
- hack/make.py is likely part of the asset/code generation pipeline used to refresh embedded data.
- This means the repo is designed to ship a self-contained binary without requiring external dictionary files at runtime.
9. Testing and validation
- parser_test.go covers the core transliteration logic.
- data/dictionary_test.go covers dictionary loading/search behavior.
- Together they protect both the algorithm layer and the embedded data layer.
10. Tooling and CI
- go.mod/go.sum define a standard Go module build.
- .github/workflows/ci.yml runs automated checks in GitHub Actions, most likely focused on build and test verification.
- No external services are part of the runtime architecture; the repository is self-contained.
11. How to draw the architecture
- Draw three main boxes: Library Parser, Dictionary/Data, and CLI.
- Show the parser depending on the dictionary package.
- Show the CLI depending on the root library only.
- Show the generated/embedded dictionary asset feeding the data package, and tests wrapping both parser and dictionary modules.
Main entry points: dictionary.go Dictionary · parser.go Parse API · ci.yml CI Workflow · parser_test.go Parser Tests
Components 13
Library Parser
Public parsing API and transliteration flow.
- Parse API · Root package entry points: Parse, MustParse, and ParseWith.
parser.go - Parser Core · Resolves Romanized Bangla text against Avro phonetic rules and dictionary entries.
parser.go - ParseWith · Alternate parsing entry point that accepts a Dictionary implementation.
parser.go
Dictionary/Data
Embedded Avro dictionary and loading paths.
- Dictionary · Dictionary implementation and lookup behavior used by the parser.
data/dictionary.go - Dictionary JSON · Avro phonetic mapping data source.
data/dictionary.json - Embedded Data · Generated asset embedding so the binary ships with dictionary data.
data/bindata.go - JSON Loader · Loads custom dictionaries from JSON into the Dictionary abstraction.
data/dictionary.go
CLI
Command-line wrapper around the library.
- CLI Main · Command-line entry point and argument handling.
avrocli/main.go - CLI Adapter · Bridges command-line input modes to the library parser.
avrocli/parse.go
Validation & Tooling
Tests, CI, and generation support.
- Parser Tests · Covers the core transliteration logic.
parser_test.go - Dict Tests · Validates dictionary loading and search behavior.
data/dictionary_test.go - Make Script · Refreshes generated embedded assets and supporting code.
hack/make.py - CI Workflow · Automated build and test checks in GitHub Actions.
.github/workflows/ci.yml
Connections 18
- Parse API → Parser Core: calls · Public API delegates parsing work to the core engine.
- Parse API → ParseWith: exposes · ParseWith is the main extension point for alternate dictionaries.
- ParseWith → Dictionary: injects · Caller-supplied Dictionary implementation feeds the parser.
- Parser Core → Dictionary: looks up · Core parsing resolves input through dictionary entries.
- Dictionary → Dictionary JSON: sources · Dictionary data is defined in JSON.
- Dictionary → Embedded Data: embedded by · Generated bindings package the dictionary into the binary.
- JSON Loader → Dictionary JSON: loads · Custom dictionaries can be loaded from JSON input.
- Embedded Data → Dictionary: feeds · Embedded assets supply the default dictionary implementation.
- CLI Main → CLI Adapter: uses · The CLI entry point delegates input handling to the adapter.
- CLI Adapter → Parse API: invokes · Command-line text and files are parsed through the root library.
- Parser Tests → Parser Core: verifies · Tests the transliteration behavior.
- Parser Tests → Parse API: verifies · Tests the exported parsing surface.
- Dict Tests → Dictionary: verifies · Tests dictionary loading and lookup behavior.
- Make Script → Embedded Data: produces · Generation script refreshes embedded dictionary code.
- Make Script → Dictionary JSON: consumes · Generation pipeline starts from the dictionary source.
- CI Workflow → Parser Tests: runs · CI validates the parser test suite.
- CI Workflow → Dict Tests: runs · CI validates the dictionary test suite.
- CI Workflow → CLI Main: builds · CI covers the command-line deliverable as part of the module.