# ctongfei/progressbar architecture

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

- Interactive diagram: https://gitdiagram.com/ctongfei/progressbar
- Repository: https://github.com/ctongfei/progressbar

## Overview

1. **What this repository is**
   - A small Java/JVM library for **console progress bars** with low runtime overhead.
   - It is packaged as a **Maven artifact** and also exposes a **Java 9 module**.

2. **Primary public API**
   - The main entry point for imperative use is `ProgressBar`.
   - `ProgressBarBuilder` and `ProgressBarStyleBuilder` provide configuration/setup APIs.
   - The README shows two usage modes: **imperative** (`step`, `stepBy`, `stepTo`, `maxHint`, `setExtraMessage`) and **declarative** wrapping of collections/streams.

3. **Core progress model**
   - `ProgressState` is the central mutable/observable state for a bar.
   - `ProgressUpdateAction` likely represents the kinds of state changes that drive redraws.
   - This is the boundary between application work and visualization: user code updates state, the library turns that into terminal output.

4. **Rendering layer**
   - `ProgressBarRenderer` defines how a `ProgressState` becomes a textual bar.
   - `DefaultProgressBarRenderer` is the standard renderer.
   - `ProgressBarStyle` and `ProgressBarStyleBuilder` define the visual language of the bar, including ASCII vs box-drawing styles.
   - `StringDisplayUtils` handles text-width/width-alignment concerns, which matter for terminal glyphs and wide characters.

5. **Console/output layer**
   - `ProgressBarConsumer` is the output abstraction for sending rendered updates somewhere.
   - `ConsoleProgressBarConsumer` and `InteractiveConsoleProgressBarConsumer` are the concrete console targets.
   - `DelegatingProgressBarConsumer` suggests composition, so output can be wrapped or adapted without changing the core progress logic.
   - `TerminalUtils` likely handles terminal capabilities and behavior that affect redraws, line clearing, or interactive vs non-interactive consoles.

6. **Declarative wrappers around workload sources**
   - The `wrapped` package adapts existing data sources so progress is tracked automatically:
     - `ProgressBarWrappedIterable`
     - `ProgressBarWrappedIterator`
     - `ProgressBarWrappedSpliterator`
     - `ProgressBarWrappedInputStream`
     - `ProgressBarWrappedOutputStream`
     - `ProgressBarWrappedReader`
     - `ProgressBarWrappedWriter`
   - These wrappers form a second major entry path: instead of manually calling `step`, the library intercepts reads/writes/iteration and advances the bar for the caller.

7. **Typical data flow**
   - Application code performs work or iterates data.
   - Work is tracked either directly through `ProgressBar` or indirectly through a wrapper.
   - Progress updates mutate `ProgressState`.
   - The renderer converts state into a terminal line based on the chosen style.
   - The consumer sends the rendered line to the console, optionally using terminal-aware behavior for interactive redraws.

8. **Parallel / multiple progress bars**
   - The README explicitly supports multiple simultaneous bars for parallel jobs.
   - This means the output layer is designed to handle more than one active `ProgressBar` instance, not just a single linear task.

9. **Platform and compatibility boundaries**
   - The presence of `src/main/java9/module-info.java` indicates explicit **JPMS/module support**.
   - Tests like `EastAsianDisplayTest` imply the library pays attention to **character width and locale-dependent terminal rendering**, which is important to diagram as part of the rendering boundary.

10. **Testing and quality focus**
   - The test suite is broad and behavior-driven: progress updates, pause/resume, ranges, speed display, wrapped iterables, multi-bar behavior, and logging integration (`Slf4jTest`).
   - This suggests the key risks are not business logic but **terminal rendering correctness** and **state/update semantics**.

11. **Documentation and developer tooling**
   - `docs/` plus `mkdocs.yml` indicate a separate documentation site for API/usage guidance.
   - `Makefile`, `pom.xml`, and Dependabot config show standard Java build/release and dependency maintenance tooling.

