# filippovicidomini/phonetic-distance architecture

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

- Interactive diagram: https://gitdiagram.com/filippovicidomini/phonetic-distance
- Repository: https://github.com/filippovicidomini/phonetic-distance

## Overview

Phonetic Distance is a Python library for comparing phonetic or dialectal forms. The main workflow normalizes and tokenizes input, computes feature-weighted edit distance, and returns normalized similarity; slash-separated variants are compared pairwise and the maximum similarity is returned. The README also documents corpus timing analysis and plotting. The core implementation is sampled, but timing-analysis details and several relationships are based on the excerpts and README rather than a complete inspection of every file.

Main entry points: [`scripts/analyze_computation_times.py`](https://github.com/filippovicidomini/phonetic-distance/blob/main/scripts/analyze_computation_times.py) (Timing analysis), [`phonetic_distance/__init__.py`](https://github.com/filippovicidomini/phonetic-distance/blob/main/phonetic_distance/__init__.py) (Public API), [`phonetic_distance/core.py`](https://github.com/filippovicidomini/phonetic-distance/blob/main/phonetic_distance/core.py) (Weighted distance), [`scripts/plot_timing_analysis.py`](https://github.com/filippovicidomini/phonetic-distance/blob/main/scripts/plot_timing_analysis.py) (Timing plots)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["Similarity library"]
  node_api["Public API<br/>[__init__.py]"]
  node_normalization["NFD tokenization<br/>[core.py]"]
  node_features["Phonetic features<br/>[core.py]"]
  node_distance["Weighted distance<br/>[core.py]"]
  node_similarity["Normalized similarity<br/>[core.py]"]
  node_variants["Variant comparison<br/>[core.py]"]
end

subgraph group_analysis["Timing analysis"]
  node_corpus["Corpus input"]
  node_timing["Timing analysis"]
  node_results["Timing results"]
  node_plots["Timing plots"]
end

node_user(("Library user"))

node_user -->|"supplies forms"| node_api
node_api -->|"re-exports"| node_normalization
node_normalization -->|"tokenizes sequences"| node_distance
node_features -->|"sets substitution costs"| node_distance
node_distance -->|"normalizes distance"| node_similarity
node_variants -->|"compares variant pairs"| node_similarity
node_user -->|"runs analysis"| node_timing
node_corpus -->|"provides CSV data"| node_timing
node_timing -->|"calls similarity"| node_api
node_timing -->|"writes CSV summary"| node_results
node_results -->|"provides analysis CSV"| node_plots

click node_api "https://github.com/filippovicidomini/phonetic-distance/blob/main/phonetic_distance/__init__.py"
click node_normalization "https://github.com/filippovicidomini/phonetic-distance/blob/main/phonetic_distance/core.py"
click node_features "https://github.com/filippovicidomini/phonetic-distance/blob/main/phonetic_distance/core.py"
click node_distance "https://github.com/filippovicidomini/phonetic-distance/blob/main/phonetic_distance/core.py"
click node_similarity "https://github.com/filippovicidomini/phonetic-distance/blob/main/phonetic_distance/core.py"
click node_variants "https://github.com/filippovicidomini/phonetic-distance/blob/main/phonetic_distance/core.py"
click node_timing "https://github.com/filippovicidomini/phonetic-distance/blob/main/scripts/analyze_computation_times.py"
click node_plots "https://github.com/filippovicidomini/phonetic-distance/blob/main/scripts/plot_timing_analysis.py"

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_api,node_normalization,node_features,node_distance,node_similarity,node_variants,node_user toneBlue
class node_corpus,node_timing,node_results,node_plots toneAmber
```

## Components

### Similarity library

- [Public API](https://github.com/filippovicidomini/phonetic-distance/blob/main/phonetic_distance/__init__.py): `phonetic_distance/__init__.py`
- [NFD tokenization](https://github.com/filippovicidomini/phonetic-distance/blob/main/phonetic_distance/core.py): `phonetic_distance/core.py`
- [Phonetic features](https://github.com/filippovicidomini/phonetic-distance/blob/main/phonetic_distance/core.py): `phonetic_distance/core.py`
- [Weighted distance](https://github.com/filippovicidomini/phonetic-distance/blob/main/phonetic_distance/core.py): `phonetic_distance/core.py`
- [Normalized similarity](https://github.com/filippovicidomini/phonetic-distance/blob/main/phonetic_distance/core.py): `phonetic_distance/core.py`
- [Variant comparison](https://github.com/filippovicidomini/phonetic-distance/blob/main/phonetic_distance/core.py): `phonetic_distance/core.py`

### Timing analysis

- **Corpus input**
- [Timing analysis](https://github.com/filippovicidomini/phonetic-distance/blob/main/scripts/analyze_computation_times.py): `scripts/analyze_computation_times.py`
- **Timing results**
- [Timing plots](https://github.com/filippovicidomini/phonetic-distance/blob/main/scripts/plot_timing_analysis.py): `scripts/plot_timing_analysis.py`

### Other components

- **Library user**

## Connections

- Library user → Public API: supplies forms (evidence: `README.md`)
- Public API → NFD tokenization: re-exports (evidence: `phonetic_distance/__init__.py`)
- NFD tokenization → Weighted distance: tokenizes sequences (evidence: `README.md`)
- Phonetic features → Weighted distance: sets substitution costs (evidence: `phonetic_distance/core.py`)
- Weighted distance → Normalized similarity: normalizes distance (evidence: `phonetic_distance/core.py`)
- Variant comparison → Normalized similarity: compares variant pairs (evidence: `README.md`)
- Library user → Timing analysis: runs analysis (evidence: `scripts/analyze_computation_times.py`)
- Corpus input → Timing analysis: provides CSV data (evidence: `scripts/analyze_computation_times.py`)
- Timing analysis → Public API: calls similarity (evidence: `scripts/analyze_computation_times.py`)
- Timing analysis → Timing results: writes CSV summary (evidence: `scripts/analyze_computation_times.py`)
- Timing results → Timing plots: provides analysis CSV (evidence: `scripts/plot_timing_analysis.py`)
