# nukesor/comfy-table architecture

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

- Interactive diagram: https://gitdiagram.com/nukesor/comfy-table
- Repository: https://github.com/nukesor/comfy-table

## Overview

1. This repository is a single Rust library crate: `comfy-table`, focused on rendering formatted tables for terminal output. There is no server, CLI, or app runtime; the crate is consumed as a dependency and produces a string/table display for the caller to print.

2. The main public API is centered around `Table`, with supporting model types `Row`, `Column`, and `Cell`. These are the core user-facing building blocks: users assemble headers and rows, then configure styling, width, alignment, padding, and content arrangement.

3. `src/table.rs` is the orchestration layer. It owns the table state and coordinates the full render pipeline: collect rows/cells, apply presets/modifiers, determine widths, arrange content, and emit the final formatted output.

4. `src/cell.rs`, `src/row.rs`, and `src/column.rs` are the data-model boundary. They hold per-cell text and styling, row-level content, and column-level configuration such as alignment or constraints. This is where table structure and per-column behavior are defined.

5. Styling is isolated under `src/style/`. It contains separate concerns for attributes, colors, modifiers, presets, and style application at different granularities:
   - cell styling
   - column styling
   - table/border styling
   - reusable preset themes and modifiers
   This keeps visual formatting independent from layout logic.

6. Layout and width management live under `src/utils/arrangement/`. This subsystem is responsible for deciding how content fits into the available table width. The presence of `dynamic.rs`, `disabled.rs`, and `constraint.rs` indicates multiple arrangement modes: no wrapping, dynamic wrapping, and constraint-driven layout.

7. Text measurement and wrapping are handled under `src/utils/formatting/`, especially `content_split/`. This layer is responsible for splitting cell content into lines, respecting width, multiline text, and styling boundaries. It is the bridge between logical cell content and rendered rows.

8. Border and line rendering are also separated in formatting utilities, with `borders.rs` and `content_format.rs`. These modules turn the arranged content into the visual table frame: top/bottom borders, separators, row lines, padding, and alignment-aware placement.

9. The data flow is: user creates a `Table` → adds `Row`/`Cell` data → configures styling and width/preset options → arrangement computes column widths and wrapping → formatting renders borders, padding, and ANSI/custom styling → final string is printed or otherwise consumed.

10. Feature flags materially affect architecture:
   - `tty` enables terminal-size detection and ANSI terminal styling behavior.
   - `custom_styling` allows user-provided escape sequences inside cell text and changes the content-splitting path.
   - `reexport_crossterm` swaps the crate’s mirrored color/attribute types for crossterm’s own types.
   These flags affect both API surface and rendering behavior.

11. The crate is designed for terminal environment compatibility across Linux, macOS, and Windows. When `tty` is enabled and width is not explicitly set, it can query the terminal size via crossterm/terminal APIs; otherwise, layout is driven purely by the caller-provided width.

12. The repository includes strong verification and performance boundaries:
   - `tests/all/` covers layout, styling, wrapping, constraints, UTF-8 handling, truncation, and edge cases.
   - `benches/` measures table-building performance under small and large workloads.
   - GitHub Actions run lint, test, and coverage workflows.
   This suggests the architecture is optimized for correctness and predictable rendering behavior rather than extensibility into nested or spanning tables.

13. Examples under `examples/` show the intended usage patterns and demonstrate the main render pipeline with and without TTY assumptions. They serve as a reference for how the public API maps to rendered output.

14. Architecturally, the important boundary is between table composition/styling on one side and arrangement/formatting on the other. The first side is user-facing and mutable; the second side is internal and deterministic, converting table state into a terminal-safe visual representation.