12. **How to draw the architecture**
   - The cleanest diagram is a layered one:
     - **Client application** on top
     - **Progress API / wrappers**
     - **Progress state + rendering**
     - **Console consumers / terminal handling**
     - **Standard output/error terminal**
   - The wrapper package can be shown as an alternate ingress path that feeds into the same core progress/render/output pipeline.

Main entry points: [`src/main/java/me/tongfei/progressbar/ProgressState.java`](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressState.java) (Progress state), [`src/main/java/me/tongfei/progressbar/ProgressBar.java`](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressBar.java) (ProgressBar), [`src/main/java/me/tongfei/progressbar/ProgressBarRenderer.java`](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressBarRenderer.java) (Renderer), [`src/main/java/me/tongfei/progressbar/ConsoleProgressBarConsumer.java`](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ConsoleProgressBarConsumer.java) (Console consumer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_progressbar["ProgressBar<br/>API entry<br/>[ProgressBar.java]"]
  node_builder["Bar builder<br/>config API"]
  node_stylebuilder["Style builder<br/>config API"]
end

subgraph group_core["Core Engine"]
  node_state[("Progress state<br/>mutable state<br/>[ProgressState.java]")]
  node_update(("Update action<br/>state change"))
  node_renderer["Renderer<br/>render contract"]
  node_defaultrenderer["Default renderer<br/>renderer impl"]
  node_style["Style<br/>visual model"]
  node_stringutils["Text width<br/>terminal text utils"]
end

subgraph group_output["Console Output"]
  node_consumer["Consumer<br/>output contract"]
  node_delegatingconsumer["Delegating consumer<br/>consumer wrapper"]
  node_consoleconsumer["Console consumer<br/>console output"]
  node_interactiveconsumer["Interactive console<br/>console output"]
  node_terminalutils["Terminal utils<br/>terminal support<br/>[TerminalUtils.java]"]
end

subgraph group_wrap["Wrappers"]
  node_wrappediterable["Iterable wrapper<br/>declarative adapter"]
  node_wrappediterator["Iterator wrapper<br/>declarative adapter"]
  node_wrappedspliterator["Spliterator wrapper<br/>declarative adapter"]
  node_wrappedinput["Input stream<br/>io wrapper"]
  node_wrappedoutput["Output stream<br/>io wrapper"]
  node_wrappedreader["Reader wrapper<br/>io wrapper"]
  node_wrappedwriter["Writer wrapper<br/>io wrapper"]
end

subgraph group_platform["Platform"]
  node_moduleinfo["JPMS module<br/>module boundary<br/>[module-info.java]"]
  node_console["Terminal<br/>runtime sink"]
end

node_app["Client app<br/>external"]

node_app -->|"configure"| node_builder
node_builder -->|"create"| node_progressbar
node_app -->|"step"| node_progressbar
node_app -->|"wrap"| node_wrappediterable
node_app -->|"wrap"| node_wrappedinput
node_wrappediterable -->|"advance"| node_state
node_wrappediterator -->|"advance"| node_state
node_wrappedspliterator -->|"advance"| node_state
node_wrappedinput -->|"advance"| node_state
node_wrappedoutput -->|"advance"| node_state
node_wrappedreader -->|"advance"| node_state
node_wrappedwriter -->|"advance"| node_state
node_progressbar -->|"mutate"| node_state
node_state -->|"render"| node_renderer
node_renderer -->|"implements"| node_defaultrenderer
node_defaultrenderer -->|"uses"| node_style
node_style -->|"builds"| node_stylebuilder
node_renderer -->|"measure"| node_stringutils
node_state -->|"emit"| node_consumer
node_consumer -->|"compose"| node_delegatingconsumer
node_delegatingconsumer -->|"delegate"| node_consoleconsumer
node_consoleconsumer -->|"variant"| node_interactiveconsumer
node_interactiveconsumer -->|"inspect"| node_terminalutils
node_consoleconsumer -->|"write"| node_console
node_interactiveconsumer -->|"redraw"| node_console
node_moduleinfo -->|"exports"| node_progressbar

click node_progressbar "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressBar.java"
click node_builder "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressBarBuilder.java"
click node_stylebuilder "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressBarStyleBuilder.java"
click node_state "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressState.java"
click node_update "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressUpdateAction.java"
click node_renderer "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressBarRenderer.java"
click node_defaultrenderer "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/DefaultProgressBarRenderer.java"
click node_style "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressBarStyle.java"
click node_stringutils "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/StringDisplayUtils.java"
click node_consumer "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressBarConsumer.java"
click node_delegatingconsumer "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/DelegatingProgressBarConsumer.java"
click node_consoleconsumer "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ConsoleProgressBarConsumer.java"
click node_interactiveconsumer "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/InteractiveConsoleProgressBarConsumer.java"
click node_terminalutils "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/TerminalUtils.java"
click node_wrappediterable "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedIterable.java"
click node_wrappediterator "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedIterator.java"
click node_wrappedspliterator "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedSpliterator.java"
click node_wrappedinput "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedInputStream.java"
click node_wrappedoutput "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedOutputStream.java"
click node_wrappedreader "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedReader.java"
click node_wrappedwriter "https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedWriter.java"
click node_moduleinfo "https://github.com/ctongfei/progressbar/blob/main/src/main/java9/module-info.java"

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_progressbar,node_builder,node_stylebuilder toneBlue
class node_state,node_update,node_renderer,node_defaultrenderer,node_style,node_stringutils toneAmber
class node_consumer,node_delegatingconsumer,node_consoleconsumer,node_interactiveconsumer,node_terminalutils toneMint
class node_wrappediterable,node_wrappediterator,node_wrappedspliterator,node_wrappedinput,node_wrappedoutput,node_wrappedreader,node_wrappedwriter toneRose
class node_moduleinfo,node_console toneIndigo
class node_app toneNeutral
```

## Components

### Public API

Main entry points and configuration surfaces for library users.

- [ProgressBar](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressBar.java): API entry · Main imperative handle for creating and updating a progress bar. · `src/main/java/me/tongfei/progressbar/ProgressBar.java`
- [Bar builder](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressBarBuilder.java): config API · Builds configured progress bar instances. · `src/main/java/me/tongfei/progressbar/ProgressBarBuilder.java`
- [Style builder](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressBarStyleBuilder.java): config API · Builds visual styles for bars and glyph sets. · `src/main/java/me/tongfei/progressbar/ProgressBarStyleBuilder.java`

### Core Engine

Progress state, update semantics, and rendering logic.

- [Progress state](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressState.java): mutable state · Central observable state for progress, rate, and messages. · `src/main/java/me/tongfei/progressbar/ProgressState.java`
- [Update action](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressUpdateAction.java): state change · Represents a progress mutation that can trigger redraws. · `src/main/java/me/tongfei/progressbar/ProgressUpdateAction.java`
- [Renderer](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressBarRenderer.java): render contract · Converts progress state into a textual bar representation. · `src/main/java/me/tongfei/progressbar/ProgressBarRenderer.java`
- [Default renderer](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/DefaultProgressBarRenderer.java): renderer impl · Standard textual rendering implementation. · `src/main/java/me/tongfei/progressbar/DefaultProgressBarRenderer.java`
- [Style](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressBarStyle.java): visual model · Defines the bar's textual appearance and glyph choices. · `src/main/java/me/tongfei/progressbar/ProgressBarStyle.java`
- [Text width](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/StringDisplayUtils.java): terminal text utils · Handles display width and alignment for wide or complex glyphs. · `src/main/java/me/tongfei/progressbar/StringDisplayUtils.java`

### Console Output

Consumer abstractions and terminal-aware console targets.

- [Consumer](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ProgressBarConsumer.java): output contract · Abstracts where rendered progress updates are written. · `src/main/java/me/tongfei/progressbar/ProgressBarConsumer.java`
- [Delegating consumer](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/DelegatingProgressBarConsumer.java): consumer wrapper · Composes or adapts another consumer. · `src/main/java/me/tongfei/progressbar/DelegatingProgressBarConsumer.java`
- [Console consumer](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/ConsoleProgressBarConsumer.java): console output · Concrete non-interactive console target. · `src/main/java/me/tongfei/progressbar/ConsoleProgressBarConsumer.java`
- [Interactive console](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/InteractiveConsoleProgressBarConsumer.java): console output · Terminal-aware consumer for live redraws and line management. · `src/main/java/me/tongfei/progressbar/InteractiveConsoleProgressBarConsumer.java`
- [Terminal utils](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/TerminalUtils.java): terminal support · Detects terminal behavior and supports redraw decisions. · `src/main/java/me/tongfei/progressbar/TerminalUtils.java`

### Wrappers

Declarative adapters that track progress while iterating or streaming.

- [Iterable wrapper](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedIterable.java): declarative adapter · Advances progress while iterating collections. · `src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedIterable.java`
- [Iterator wrapper](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedIterator.java): declarative adapter · Tracks progress for iterator consumption. · `src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedIterator.java`
- [Spliterator wrapper](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedSpliterator.java): declarative adapter · Tracks progress for spliterator-based traversal. · `src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedSpliterator.java`
- [Input stream](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedInputStream.java): io wrapper · Advances progress while reading bytes. · `src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedInputStream.java`
- [Output stream](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedOutputStream.java): io wrapper · Advances progress while writing bytes. · `src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedOutputStream.java`
- [Reader wrapper](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedReader.java): io wrapper · Advances progress while reading characters. · `src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedReader.java`
- [Writer wrapper](https://github.com/ctongfei/progressbar/blob/main/src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedWriter.java): io wrapper · Advances progress while writing characters. · `src/main/java/me/tongfei/progressbar/wrapped/ProgressBarWrappedWriter.java`

### Platform

Module and runtime compatibility boundaries.

- [JPMS module](https://github.com/ctongfei/progressbar/blob/main/src/main/java9/module-info.java): module boundary · Java 9 module descriptor for explicit module support. · `src/main/java9/module-info.java`
- **Terminal**: runtime sink · Standard console or terminal output device.

### Other components

- **Client app**: external · User code that performs work and advances progress.

## Connections

- Client app → Bar builder: configure · Client code typically starts by configuring a bar.
- Bar builder → ProgressBar: create · Builder constructs the runtime progress bar.
- Client app → ProgressBar: step · Imperative usage advances progress directly.
- Client app → Iterable wrapper: wrap · Declarative usage can adapt existing sources.
- Client app → Input stream: wrap · I/O sources can be wrapped for automatic tracking.
- Iterable wrapper → Progress state: advance · Wrappers update shared progress state as data is consumed.
- Iterator wrapper → Progress state: advance · Iterator consumption mutates progress state.
- Spliterator wrapper → Progress state: advance · Spliterator traversal mutates progress state.
- Input stream → Progress state: advance · Read operations advance progress state.
- Output stream → Progress state: advance · Write operations advance progress state.
- Reader wrapper → Progress state: advance · Character reads advance progress state.
- Writer wrapper → Progress state: advance · Character writes advance progress state.
- ProgressBar → Progress state: mutate · Imperative API updates the central state.
- Progress state → Renderer: render · State is converted into a display string.
- Renderer → Default renderer: implements · Default renderer provides standard output formatting.
- Default renderer → Style: uses · Rendering depends on style settings and glyph choices.
- Style → Style builder: builds · Style builder configures the visual language.
- Renderer → Text width: measure · Renderer relies on display-width calculations.
- Progress state → Consumer: emit · Rendered updates are sent through a consumer abstraction.
- Consumer → Delegating consumer: compose · Consumers can be wrapped or adapted.
- Delegating consumer → Console consumer: delegate · Delegating consumer can forward to console output.
- Console consumer → Interactive console: variant · Interactive console is the live-redraw variant.
- Interactive console → Terminal utils: inspect · Interactive behavior depends on terminal capabilities.
- Console consumer → Terminal: write · Console consumers ultimately write to the terminal.
- Interactive console → Terminal: redraw · Interactive consumers redraw output on the terminal.
- JPMS module → ProgressBar: exports · JPMS descriptor exposes the public API as a module.