# xulbux/python-lib-xulbux architecture

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

- Interactive diagram: https://gitdiagram.com/xulbux/python-lib-xulbux
- Repository: https://github.com/xulbux/python-lib-xulbux

## Overview

xulbux is a Python utility library whose principal workflow is importing a top-level API, applying a utility to caller-provided values or terminal interaction, and receiving a result or terminal output. Its documented capability areas are terminal styling and interaction, color manipulation, data and string processing, filesystem operations, and system automation. The graph preserves the indexed core modules and CLI components; source excerpts and the index establish some module references, but not all runtime call paths, so uncertain links are omitted.

Main entry points: [`src/xulbux/__init__.py`](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/__init__.py) (Lazy public API), [`src/xulbux/fs.py`](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/fs.py) (Filesystem and JSON), [`src/xulbux/cli/_main.py`](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/cli/_main.py) (CLI entry), [`src/xulbux/console.py`](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/console.py) (Console interaction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Library API"]
  node_api["Lazy public API<br/>[__init__.py]"]
end

subgraph group_terminal["Terminal and Color"]
  node_ansi["ANSI styling<br/>[ansi.py]"]
  node_color["Color models<br/>[color.py]"]
  node_console["Console interaction<br/>[console.py]"]
  node_cli_main["CLI entry<br/>[_main.py]"]
  node_cli_ansi["ANSI CLI<br/>[ansi.py]"]
  node_cli_256["256-color CLI<br/>[color256.py]"]
  node_cli_true["True-color CLI<br/>[true_color.py]"]
  node_cli_help["CLI help<br/>[help.py]"]
end

subgraph group_data["Data and System Utilities"]
  node_data_ops["Nested data<br/>[data.py]"]
  node_strings["String utilities<br/>[string.py]"]
  node_regex["Regex utilities<br/>[regex.py]"]
  node_filesystem["Filesystem and JSON<br/>[fs.py]"]
  node_system["System automation<br/>[system.py]"]
end

subgraph group_internal["Shared Internals"]
  node_constants["Shared constants<br/>[consts.py]"]
  node_types["Shared types<br/>[types.py]"]
  node_decorators["Shared decorators<br/>[decorators.py]"]
  node_exceptions["Shared exceptions<br/>[exceptions.py]"]
end

node_caller(("Python caller"))

node_caller -->|"imports"| node_api
node_api -->|"lazy-loads"| node_ansi
node_api -->|"lazy-loads"| node_color
node_api -->|"lazy-loads"| node_console
node_api -->|"lazy-loads"| node_data_ops
node_api -->|"lazy-loads"| node_filesystem
node_api -->|"lazy-loads"| node_regex
node_api -->|"lazy-loads"| node_strings
node_api -->|"lazy-loads"| node_system
node_cli_main -.->|"dispatches"| node_cli_ansi
node_cli_main -.->|"dispatches"| node_cli_256
node_cli_main -.->|"dispatches"| node_cli_true
node_cli_main -.->|"dispatches"| node_cli_help
node_filesystem -->|"uses"| node_data_ops
node_filesystem -->|"uses"| node_strings
node_strings -->|"uses"| node_data_ops
node_data_ops -->|"uses"| node_strings
node_color -->|"uses"| node_regex
node_ansi -->|"uses"| node_color
node_console -->|"uses"| node_ansi
node_console -->|"uses"| node_constants
node_system -->|"uses"| node_console
node_system -->|"uses"| node_filesystem
node_regex -->|"uses"| node_decorators
node_filesystem -->|"uses"| node_exceptions

click node_api "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/__init__.py"
click node_ansi "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/ansi.py"
click node_color "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/color.py"
click node_console "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/console.py"
click node_cli_main "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/cli/_main.py"
click node_cli_ansi "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/cli/ansi.py"
click node_cli_256 "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/cli/color256.py"
click node_cli_true "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/cli/true_color.py"
click node_cli_help "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/cli/help.py"
click node_data_ops "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/data.py"
click node_strings "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/string.py"
click node_regex "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/regex.py"
click node_filesystem "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/fs.py"
click node_system "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/system.py"
click node_constants "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/base/consts.py"
click node_types "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/base/types.py"
click node_decorators "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/base/decorators.py"
click node_exceptions "https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/base/exceptions.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 toneBlue
class node_ansi,node_color,node_console,node_cli_main,node_cli_ansi,node_cli_256,node_cli_true,node_cli_help toneAmber
class node_data_ops,node_strings,node_regex,node_filesystem,node_system toneMint
class node_constants,node_types,node_decorators,node_exceptions toneRose
class node_caller toneIndigo
```

## Components

### Library API

- [Lazy public API](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/__init__.py): `src/xulbux/__init__.py`

### Terminal and Color

- [ANSI styling](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/ansi.py): `src/xulbux/ansi.py`
- [Color models](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/color.py): `src/xulbux/color.py`
- [Console interaction](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/console.py): `src/xulbux/console.py`
- [CLI entry](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/cli/_main.py): `src/xulbux/cli/_main.py`
- [ANSI CLI](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/cli/ansi.py): `src/xulbux/cli/ansi.py`
- [256-color CLI](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/cli/color256.py): `src/xulbux/cli/color256.py`
- [True-color CLI](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/cli/true_color.py): `src/xulbux/cli/true_color.py`
- [CLI help](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/cli/help.py): `src/xulbux/cli/help.py`

### Data and System Utilities

- [Nested data](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/data.py): `src/xulbux/data.py`
- [String utilities](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/string.py): `src/xulbux/string.py`
- [Regex utilities](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/regex.py): `src/xulbux/regex.py`
- [Filesystem and JSON](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/fs.py): `src/xulbux/fs.py`
- [System automation](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/system.py): `src/xulbux/system.py`

### Shared Internals

- [Shared constants](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/base/consts.py): `src/xulbux/base/consts.py`
- [Shared types](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/base/types.py): `src/xulbux/base/types.py`
- [Shared decorators](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/base/decorators.py): `src/xulbux/base/decorators.py`
- [Shared exceptions](https://github.com/xulbux/python-lib-xulbux/blob/main/src/xulbux/base/exceptions.py): `src/xulbux/base/exceptions.py`

### Other components

- **Python caller**

## Connections

- Python caller → Lazy public API: imports (evidence: `README.md`)
- Lazy public API → ANSI styling: lazy-loads (evidence: `src/xulbux/__init__.py`)
- Lazy public API → Color models: lazy-loads (evidence: `src/xulbux/__init__.py`)
- Lazy public API → Console interaction: lazy-loads (evidence: `src/xulbux/__init__.py`)
- Lazy public API → Nested data: lazy-loads (evidence: `src/xulbux/__init__.py`)
- Lazy public API → Filesystem and JSON: lazy-loads (evidence: `src/xulbux/__init__.py`)
- Lazy public API → Regex utilities: lazy-loads (evidence: `src/xulbux/__init__.py`)
- Lazy public API → String utilities: lazy-loads (evidence: `src/xulbux/__init__.py`)
- Lazy public API → System automation: lazy-loads (evidence: `src/xulbux/__init__.py`)
- CLI entry → ANSI CLI: dispatches (evidence: `src/xulbux/cli/_main.py`)
- CLI entry → 256-color CLI: dispatches (evidence: `src/xulbux/cli/_main.py`)
- CLI entry → True-color CLI: dispatches (evidence: `src/xulbux/cli/_main.py`)
- CLI entry → CLI help: dispatches (evidence: `src/xulbux/cli/_main.py`)
- Filesystem and JSON → Nested data: uses (evidence: `src/xulbux/fs.py`)
- Filesystem and JSON → String utilities: uses (evidence: `src/xulbux/fs.py`)
- String utilities → Nested data: uses (evidence: `src/xulbux/string.py`)
- Nested data → String utilities: uses (evidence: `src/xulbux/data.py`)
- Color models → Regex utilities: uses (evidence: `src/xulbux/color.py`)
- ANSI styling → Color models: uses (evidence: `src/xulbux/ansi.py`)
- Console interaction → ANSI styling: uses (evidence: `src/xulbux/console.py`)
- Console interaction → Shared constants: uses (evidence: `src/xulbux/console.py`)
- System automation → Console interaction: uses (evidence: `src/xulbux/system.py`)
- System automation → Filesystem and JSON: uses (evidence: `src/xulbux/system.py`)
- Regex utilities → Shared decorators: uses (evidence: `src/xulbux/regex.py`)
- Filesystem and JSON → Shared exceptions: uses (evidence: `src/xulbux/fs.py`)
