# sadlil/go-avro-phonetic architecture

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

- Interactive diagram: https://gitdiagram.com/sadlil/go-avro-phonetic
- Repository: https://github.com/sadlil/go-avro-phonetic

## Overview

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: [`data/dictionary.go`](https://github.com/sadlil/go-avro-phonetic/blob/master/data/dictionary.go) (Dictionary), [`parser.go`](https://github.com/sadlil/go-avro-phonetic/blob/master/parser.go) (Parse API), [`.github/workflows/ci.yml`](https://github.com/sadlil/go-avro-phonetic/blob/master/.github/workflows/ci.yml) (CI Workflow), [`parser_test.go`](https://github.com/sadlil/go-avro-phonetic/blob/master/parser_test.go) (Parser Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["Library Parser"]
  node_public_api["Parse API<br/>package api<br/>[parser.go]"]
  node_parse_engine["Parser Core<br/>transliteration engine<br/>[parser.go]"]
  node_custom_seam(("ParseWith<br/>extension seam<br/>[parser.go]"))
end

subgraph group_data["Dictionary/Data"]
  node_dict_core[("Dictionary<br/>lookup store<br/>[dictionary.go]")]
  node_dict_json["Dictionary JSON<br/>rule source<br/>[dictionary.json]"]
  node_bindata["Embedded Data<br/>generated embed<br/>[bindata.go]"]
  node_json_loader["JSON Loader<br/>[dictionary.go]"]
end

subgraph group_cli["CLI"]
  node_cli_main["CLI Main<br/>command entrypoint<br/>[main.go]"]
  node_cli_parse["CLI Adapter<br/>input adapter<br/>[parse.go]"]
end

subgraph group_support["Validation & Tooling"]
  node_parser_tests["Parser Tests<br/>unit tests<br/>[parser_test.go]"]
  node_dict_tests["Dict Tests<br/>unit tests<br/>[dictionary_test.go]"]
  node_generator["Make Script<br/>code generation<br/>[make.py]"]
  node_ci["CI Workflow<br/>automation<br/>[ci.yml]"]
end

node_public_api -->|"calls"| node_parse_engine
node_public_api -->|"exposes"| node_custom_seam
node_custom_seam -->|"injects"| node_dict_core
node_parse_engine -->|"looks up"| node_dict_core
node_dict_core -->|"sources"| node_dict_json
node_dict_core -->|"embedded by"| node_bindata
node_json_loader -->|"loads"| node_dict_json
node_bindata -->|"feeds"| node_dict_core
node_cli_main -->|"uses"| node_cli_parse
node_cli_parse -->|"invokes"| node_public_api
node_parser_tests -.->|"verifies"| node_parse_engine
node_parser_tests -.->|"verifies"| node_public_api
node_dict_tests -.->|"verifies"| node_dict_core
node_generator -->|"produces"| node_bindata
node_generator -->|"consumes"| node_dict_json
node_ci -->|"runs"| node_parser_tests
node_ci -->|"runs"| node_dict_tests
node_ci -->|"builds"| node_cli_main

click node_public_api "https://github.com/sadlil/go-avro-phonetic/blob/master/parser.go"
click node_parse_engine "https://github.com/sadlil/go-avro-phonetic/blob/master/parser.go"
click node_custom_seam "https://github.com/sadlil/go-avro-phonetic/blob/master/parser.go"
click node_dict_core "https://github.com/sadlil/go-avro-phonetic/blob/master/data/dictionary.go"
click node_dict_json "https://github.com/sadlil/go-avro-phonetic/blob/master/data/dictionary.json"
click node_bindata "https://github.com/sadlil/go-avro-phonetic/blob/master/data/bindata.go"
click node_json_loader "https://github.com/sadlil/go-avro-phonetic/blob/master/data/dictionary.go"
click node_cli_main "https://github.com/sadlil/go-avro-phonetic/blob/master/avrocli/main.go"
click node_cli_parse "https://github.com/sadlil/go-avro-phonetic/blob/master/avrocli/parse.go"
click node_parser_tests "https://github.com/sadlil/go-avro-phonetic/blob/master/parser_test.go"
click node_dict_tests "https://github.com/sadlil/go-avro-phonetic/blob/master/data/dictionary_test.go"
click node_generator "https://github.com/sadlil/go-avro-phonetic/blob/master/hack/make.py"
click node_ci "https://github.com/sadlil/go-avro-phonetic/blob/master/.github/workflows/ci.yml"

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_public_api,node_parse_engine,node_custom_seam toneBlue
class node_dict_core,node_dict_json,node_bindata,node_json_loader toneAmber
class node_cli_main,node_cli_parse toneMint
class node_parser_tests,node_dict_tests,node_generator,node_ci toneRose
```

## Components

### Library Parser

Public parsing API and transliteration flow.

- [Parse API](https://github.com/sadlil/go-avro-phonetic/blob/master/parser.go): package api · Root package entry points: Parse, MustParse, and ParseWith. · `parser.go`
- [Parser Core](https://github.com/sadlil/go-avro-phonetic/blob/master/parser.go): transliteration engine · Resolves Romanized Bangla text against Avro phonetic rules and dictionary entries. · `parser.go`
- [ParseWith](https://github.com/sadlil/go-avro-phonetic/blob/master/parser.go): extension seam · Alternate parsing entry point that accepts a Dictionary implementation. · `parser.go`

### Dictionary/Data

Embedded Avro dictionary and loading paths.

- [Dictionary](https://github.com/sadlil/go-avro-phonetic/blob/master/data/dictionary.go): lookup store · Dictionary implementation and lookup behavior used by the parser. · `data/dictionary.go`
- [Dictionary JSON](https://github.com/sadlil/go-avro-phonetic/blob/master/data/dictionary.json): rule source · Avro phonetic mapping data source. · `data/dictionary.json`
- [Embedded Data](https://github.com/sadlil/go-avro-phonetic/blob/master/data/bindata.go): generated embed · Generated asset embedding so the binary ships with dictionary data. · `data/bindata.go`
- [JSON Loader](https://github.com/sadlil/go-avro-phonetic/blob/master/data/dictionary.go): loader · Loads custom dictionaries from JSON into the Dictionary abstraction. · `data/dictionary.go`

### CLI

Command-line wrapper around the library.

- [CLI Main](https://github.com/sadlil/go-avro-phonetic/blob/master/avrocli/main.go): command entrypoint · Command-line entry point and argument handling. · `avrocli/main.go`
- [CLI Adapter](https://github.com/sadlil/go-avro-phonetic/blob/master/avrocli/parse.go): input adapter · Bridges command-line input modes to the library parser. · `avrocli/parse.go`

### Validation & Tooling

Tests, CI, and generation support.

- [Parser Tests](https://github.com/sadlil/go-avro-phonetic/blob/master/parser_test.go): unit tests · Covers the core transliteration logic. · `parser_test.go`
- [Dict Tests](https://github.com/sadlil/go-avro-phonetic/blob/master/data/dictionary_test.go): unit tests · Validates dictionary loading and search behavior. · `data/dictionary_test.go`
- [Make Script](https://github.com/sadlil/go-avro-phonetic/blob/master/hack/make.py): code generation · Refreshes generated embedded assets and supporting code. · `hack/make.py`
- [CI Workflow](https://github.com/sadlil/go-avro-phonetic/blob/master/.github/workflows/ci.yml): automation · Automated build and test checks in GitHub Actions. · `.github/workflows/ci.yml`

## Connections

- 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.