# nazmul-nhb/toolbox-x architecture

> Architecture diagram of the GitHub repository nazmul-nhb/toolbox-x, 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/nazmul-nhb/toolbox-x
- Repository: https://github.com/nazmul-nhb/toolbox-x

## Overview

1. **Repository shape**
   - This is a **TypeScript utility library** (`toolbox-x`) plus a **separate documentation site** in `docs/`.
   - The root package is the publishable library; the docs app is a Next.js application that consumes the library source and generated metadata.

2. **Primary runtime boundary**
   - The reusable product is the **`src/` library**.
   - The website, API routes, MDX content, and UI live under **`docs/`** and are isolated from the library package.
   - There is no database or long-lived backend in the tree; the only server-side pieces are Next.js route handlers in the docs app.

3. **Library architecture**
   - `src/index.ts` is the top-level export surface.
   - The code is organized by domain: `array`, `colors`, `converter`, `date`, `dom`, `form`, `guards`, `hash`, `http-status`, `number`, `object`, `pluralizer`, `string`, `stylog`, `verbalizer`, `paginator`, and shared `utils`.
   - Each domain has its own entrypoint plus internal helpers/constants/types, which makes the package modular and tree-shakeable.

4. **Core design pattern**
   - The library combines **functions, classes, and type utilities**.
   - Classes such as `Color`, `Finder`, `Converter`, `Paginator`, `Pluralizer`, `Verbalizer`, and `Stylog` encapsulate richer behaviors.
   - Smaller modules provide stateless helpers, validation guards, and constants that those classes and functions reuse.

5. **Cross-cutting support layer**
   - `src/guards`, `src/types`, and `src/constants` are shared building blocks used across domains.
   - Guards provide runtime validation and type narrowing; the `types/` folders define the public TypeScript surface area.
   - This support layer keeps the domain modules consistent without introducing external dependencies.

6. **Packaging and subpath exports**
   - The README examples show subpath imports like `toolbox-x/pluralizer` and `toolbox-x/dom`, so the package is designed with **feature-level exports**, not just a single monolith.
   - Build configuration lives at the root (`tsdown.config.ts` and `tsconfig.json`), indicating the library is compiled and bundled for npm distribution.

7. **Documentation source pipeline**
   - The docs content is stored as **MDX files** under `docs/content/docs/`, grouped to mirror the library domains.
   - Per-folder `meta.json` files suggest the content is structured as a navigable docs catalog, not hand-written standalone pages.
   - `docs/source.config.ts` and the generated files in `docs/lib/` indicate a content-processing step that turns source metadata into app-ready navigation/module data.

8. **Docs application**
   - `docs/app/` is a **Next.js App Router** site with pages for the home screen and the documentation pages.
   - `docs/components/` contains the reusable UI for rendering docs, MDX content, tabs, accordion, code-copy, AI widgets, and other presentation pieces.
   - `docs/hooks/` and `docs/lib/` provide client/shared behavior such as layout helpers, URL handling, source mapping, and generated module metadata.

9. **Search, chat, and LLM-facing endpoints**
   - The docs app exposes server routes at `docs/app/api/search/route.ts` and `docs/app/api/chat/route.ts`.
   - It also publishes LLM-oriented text endpoints: `llms.txt`, `llms-full.txt`, and `llms.mdx`, which are typically used for machine-readable documentation access.
   - The data flow here is: **docs content → generated/searchable indexes → API routes → docs UI and AI widgets**.

10. **Static media and SEO surfaces**
   - The docs app includes Open Graph generation (`opengraph-image.tsx` and `docs/app/og/...`) for shareable preview images.
   - `docs/public/` and page-level layout files handle site assets, metadata, and rendering structure.

11. **Tooling and quality gates**
   - Formatting/linting is handled by **Biome** (`biome.json`), and pre-commit automation is wired through **Husky**.
   - The repo uses **pnpm workspaces** and a root-level `package.json`/`pnpm-lock.yaml` to coordinate the package and docs app.
   - Scripts under `scripts/` and `docs/scripts/` manage release metadata, changelog generation, link validation, and type generation.