Main entry points: [`src/table.rs`](https://github.com/nukesor/comfy-table/blob/main/src/table.rs) (Table), [`src/lib.rs`](https://github.com/nukesor/comfy-table/blob/main/src/lib.rs) (crate root), [`src/style/mod.rs`](https://github.com/nukesor/comfy-table/blob/main/src/style/mod.rs) (Styles), [`src/utils/arrangement/mod.rs`](https://github.com/nukesor/comfy-table/blob/main/src/utils/arrangement/mod.rs) (Arrangement)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_api["Public API"]
  node_lib["crate root<br/>facade<br/>[lib.rs]"]
  node_table["Table<br/>orchestrator<br/>[table.rs]"]
  node_row["Row<br/>[row.rs]"]
  node_cell["Cell<br/>[cell.rs]"]
  node_column["Column<br/>[column.rs]"]
  node_feature_flags{{"Feature flags<br/>conditional behavior"}}
end

subgraph group_styling["Styling"]
  node_style_mod["Styles<br/>style system<br/>[mod.rs]"]
  node_style_cell["Cell style<br/>style layer<br/>[cell.rs]"]
  node_style_column["Column style<br/>style layer<br/>[column.rs]"]
  node_style_table["Table style<br/>border style<br/>[table.rs]"]
  node_style_presets["Presets<br/>[presets.rs]"]
end

subgraph group_layout["Layout"]
  node_arrangement_mod["Arrangement<br/>layout engine<br/>[mod.rs]"]
  node_arr_dynamic["Dynamic<br/>wrap mode<br/>[dynamic.rs]"]
  node_arr_disabled["Disabled<br/>layout mode<br/>[disabled.rs]"]
  node_arr_constraint["Constraints<br/>layout rules<br/>[constraint.rs]"]
end

subgraph group_formatting["Formatting"]
  node_fmt_mod["Formatting<br/>rendering layer<br/>[mod.rs]"]
  node_content_split["Split content<br/>text split<br/>[mod.rs]"]
  node_content_format["Content format<br/>rendering helper<br/>[content_format.rs]"]
  node_borders["Borders<br/>frame renderer<br/>[borders.rs]"]
end

node_lib -->|"exports"| node_table
node_lib -->|"exports"| node_row
node_lib -->|"exports"| node_cell
node_lib -->|"exports"| node_column
node_lib -.->|"gates"| node_feature_flags
node_table -->|"builds"| node_row
node_table -->|"contains"| node_cell
node_table -->|"configures"| node_column
node_table -->|"applies"| node_style_mod
node_table -->|"sizes"| node_arrangement_mod
node_table -->|"renders"| node_fmt_mod
node_style_mod -->|"includes"| node_style_cell
node_style_mod -->|"includes"| node_style_column
node_style_mod -->|"includes"| node_style_table
node_style_mod -->|"includes"| node_style_presets
node_arrangement_mod -->|"selects"| node_arr_dynamic
node_arrangement_mod -->|"selects"| node_arr_disabled
node_arrangement_mod -->|"selects"| node_arr_constraint
node_fmt_mod -->|"uses"| node_content_split
node_fmt_mod -->|"uses"| node_content_format
node_fmt_mod -->|"uses"| node_borders
node_content_split -.->|"adapts"| node_feature_flags
node_arr_dynamic -->|"feeds"| node_content_split
node_arr_constraint -->|"drives"| node_arr_dynamic

click node_lib "https://github.com/nukesor/comfy-table/blob/main/src/lib.rs"
click node_table "https://github.com/nukesor/comfy-table/blob/main/src/table.rs"
click node_row "https://github.com/nukesor/comfy-table/blob/main/src/row.rs"
click node_cell "https://github.com/nukesor/comfy-table/blob/main/src/cell.rs"
click node_column "https://github.com/nukesor/comfy-table/blob/main/src/column.rs"
click node_style_mod "https://github.com/nukesor/comfy-table/blob/main/src/style/mod.rs"
click node_style_cell "https://github.com/nukesor/comfy-table/blob/main/src/style/cell.rs"
click node_style_column "https://github.com/nukesor/comfy-table/blob/main/src/style/column.rs"
click node_style_table "https://github.com/nukesor/comfy-table/blob/main/src/style/table.rs"
click node_style_presets "https://github.com/nukesor/comfy-table/blob/main/src/style/presets.rs"
click node_arrangement_mod "https://github.com/nukesor/comfy-table/blob/main/src/utils/arrangement/mod.rs"
click node_arr_dynamic "https://github.com/nukesor/comfy-table/blob/main/src/utils/arrangement/dynamic.rs"
click node_arr_disabled "https://github.com/nukesor/comfy-table/blob/main/src/utils/arrangement/disabled.rs"
click node_arr_constraint "https://github.com/nukesor/comfy-table/blob/main/src/utils/arrangement/constraint.rs"
click node_fmt_mod "https://github.com/nukesor/comfy-table/blob/main/src/utils/formatting/mod.rs"
click node_content_split "https://github.com/nukesor/comfy-table/blob/main/src/utils/formatting/content_split/mod.rs"
click node_content_format "https://github.com/nukesor/comfy-table/blob/main/src/utils/formatting/content_format.rs"
click node_borders "https://github.com/nukesor/comfy-table/blob/main/src/utils/formatting/borders.rs"

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_lib,node_table,node_row,node_cell,node_column,node_feature_flags toneBlue
class node_style_mod,node_style_cell,node_style_column,node_style_table,node_style_presets toneAmber
class node_arrangement_mod,node_arr_dynamic,node_arr_disabled,node_arr_constraint toneMint
class node_fmt_mod,node_content_split,node_content_format,node_borders toneRose
```

## Components

### Public API

User-facing crate surface and feature gates

- [crate root](https://github.com/nukesor/comfy-table/blob/main/src/lib.rs): facade · Public entrypoint exporting the table API and feature-dependent types · `src/lib.rs`
- [Table](https://github.com/nukesor/comfy-table/blob/main/src/table.rs): orchestrator · Owns table state and drives the render pipeline · `src/table.rs`
- [Row](https://github.com/nukesor/comfy-table/blob/main/src/row.rs): content row · Row-level content container · `src/row.rs`
- [Cell](https://github.com/nukesor/comfy-table/blob/main/src/cell.rs): content cell · Per-cell text and styling boundary · `src/cell.rs`
- [Column](https://github.com/nukesor/comfy-table/blob/main/src/column.rs): column config · Per-column alignment and constraint settings · `src/column.rs`
- **Feature flags**: conditional behavior · TTY, custom styling, and crossterm reexport behavior that changes rendering and API types

### Styling

Reusable styling types and preset layers

- [Styles](https://github.com/nukesor/comfy-table/blob/main/src/style/mod.rs): style system · Style namespace tying together attributes, colors, modifiers, and presets · `src/style/mod.rs`
- [Cell style](https://github.com/nukesor/comfy-table/blob/main/src/style/cell.rs): style layer · Cell-specific styling application · `src/style/cell.rs`
- [Column style](https://github.com/nukesor/comfy-table/blob/main/src/style/column.rs): style layer · Column-specific styling application · `src/style/column.rs`
- [Table style](https://github.com/nukesor/comfy-table/blob/main/src/style/table.rs): border style · Table-wide visual rules including borders and frame styling · `src/style/table.rs`
- [Presets](https://github.com/nukesor/comfy-table/blob/main/src/style/presets.rs): theme presets · Reusable preset themes and modifier sets · `src/style/presets.rs`

### Layout

Width management and content arrangement

- [Arrangement](https://github.com/nukesor/comfy-table/blob/main/src/utils/arrangement/mod.rs): layout engine · Chooses how content fits the available table width · `src/utils/arrangement/mod.rs`
- [Dynamic](https://github.com/nukesor/comfy-table/blob/main/src/utils/arrangement/dynamic.rs): wrap mode · Width-sensitive wrapping and dynamic fitting · `src/utils/arrangement/dynamic.rs`
- [Disabled](https://github.com/nukesor/comfy-table/blob/main/src/utils/arrangement/disabled.rs): layout mode · Non-wrapping arrangement path · `src/utils/arrangement/disabled.rs`
- [Constraints](https://github.com/nukesor/comfy-table/blob/main/src/utils/arrangement/constraint.rs): layout rules · Constraint-driven width allocation and column limits · `src/utils/arrangement/constraint.rs`

### Formatting

Rendering content, borders, and line splitting

- [Formatting](https://github.com/nukesor/comfy-table/blob/main/src/utils/formatting/mod.rs): rendering layer · Formatting namespace for borders, content layout, and splitting · `src/utils/formatting/mod.rs`
- [Split content](https://github.com/nukesor/comfy-table/blob/main/src/utils/formatting/content_split/mod.rs): text split · Breaks cell content into renderable lines while respecting width and styling · `src/utils/formatting/content_split/mod.rs`
- [Content format](https://github.com/nukesor/comfy-table/blob/main/src/utils/formatting/content_format.rs): rendering helper · Places aligned content into table rows and padding · `src/utils/formatting/content_format.rs`
- [Borders](https://github.com/nukesor/comfy-table/blob/main/src/utils/formatting/borders.rs): frame renderer · Renders outer borders and row separators · `src/utils/formatting/borders.rs`

## Connections

- crate root → Table: exports · The crate root exposes the main table API
- crate root → Row: exports · Row type is part of the public model
- crate root → Cell: exports · Cell type is part of the public model
- crate root → Column: exports · Column type is part of the public model
- crate root → Feature flags: gates · Feature flags alter public types and rendering behavior
- Table → Row: builds · Table collects rows as its primary content structure
- Table → Cell: contains · Rows are composed of cells during table assembly
- Table → Column: configures · Table uses column settings to drive width and alignment
- Table → Styles: applies · Table-level rendering is styled through the style system
- Table → Arrangement: sizes · Table delegates width computation and wrapping to arrangement
- Table → Formatting: renders · Table hands arranged content to formatting for final output
- Styles → Cell style: includes · Style namespace contains cell styling
- Styles → Column style: includes · Style namespace contains column styling
- Styles → Table style: includes · Style namespace contains table and border styling
- Styles → Presets: includes · Style namespace includes reusable presets and modifiers
- Arrangement → Dynamic: selects · Dynamic wrapping is one arrangement strategy
- Arrangement → Disabled: selects · Disabled wrapping is another arrangement strategy
- Arrangement → Constraints: selects · Constraints guide width allocation and truncation
- Formatting → Split content: uses · Formatting begins by splitting content into lines
- Formatting → Content format: uses · Formatting then aligns and places content
- Formatting → Borders: uses · Formatting adds borders and separators around content
- Split content → Feature flags: adapts · Custom styling and TTY behavior change splitting rules
- Dynamic → Split content: feeds · Wrapped layout depends on line splitting
- Constraints → Dynamic: drives · Constraints influence dynamic width decisions
