# bahaarawass/wordcount-parallel architecture

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

- Interactive diagram: https://gitdiagram.com/bahaarawass/wordcount-parallel
- Repository: https://github.com/bahaarawass/wordcount-parallel

## Overview

This is a Python teaching demo for whole-word counting and parallel-computing experiments. The main workflow reads UTF-8 lines, counts assigned ranges using threads, combines partial counts, and reports a total and optional trace. Separate commands generate reproducible input, compare threaded and process-based timings, and demonstrate a controlled lost update. The graph reflects the sampled implementation and README; the experiment’s plotting and artifact outputs are documented, while no distributed runtime is shown.

Main entry points: [`src/wordcount/cli.py`](https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/cli.py) (Count CLI), [`src/wordcount/experiment.py`](https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/experiment.py) (Benchmark runner), [`src/wordcount/core.py`](https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/core.py) (Thread counting), [`src/wordcount/generate.py`](https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/generate.py) (Input generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_counting["Word counting"]
  node_count_cli["Count CLI<br/>[cli.py]"]
  node_scanner["Token scanner<br/>[core.py]"]
  node_thread_engine["Thread counting<br/>[core.py]"]
  node_process_engine["Process counting<br/>[core.py]"]
end

subgraph group_experiments["Experiments"]
  node_generator["Input generator<br/>[generate.py]"]
  node_experiment["Benchmark runner<br/>[experiment.py]"]
end

subgraph group_demos["Teaching demos"]
  node_race_cli["Race demo<br/>[race.py]"]
end

node_user(("CLI user"))
node_input["UTF-8 input"]
node_count_result["Count output"]
node_generated_data["Generated input"]
node_experiment_outputs["Benchmark artifacts"]
node_race_result["Race output"]

node_user -->|"runs"| node_count_cli
node_input -->|"provides file"| node_count_cli
node_count_cli -->|"loads lines"| node_scanner
node_count_cli -->|"dispatches threads"| node_thread_engine
node_count_cli -->|"dispatches processes"| node_process_engine
node_thread_engine -->|"scans ranges"| node_scanner
node_process_engine -->|"submits scans"| node_scanner
node_thread_engine -->|"returns counts"| node_count_cli
node_process_engine -->|"returns counts"| node_count_cli
node_count_cli -->|"prints total"| node_count_result
node_user -->|"runs"| node_generator
node_generator -->|"writes input"| node_generated_data
node_user -->|"runs"| node_experiment
node_input -->|"provides file"| node_experiment
node_experiment -->|"loads lines"| node_scanner
node_experiment -->|"benchmarks threads"| node_thread_engine
node_experiment -->|"benchmarks processes"| node_process_engine
node_experiment -->|"writes reports"| node_experiment_outputs
node_user -->|"runs"| node_race_cli
node_race_cli -->|"prints comparison"| node_race_result

click node_count_cli "https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/cli.py"
click node_scanner "https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/core.py"
click node_thread_engine "https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/core.py"
click node_process_engine "https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/core.py"
click node_generator "https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/generate.py"
click node_experiment "https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/experiment.py"
click node_race_cli "https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/race.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_count_cli,node_scanner,node_thread_engine,node_process_engine,node_user toneBlue
class node_generator,node_experiment toneAmber
class node_race_cli toneMint
class node_input,node_count_result,node_generated_data,node_experiment_outputs,node_race_result toneIndigo
```

## Components

### Word counting

- [Count CLI](https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/cli.py): `src/wordcount/cli.py`
- [Token scanner](https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/core.py): `src/wordcount/core.py`
- [Thread counting](https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/core.py): `src/wordcount/core.py`
- [Process counting](https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/core.py): `src/wordcount/core.py`

### Experiments

- [Input generator](https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/generate.py): `src/wordcount/generate.py`
- [Benchmark runner](https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/experiment.py): `src/wordcount/experiment.py`

### Teaching demos

- [Race demo](https://github.com/bahaarawass/wordcount-parallel/blob/main/src/wordcount/race.py): `src/wordcount/race.py`

### Other components

- **CLI user**
- **UTF-8 input**
- **Count output**
- **Generated input**
- **Benchmark artifacts**
- **Race output**

## Connections

- CLI user → Count CLI: runs (evidence: `README.md`)
- UTF-8 input → Count CLI: provides file (evidence: `src/wordcount/cli.py`)
- Count CLI → Token scanner: loads lines (evidence: `src/wordcount/cli.py`)
- Count CLI → Thread counting: dispatches threads (evidence: `src/wordcount/cli.py`)
- Count CLI → Process counting: dispatches processes (evidence: `src/wordcount/cli.py`)
- Thread counting → Token scanner: scans ranges (evidence: `src/wordcount/core.py`)
- Process counting → Token scanner: submits scans (evidence: `src/wordcount/core.py`)
- Thread counting → Count CLI: returns counts (evidence: `src/wordcount/cli.py`)
- Process counting → Count CLI: returns counts (evidence: `src/wordcount/cli.py`)
- Count CLI → Count output: prints total (evidence: `src/wordcount/cli.py`)
- CLI user → Input generator: runs (evidence: `README.md`)
- Input generator → Generated input: writes input (evidence: `src/wordcount/generate.py`)
- CLI user → Benchmark runner: runs (evidence: `README.md`)
- UTF-8 input → Benchmark runner: provides file (evidence: `src/wordcount/experiment.py`)
- Benchmark runner → Token scanner: loads lines (evidence: `src/wordcount/experiment.py`)
- Benchmark runner → Thread counting: benchmarks threads (evidence: `src/wordcount/experiment.py`)
- Benchmark runner → Process counting: benchmarks processes (evidence: `src/wordcount/experiment.py`)
- Benchmark runner → Benchmark artifacts: writes reports (evidence: `src/wordcount/experiment.py`)
- CLI user → Race demo: runs (evidence: `README.md`)
- Race demo → Race output: prints comparison (evidence: `src/wordcount/race.py`)