12. **Release and distribution**
   - CI/CD is centered on `.github/workflows/publish.yml`, which publishes the package to **npm**.
   - Supporting scripts like `generate-changelog.mjs` and `pull-main.mjs` indicate a release workflow that keeps the changelog and main branch in sync.
   - The external services that materially matter here are **GitHub Actions** for automation and **npm** for package distribution.

Main entry points: [`docs/app`](https://github.com/nazmul-nhb/toolbox-x/tree/main/docs/app) (App router), [`src/index.ts`](https://github.com/nazmul-nhb/toolbox-x/blob/main/src/index.ts) (src/index), [`docs/content/docs`](https://github.com/nazmul-nhb/toolbox-x/tree/main/docs/content/docs) (Docs content), [`docs/lib`](https://github.com/nazmul-nhb/toolbox-x/tree/main/docs/lib) (docs/lib)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["Library"]
  node_src_index["src/index<br/>library entrypoint<br/>[index.ts]"]
  node_src_domains["Domains<br/>feature modules"]
  node_src_classes["Classes<br/>behavioral objects"]
  node_src_helpers["Helpers<br/>shared support"]
  node_src_array["array<br/>domain module"]
  node_src_colors["colors<br/>domain module"]
  node_src_converter["converter<br/>domain module"]
  node_src_date["date<br/>domain module"]
  node_src_dom["dom"]
  node_src_form["form<br/>domain module"]
  node_src_hash["hash<br/>domain module"]
  node_src_number["number<br/>domain module"]
  node_src_object["object<br/>domain module"]
  node_src_string["string<br/>domain module"]
  node_src_stylog["stylog<br/>domain module"]
  node_src_verbalizer["verbalizer<br/>domain module"]
  node_src_paginator["paginator<br/>utility class<br/>[paginator.ts]"]
  node_src_types["types<br/>type surface"]
end

subgraph group_docs["Docs App"]
  node_docs_content["Docs content<br/>mdx catalog"]
  node_docs_lib["docs/lib<br/>generated helpers"]
  node_docs_app["App router<br/>next.js app"]
  node_docs_components["UI components<br/>presentation layer"]
  node_docs_routes["API routes<br/>server handlers"]
  node_docs_og["OG images<br/>social media assets"]
end

subgraph group_tooling["Tooling"]
  node_tooling_root["Tooling<br/>repo automation"]
end

node_src_index -->|"exports"| node_src_domains
node_src_index -->|"exports"| node_src_classes
node_src_index -.->|"shares"| node_src_helpers
node_src_domains -->|"includes"| node_src_array
node_src_domains -->|"includes"| node_src_colors
node_src_domains -->|"includes"| node_src_converter
node_src_domains -->|"includes"| node_src_date
node_src_domains -->|"includes"| node_src_dom
node_src_domains -->|"includes"| node_src_form
node_src_domains -->|"includes"| node_src_hash
node_src_domains -->|"includes"| node_src_number
node_src_domains -->|"includes"| node_src_object
node_src_domains -->|"includes"| node_src_string
node_src_domains -->|"includes"| node_src_stylog
node_src_domains -->|"includes"| node_src_verbalizer
node_src_classes -->|"includes"| node_src_paginator
node_src_classes -.->|"shares"| node_src_helpers
node_src_helpers -->|"defines"| node_src_types
node_docs_content -->|"generates"| node_docs_lib
node_docs_lib -->|"feeds"| node_docs_app
node_docs_content -->|"renders"| node_docs_app
node_docs_app -->|"uses"| node_docs_components
node_docs_app -->|"hosts"| node_docs_routes
node_docs_app -->|"hosts"| node_docs_og
node_docs_routes -.->|"indexes"| node_docs_content
node_tooling_root -->|"builds"| node_src_index
node_tooling_root -->|"manages"| node_docs_app
node_tooling_root -.->|"validates"| node_docs_content

click node_src_index "https://github.com/nazmul-nhb/toolbox-x/blob/main/src/index.ts"
click node_src_array "https://github.com/nazmul-nhb/toolbox-x/tree/main/src/array"
click node_src_colors "https://github.com/nazmul-nhb/toolbox-x/tree/main/src/colors"
click node_src_converter "https://github.com/nazmul-nhb/toolbox-x/tree/main/src/converter"
click node_src_date "https://github.com/nazmul-nhb/toolbox-x/tree/main/src/date"
click node_src_dom "https://github.com/nazmul-nhb/toolbox-x/tree/main/src/dom"
click node_src_form "https://github.com/nazmul-nhb/toolbox-x/tree/main/src/form"
click node_src_hash "https://github.com/nazmul-nhb/toolbox-x/tree/main/src/hash"
click node_src_number "https://github.com/nazmul-nhb/toolbox-x/tree/main/src/number"
click node_src_object "https://github.com/nazmul-nhb/toolbox-x/tree/main/src/object"
click node_src_string "https://github.com/nazmul-nhb/toolbox-x/tree/main/src/string"
click node_src_stylog "https://github.com/nazmul-nhb/toolbox-x/tree/main/src/stylog"
click node_src_verbalizer "https://github.com/nazmul-nhb/toolbox-x/tree/main/src/verbalizer"
click node_src_paginator "https://github.com/nazmul-nhb/toolbox-x/blob/main/src/paginator.ts"
click node_src_types "https://github.com/nazmul-nhb/toolbox-x/tree/main/src/types"
click node_docs_content "https://github.com/nazmul-nhb/toolbox-x/tree/main/docs/content/docs"
click node_docs_lib "https://github.com/nazmul-nhb/toolbox-x/tree/main/docs/lib"
click node_docs_app "https://github.com/nazmul-nhb/toolbox-x/tree/main/docs/app"
click node_docs_components "https://github.com/nazmul-nhb/toolbox-x/tree/main/docs/components"
click node_docs_og "https://github.com/nazmul-nhb/toolbox-x/tree/main/docs/app/og"

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_src_index,node_src_domains,node_src_classes,node_src_helpers,node_src_array,node_src_colors,node_src_converter,node_src_date,node_src_dom,node_src_form,node_src_hash,node_src_number,node_src_object,node_src_string,node_src_stylog,node_src_verbalizer,node_src_paginator,node_src_types toneBlue
class node_docs_content,node_docs_lib,node_docs_app,node_docs_components,node_docs_routes,node_docs_og toneAmber
class node_tooling_root toneMint
```

## Components

### Library

Publishable TypeScript utility package under src/

- [src/index](https://github.com/nazmul-nhb/toolbox-x/blob/main/src/index.ts): library entrypoint · Top-level export surface for the package · `src/index.ts`
- **Domains**: feature modules · Core utility domains exposed as subpath exports
- **Classes**: behavioral objects · Rich stateful utilities such as Color, Finder, Converter, and friends
- **Helpers**: shared support · Cross-cutting guards, constants, types, and shared utilities
- [array](https://github.com/nazmul-nhb/toolbox-x/tree/main/src/array): domain module · Array operations, sorting, search, and transformation helpers · `src/array`
- [colors](https://github.com/nazmul-nhb/toolbox-x/tree/main/src/colors): domain module · Color parsing, conversion, and generation tools · `src/colors`
- [converter](https://github.com/nazmul-nhb/toolbox-x/tree/main/src/converter): domain module · Measurement conversion system across unit families · `src/converter`
- [date](https://github.com/nazmul-nhb/toolbox-x/tree/main/src/date): domain module · Date/time parsing, calculation, and timezone helpers · `src/date`
- [dom](https://github.com/nazmul-nhb/toolbox-x/tree/main/src/dom): domain module · Browser-oriented query and storage helpers · `src/dom`
- [form](https://github.com/nazmul-nhb/toolbox-x/tree/main/src/form): domain module · Form data conversion and transformation helpers · `src/form`
- [hash](https://github.com/nazmul-nhb/toolbox-x/tree/main/src/hash): domain module · Encoding, hashing, and UUID utilities · `src/hash`
- [number](https://github.com/nazmul-nhb/toolbox-x/tree/main/src/number): domain module · Numeric calculations, formatting, and sequences · `src/number`
- [object](https://github.com/nazmul-nhb/toolbox-x/tree/main/src/object): domain module · Object shaping, cloning, merging, and sanitizing helpers · `src/object`
- [string](https://github.com/nazmul-nhb/toolbox-x/tree/main/src/string): domain module · String case, extraction, normalization, and diff helpers · `src/string`
- [stylog](https://github.com/nazmul-nhb/toolbox-x/tree/main/src/stylog): domain module · Console styling and log formatting utilities · `src/stylog`
- [verbalizer](https://github.com/nazmul-nhb/toolbox-x/tree/main/src/verbalizer): domain module · Rule-based text verbalization and generation · `src/verbalizer`
- [paginator](https://github.com/nazmul-nhb/toolbox-x/blob/main/src/paginator.ts): utility class · Pagination helper exposed as a standalone module · `src/paginator.ts`
- [types](https://github.com/nazmul-nhb/toolbox-x/tree/main/src/types): type surface · Shared TypeScript definitions for public APIs · `src/types`

### Docs App

Next.js documentation site and content pipeline under docs/

- [Docs content](https://github.com/nazmul-nhb/toolbox-x/tree/main/docs/content/docs): mdx catalog · MDX documentation source organized by library domain · `docs/content/docs`
- [docs/lib](https://github.com/nazmul-nhb/toolbox-x/tree/main/docs/lib): generated helpers · Generated metadata and shared app-side source utilities · `docs/lib`
- [App router](https://github.com/nazmul-nhb/toolbox-x/tree/main/docs/app): next.js app · Docs site routes, layouts, and page rendering · `docs/app`
- [UI components](https://github.com/nazmul-nhb/toolbox-x/tree/main/docs/components): presentation layer · Reusable docs, MDX, and interactive UI components · `docs/components`
- **API routes**: server handlers · Search, chat, and machine-readable documentation endpoints
- [OG images](https://github.com/nazmul-nhb/toolbox-x/tree/main/docs/app/og): social media assets · Open Graph image generation and share previews · `docs/app/og`

### Tooling

Repo-level build, quality, and release automation

- **Tooling**: repo automation · Workspace config, linting, scripts, and release automation

## Connections

- src/index → Domains: exports · Re-exports the domain modules as the package surface
- src/index → Classes: exports · Exposes class-based utilities from the top-level entry
- src/index → Helpers: shares · Relies on common guards, constants, and types
- Domains → array: includes · Array utilities
- Domains → colors: includes · Color utilities
- Domains → converter: includes · Unit conversion utilities
- Domains → date: includes · Date and time utilities
- Domains → dom: includes · Browser helpers
- Domains → form: includes · Form helpers
- Domains → hash: includes · Hashing and encoding utilities
- Domains → number: includes · Numeric utilities
- Domains → object: includes · Object utilities
- Domains → string: includes · String utilities
- Domains → stylog: includes · Logging style utilities
- Domains → verbalizer: includes · Text verbalization utilities
- Classes → paginator: includes · Standalone pagination class entry
- Classes → Helpers: shares · Uses shared validation and types
- Helpers → types: defines · Type declarations used across modules
- Docs content → docs/lib: generates · Source metadata is transformed into app-ready structures
- docs/lib → App router: feeds · Provides shared layout, source, and navigation data
- Docs content → App router: renders · MDX docs are served through the app routes
- App router → UI components: uses · Pages compose reusable presentation components
- App router → API routes: hosts · Search and chat endpoints live in the app router
- App router → OG images: hosts · Open Graph image routes and previews
- API routes → Docs content: indexes · Search/chat endpoints consume docs content and metadata
- Tooling → src/index: builds · Root TypeScript build and packaging target
- Tooling → App router: manages · Workspace tooling also supports the docs site
- Tooling → Docs content: validates · Scripts handle changelog, links, and generated types