# econviz/utility-viz architecture

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

- Interactive diagram: https://gitdiagram.com/econviz/utility-viz
- Repository: https://github.com/econviz/utility-viz

## Overview

utility-viz is a Python toolkit for creating microeconomics diagrams from utility models through equilibrium analysis to rendered and exported figures. The main workflow defines or parses a utility function, solves a consumer optimum, then builds and saves a Canvas; the CLI exposes plotting and closed-form demand output. The graph also preserves documented analysis, diagram, layout, interactive, animation, theme, and TikZ capabilities. Edges cite README-described behavior or shown caller code; unsampled subsystem links are dashed and unverified.

Main entry points: [`utility_viz/cli/plot.py`](https://github.com/econviz/utility-viz/blob/main/utility_viz/cli/plot.py) (Plot command), [`utility_viz/core/canvas/base.py`](https://github.com/econviz/utility-viz/blob/main/utility_viz/core/canvas/base.py) (Canvas), [`utility_viz/models/optimization/solver.py`](https://github.com/econviz/utility-viz/blob/main/utility_viz/models/optimization/solver.py) (Equilibrium solver), [`utility_viz/models/utility/core.py`](https://github.com/econviz/utility-viz/blob/main/utility_viz/models/utility/core.py) (Utility models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI<br/>[main.py]"]
  node_plot_command["Plot command<br/>[plot.py]"]
end

subgraph group_economics["Economic models"]
  node_parser["Utility parser<br/>[parser.py]"]
  node_utility_models["Utility models<br/>[core.py]"]
  node_solver["Equilibrium solver<br/>[solver.py]"]
  node_analysis["Analysis tools"]
  node_paths["Price and income paths<br/>[paths.py]"]
  node_logging["Logging<br/>[logging.py]"]
end

subgraph group_diagrams["Diagram composition"]
  node_canvas["Canvas<br/>[base.py]"]
  node_layers["Diagram layers<br/>[layers.py]"]
  node_demand["Demand diagram<br/>[demand.py]"]
  node_edgeworth["Edgeworth box"]
  node_figure["Multi-panel figure<br/>[figure.py]"]
  node_animation["Animation<br/>[animator.py]"]
end

subgraph group_presentation["Rendering and style"]
  node_themes["Themes<br/>[theme.py]"]
  node_config["Diagram settings<br/>[settings.py]"]
  node_styles["Style objects"]
  node_stroke_rendering["Style application<br/>[stroke.py]"]
  node_exceptions["Package errors<br/>[exceptions.py]"]
end

subgraph group_output["Output and interaction"]
  node_export["Figure export<br/>[exporter.py]"]
  node_tikz["TikZ backend<br/>[renderer.py]"]
  node_widgets["Interactive widgets<br/>[widgets.py]"]
end

node_user(("Python user"))

node_user -->|"defines model"| node_utility_models
node_user -->|"solves optimum"| node_solver
node_user -->|"builds diagram"| node_canvas
node_parser -->|"instantiates model"| node_utility_models
node_solver -->|"evaluates utility"| node_utility_models
node_user -->|"requests analysis"| node_analysis
node_user -->|"builds paths"| node_paths
node_canvas -->|"adds layers"| node_layers
node_canvas -->|"uses theme"| node_themes
node_config -->|"configures theme"| node_themes
node_layers -->|"styles artists"| node_stroke_rendering
node_styles -->|"provides styles"| node_stroke_rendering
node_user -->|"assembles panels"| node_figure
node_figure -->|"creates panels"| node_canvas
node_user -->|"builds demand view"| node_demand
node_user -.->|"builds exchange view"| node_edgeworth
node_user -.->|"animates diagrams"| node_animation
node_user -.->|"uses playground"| node_widgets
node_user -->|"runs command"| node_cli
node_cli -->|"dispatches plot"| node_plot_command
node_plot_command -->|"builds model"| node_parser
node_plot_command -->|"solves optimum"| node_solver
node_plot_command -->|"builds diagram"| node_canvas
node_plot_command -->|"loads settings"| node_config
node_user -->|"saves figure"| node_export
node_export -.->|"renders TikZ"| node_tikz
node_solver -->|"logs progress"| node_logging

click node_cli "https://github.com/econviz/utility-viz/blob/main/utility_viz/cli/main.py"
click node_plot_command "https://github.com/econviz/utility-viz/blob/main/utility_viz/cli/plot.py"
click node_parser "https://github.com/econviz/utility-viz/blob/main/utility_viz/models/utility/parser.py"
click node_utility_models "https://github.com/econviz/utility-viz/blob/main/utility_viz/models/utility/core.py"
click node_solver "https://github.com/econviz/utility-viz/blob/main/utility_viz/models/optimization/solver.py"
click node_analysis "https://github.com/econviz/utility-viz/tree/main/utility_viz/models/optimization"
click node_paths "https://github.com/econviz/utility-viz/blob/main/utility_viz/models/consumer/paths.py"
click node_canvas "https://github.com/econviz/utility-viz/blob/main/utility_viz/core/canvas/base.py"
click node_layers "https://github.com/econviz/utility-viz/blob/main/utility_viz/core/canvas/layers.py"
click node_demand "https://github.com/econviz/utility-viz/blob/main/utility_viz/core/diagrams/consumer/demand.py"
click node_edgeworth "https://github.com/econviz/utility-viz/tree/main/utility_viz/core/diagrams/consumer/edgeworth"
click node_figure "https://github.com/econviz/utility-viz/blob/main/utility_viz/core/layout/figure.py"
click node_animation "https://github.com/econviz/utility-viz/blob/main/utility_viz/core/animation/animator.py"
click node_themes "https://github.com/econviz/utility-viz/blob/main/utility_viz/core/themes/theme.py"
click node_config "https://github.com/econviz/utility-viz/blob/main/utility_viz/core/config/settings.py"
click node_styles "https://github.com/econviz/utility-viz/tree/main/utility_viz/core/styles"
click node_stroke_rendering "https://github.com/econviz/utility-viz/blob/main/utility_viz/core/rendering/stroke.py"
click node_exceptions "https://github.com/econviz/utility-viz/blob/main/utility_viz/core/errors/exceptions.py"
click node_export "https://github.com/econviz/utility-viz/blob/main/utility_viz/core/export/exporter.py"
click node_tikz "https://github.com/econviz/utility-viz/blob/main/utility_viz/core/export/backend_tikz/renderer.py"
click node_widgets "https://github.com/econviz/utility-viz/blob/main/utility_viz/core/interactive/widgets.py"
click node_logging "https://github.com/econviz/utility-viz/blob/main/utility_viz/utils/logging.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_cli,node_plot_command,node_user toneBlue
class node_parser,node_utility_models,node_solver,node_analysis,node_paths,node_logging toneAmber
class node_canvas,node_layers,node_demand,node_edgeworth,node_figure,node_animation toneMint
class node_themes,node_config,node_styles,node_stroke_rendering,node_exceptions toneRose
class node_export,node_tikz,node_widgets toneIndigo
```

## Components

### Entry points

- [CLI](https://github.com/econviz/utility-viz/blob/main/utility_viz/cli/main.py): `utility_viz/cli/main.py`
- [Plot command](https://github.com/econviz/utility-viz/blob/main/utility_viz/cli/plot.py): `utility_viz/cli/plot.py`

### Economic models

- [Utility parser](https://github.com/econviz/utility-viz/blob/main/utility_viz/models/utility/parser.py): `utility_viz/models/utility/parser.py`
- [Utility models](https://github.com/econviz/utility-viz/blob/main/utility_viz/models/utility/core.py): `utility_viz/models/utility/core.py`
- [Equilibrium solver](https://github.com/econviz/utility-viz/blob/main/utility_viz/models/optimization/solver.py): `utility_viz/models/optimization/solver.py`
- [Analysis tools](https://github.com/econviz/utility-viz/tree/main/utility_viz/models/optimization): `utility_viz/models/optimization`
- [Price and income paths](https://github.com/econviz/utility-viz/blob/main/utility_viz/models/consumer/paths.py): `utility_viz/models/consumer/paths.py`
- [Logging](https://github.com/econviz/utility-viz/blob/main/utility_viz/utils/logging.py): `utility_viz/utils/logging.py`

### Diagram composition

- [Canvas](https://github.com/econviz/utility-viz/blob/main/utility_viz/core/canvas/base.py): `utility_viz/core/canvas/base.py`
- [Diagram layers](https://github.com/econviz/utility-viz/blob/main/utility_viz/core/canvas/layers.py): `utility_viz/core/canvas/layers.py`
- [Demand diagram](https://github.com/econviz/utility-viz/blob/main/utility_viz/core/diagrams/consumer/demand.py): `utility_viz/core/diagrams/consumer/demand.py`
- [Edgeworth box](https://github.com/econviz/utility-viz/tree/main/utility_viz/core/diagrams/consumer/edgeworth): `utility_viz/core/diagrams/consumer/edgeworth`
- [Multi-panel figure](https://github.com/econviz/utility-viz/blob/main/utility_viz/core/layout/figure.py): `utility_viz/core/layout/figure.py`
- [Animation](https://github.com/econviz/utility-viz/blob/main/utility_viz/core/animation/animator.py): `utility_viz/core/animation/animator.py`

### Rendering and style

- [Themes](https://github.com/econviz/utility-viz/blob/main/utility_viz/core/themes/theme.py): `utility_viz/core/themes/theme.py`
- [Diagram settings](https://github.com/econviz/utility-viz/blob/main/utility_viz/core/config/settings.py): `utility_viz/core/config/settings.py`
- [Style objects](https://github.com/econviz/utility-viz/tree/main/utility_viz/core/styles): `utility_viz/core/styles`
- [Style application](https://github.com/econviz/utility-viz/blob/main/utility_viz/core/rendering/stroke.py): `utility_viz/core/rendering/stroke.py`
- [Package errors](https://github.com/econviz/utility-viz/blob/main/utility_viz/core/errors/exceptions.py): `utility_viz/core/errors/exceptions.py`

### Output and interaction

- [Figure export](https://github.com/econviz/utility-viz/blob/main/utility_viz/core/export/exporter.py): `utility_viz/core/export/exporter.py`
- [TikZ backend](https://github.com/econviz/utility-viz/blob/main/utility_viz/core/export/backend_tikz/renderer.py): `utility_viz/core/export/backend_tikz/renderer.py`
- [Interactive widgets](https://github.com/econviz/utility-viz/blob/main/utility_viz/core/interactive/widgets.py): `utility_viz/core/interactive/widgets.py`

### Other components

- **Python user**

## Connections

- Python user → Utility models: defines model
- Python user → Equilibrium solver: solves optimum
- Python user → Canvas: builds diagram
- Utility parser → Utility models: instantiates model (evidence: `utility_viz/models/utility/parser.py`)
- Equilibrium solver → Utility models: evaluates utility (evidence: `utility_viz/models/optimization/solver.py`)
- Python user → Analysis tools: requests analysis
- Python user → Price and income paths: builds paths
- Canvas → Diagram layers: adds layers (evidence: `utility_viz/core/canvas/layers.py`)
- Canvas → Themes: uses theme (evidence: `utility_viz/core/canvas/base.py`)
- Diagram settings → Themes: configures theme (evidence: `utility_viz/core/config/settings.py`)
- Diagram layers → Style application: styles artists (evidence: `utility_viz/core/canvas/layers.py`)
- Style objects → Style application: provides styles (evidence: `utility_viz/core/rendering/stroke.py`)
- Python user → Multi-panel figure: assembles panels
- Multi-panel figure → Canvas: creates panels (evidence: `utility_viz/core/layout/figure.py`)
- Python user → Demand diagram: builds demand view
- Python user → Edgeworth box: builds exchange view
- Python user → Animation: animates diagrams
- Python user → Interactive widgets: uses playground
- Python user → CLI: runs command
- CLI → Plot command: dispatches plot (evidence: `utility_viz/cli/main.py`)
- Plot command → Utility parser: builds model (evidence: `utility_viz/cli/plot.py`)
- Plot command → Equilibrium solver: solves optimum (evidence: `utility_viz/cli/plot.py`)
- Plot command → Canvas: builds diagram (evidence: `utility_viz/cli/plot.py`)
- Plot command → Diagram settings: loads settings (evidence: `utility_viz/cli/plot.py`)
- Python user → Figure export: saves figure
- Figure export → TikZ backend: renders TikZ
- Equilibrium solver → Logging: logs progress (evidence: `utility_viz/models/optimization/solver.py`)
