nazmul-nhb/toolbox-x

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.