# nazmul-nhb/chronos-date architecture

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

## Overview

1. **Repository shape**
   - This repo is split into two major surfaces: a **published TypeScript date-time library** under `src/`, and a **Next.js documentation site** under `docs/`.
   - The library is the product; the docs app is both marketing/docs and an interactive reference surface for the library.

2. **Core library boundary**
   - `src/index.ts` is the main package entry, with additional subpath exports implied by the README (`/guards`, `/utils`, `/types`, `/constants`, `/plugins`).
   - The library is designed for **tree-shakeable imports** and **framework-agnostic usage** across Node, browser, Deno, and Bun.

3. **Primary runtime model**
   - `src/core/Chronos.ts` and `src/core/chronos-fn.ts` define the main runtime abstraction: an **immutable date-time wrapper** plus a function-style convenience wrapper.
   - The Chronos API is the central orchestrator; higher-level operations like formatting, comparison, parsing, and manipulation are built on top of it.

4. **Supporting utility layer**
   - `src/utils/` holds reusable date logic split into concerns such as **calculation**, **comparison**, **formatting**, **parsing**, and generic helpers.
   - These utilities are the shared dependency surface used by the core class, plugins, guards, and type utilities rather than being directly exposed as a monolith.

5. **Plugin architecture**
   - `src/plugins/` contains the extension modules that add domain-specific behavior, such as timezone, season, zodiac, business rules, greeting/day-part logic, relative time, and rounding.
   - The README’s `Chronos.use(plugin)` model indicates a **global/plugin-registration boundary**: plugins extend the core Chronos capability set without changing the base API.

6. **Validation, constants, and types**
   - `src/guards.ts`, `src/constants/`, and `src/types/` form the library’s “static” support layer.
   - Guards provide runtime validation, constants encode reusable calendrical/domain data, and types define the public TypeScript contract for inputs, formats, plugin extensions, and Chronos-specific shapes.

7. **Documentation source of truth**
   - The docs content lives in `docs/content/docs/**` as MDX pages organized by feature area: Chronos API, plugins, guards, utils, installation, quick start, and changelog.
   - Many sections have `meta.json` files, suggesting a structured content model used to drive navigation and page generation.

8. **Docs application layer**
   - `docs/app/` is a Next.js App Router site that renders the content tree, with routes for the home page, docs pages, and several special outputs.
   - `docs/app/docs/[[...slug]]/page.tsx` is the main documentation page renderer, while `docs/app/layout.tsx` and `docs/app/global.css` define the site shell and styling.

9. **Docs tooling and generated metadata**
   - `docs/lib/` contains source integration code and generated artifacts such as `.generated-modules.ts`, `.generated-types.json`, and a cache file, indicating a build-time content/type generation step.
   - `docs/source.config.ts` likely defines how MDX content is discovered and transformed into these generated docs primitives.

10. **Interactive docs features**
   - The docs site includes specialized UI components for code copy, tabs, accordion/collapsible panels, markdown rendering, playgrounds, and AI/search experiences.
   - `docs/app/api/search/route.ts` and `docs/app/api/chat/route.ts` expose server-side endpoints for search and assistant-style interactions within the documentation experience.

11. **Machine-readable and shareable documentation outputs**
   - The docs app includes `llms.txt`, `llms.mdx`, `llms-full.txt`, and a docs-specific `llms.mdx/docs/...` route, which indicates deliberate support for LLM-readable documentation exports.
   - There is also Open Graph image generation under `docs/app/opengraph-image.tsx` and `docs/app/og/**`, supporting social/link previews.

12. **Build, release, and repository automation**
   - `tsdown.config.ts`, `biome.json`, and the root `package.json` suggest a TypeScript-first build and lint/format toolchain for the library package.
   - GitHub Actions (`.github/workflows/publish.yml`) handle publishing, while `scripts/` contains repository automation such as changelog generation, copying static chronos assets into docs, and pulling mainline changes.
   - Husky pre-commit hooks and link validation scripts indicate the repo treats **documentation correctness and package release quality** as part of the architecture, not an afterthought.

Main entry points: [`docs/app`](https://github.com/nazmul-nhb/chronos-date/tree/main/docs/app) (Docs app), [`src/index.ts`](https://github.com/nazmul-nhb/chronos-date/blob/main/src/index.ts) (Entry), [`src/core/Chronos.ts`](https://github.com/nazmul-nhb/chronos-date/blob/main/src/core/Chronos.ts) (Chronos), [`src/guards.ts`](https://github.com/nazmul-nhb/chronos-date/blob/main/src/guards.ts) (Static support)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["Library"]
  node_src_entry["Entry<br/>[index.ts]"]
  node_chronos_core(("Chronos<br/>runtime core<br/>[Chronos.ts]"))
  node_chronos_fn(("Wrapper fn<br/>factory helper<br/>[chronos-fn.ts]"))
  node_utils_layer["Utils<br/>shared helpers<br/>[index.ts]"]
  node_plugins_layer["Plugins<br/>extension modules"]
  node_support_static["Static support<br/>guards/constants/types<br/>[guards.ts]"]
  node_constants_mod["Constants<br/>calendar data<br/>[index.ts]"]
  node_types_mod["Types<br/>[index.ts]"]
end

subgraph group_docs["Docs site"]
  node_doc_content["Content tree<br/>mdx docs"]
  node_doc_app["Docs app<br/>next app"]
  node_doc_page["Doc page<br/>route renderer<br/>[page.tsx]"]
  node_doc_layout["Site shell<br/>layout and styles<br/>[layout.tsx]"]
  node_doc_api["AI/search API<br/>server routes"]
  node_doc_llms["LLM outputs<br/>machine-readable docs<br/>[llms.txt]"]
  node_doc_og["Open Graph<br/>preview images"]
  node_doc_components["UI components<br/>docs ui"]
  node_doc_lib["Docs lib<br/>build-time helpers"]
end

subgraph group_automation["Automation"]
  node_root_pkg["Package<br/>monorepo root<br/>[package.json]"]
  node_build_release["Build & release<br/>tooling<br/>[tsdown.config.ts]"]
end

node_root_pkg -->|"packages"| node_src_entry
node_root_pkg -->|"workspace"| node_doc_app
node_src_entry -->|"exports"| node_chronos_core
node_src_entry -->|"exports"| node_chronos_fn
node_chronos_core -->|"uses"| node_utils_layer
node_chronos_core -->|"uses"| node_support_static
node_chronos_fn -->|"wraps"| node_chronos_core
node_plugins_layer -->|"extends"| node_chronos_core
node_plugins_layer -->|"depends on"| node_utils_layer
node_support_static -->|"includes"| node_constants_mod
node_support_static -->|"defines"| node_types_mod
node_doc_app -->|"renders"| node_doc_page
node_doc_app -->|"shell"| node_doc_layout
node_doc_app -->|"serves"| node_doc_api
node_doc_app -->|"exports"| node_doc_llms
node_doc_app -->|"generates"| node_doc_og
node_doc_page -->|"reads"| node_doc_content
node_doc_app -->|"uses"| node_doc_components
node_doc_app -->|"depends on"| node_doc_lib
node_doc_lib -->|"indexes"| node_doc_content
node_doc_lib -.->|"references"| node_src_entry
node_build_release -->|"builds"| node_src_entry
node_build_release -->|"maintains"| node_doc_app

click node_root_pkg "https://github.com/nazmul-nhb/chronos-date/blob/main/package.json"
click node_src_entry "https://github.com/nazmul-nhb/chronos-date/blob/main/src/index.ts"
click node_chronos_core "https://github.com/nazmul-nhb/chronos-date/blob/main/src/core/Chronos.ts"
click node_chronos_fn "https://github.com/nazmul-nhb/chronos-date/blob/main/src/core/chronos-fn.ts"
click node_utils_layer "https://github.com/nazmul-nhb/chronos-date/blob/main/src/utils/index.ts"
click node_plugins_layer "https://github.com/nazmul-nhb/chronos-date/tree/main/src/plugins"
click node_support_static "https://github.com/nazmul-nhb/chronos-date/blob/main/src/guards.ts"
click node_constants_mod "https://github.com/nazmul-nhb/chronos-date/blob/main/src/constants/index.ts"
click node_types_mod "https://github.com/nazmul-nhb/chronos-date/blob/main/src/types/index.ts"
click node_doc_content "https://github.com/nazmul-nhb/chronos-date/tree/main/docs/content/docs"
click node_doc_app "https://github.com/nazmul-nhb/chronos-date/tree/main/docs/app"
click node_doc_page "https://github.com/nazmul-nhb/chronos-date/blob/main/docs/app/docs/[[...slug]]/page.tsx"
click node_doc_layout "https://github.com/nazmul-nhb/chronos-date/blob/main/docs/app/layout.tsx"
click node_doc_api "https://github.com/nazmul-nhb/chronos-date/tree/main/docs/app/api"
click node_doc_llms "https://github.com/nazmul-nhb/chronos-date/blob/main/docs/app/llms.txt"
click node_doc_og "https://github.com/nazmul-nhb/chronos-date/blob/main/docs/app/opengraph-image.tsx"
click node_doc_components "https://github.com/nazmul-nhb/chronos-date/tree/main/docs/components"
click node_doc_lib "https://github.com/nazmul-nhb/chronos-date/tree/main/docs/lib"
click node_build_release "https://github.com/nazmul-nhb/chronos-date/blob/main/tsdown.config.ts"

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_entry,node_chronos_core,node_chronos_fn,node_utils_layer,node_plugins_layer,node_support_static,node_constants_mod,node_types_mod toneBlue
class node_doc_content,node_doc_app,node_doc_page,node_doc_layout,node_doc_api,node_doc_llms,node_doc_og,node_doc_components,node_doc_lib toneAmber
class node_root_pkg,node_build_release toneMint
```

## Components

### Library

Published Chronos date-time package and its internal runtime layers.

- [Entry](https://github.com/nazmul-nhb/chronos-date/blob/main/src/index.ts): package entry · Main public exports for the Chronos library. · `src/index.ts`
- [Chronos](https://github.com/nazmul-nhb/chronos-date/blob/main/src/core/Chronos.ts): runtime core · Immutable date-time wrapper and main orchestration API. · `src/core/Chronos.ts`
- [Wrapper fn](https://github.com/nazmul-nhb/chronos-date/blob/main/src/core/chronos-fn.ts): factory helper · Function-style convenience wrapper around the Chronos runtime. · `src/core/chronos-fn.ts`
- [Utils](https://github.com/nazmul-nhb/chronos-date/blob/main/src/utils/index.ts): shared helpers · Reusable date calculation, comparison, formatting, parsing, and helper logic. · `src/utils/index.ts`
- [Plugins](https://github.com/nazmul-nhb/chronos-date/tree/main/src/plugins): extension modules · Domain plugins that extend Chronos via registration. · `src/plugins`
- [Static support](https://github.com/nazmul-nhb/chronos-date/blob/main/src/guards.ts): guards/constants/types · Runtime guards, calendrical constants, and public TypeScript contracts. · `src/guards.ts`
- [Constants](https://github.com/nazmul-nhb/chronos-date/blob/main/src/constants/index.ts): calendar data · Reusable basic, season, and timezone constants. · `src/constants/index.ts`
- [Types](https://github.com/nazmul-nhb/chronos-date/blob/main/src/types/index.ts): public types · Chronos and plugin-related TypeScript shapes. · `src/types/index.ts`

### Docs site

Next.js documentation app, content, and interactive tooling.

- [Content tree](https://github.com/nazmul-nhb/chronos-date/tree/main/docs/content/docs): mdx docs · Structured MDX documentation source organized by feature area. · `docs/content/docs`
- [Docs app](https://github.com/nazmul-nhb/chronos-date/tree/main/docs/app): next app · App Router site that renders docs pages and special outputs. · `docs/app`
- [Doc page](https://github.com/nazmul-nhb/chronos-date/blob/main/docs/app/docs/[[...slug]]/page.tsx): route renderer · Main documentation page renderer for slugs. · `docs/app/docs/[[...slug]]/page.tsx`
- [Site shell](https://github.com/nazmul-nhb/chronos-date/blob/main/docs/app/layout.tsx): layout and styles · Global app layout and styling for the docs site. · `docs/app/layout.tsx`
- [AI/search API](https://github.com/nazmul-nhb/chronos-date/tree/main/docs/app/api): server routes · Documentation search and chat endpoints. · `docs/app/api`
- [LLM outputs](https://github.com/nazmul-nhb/chronos-date/blob/main/docs/app/llms.txt): machine-readable docs · LLMs.txt, LLMs.mdx, and full text documentation exports. · `docs/app/llms.txt`
- [Open Graph](https://github.com/nazmul-nhb/chronos-date/blob/main/docs/app/opengraph-image.tsx): preview images · Social preview image generation for docs pages. · `docs/app/opengraph-image.tsx`
- [UI components](https://github.com/nazmul-nhb/chronos-date/tree/main/docs/components): docs ui · Reusable docs widgets for markdown, tabs, copy, playgrounds, and AI surfaces. · `docs/components`
- [Docs lib](https://github.com/nazmul-nhb/chronos-date/tree/main/docs/lib): build-time helpers · Content integration, generated metadata, and shared docs utilities. · `docs/lib`

### Automation

Repository scripts and release workflows.

- [Package](https://github.com/nazmul-nhb/chronos-date/blob/main/package.json): monorepo root · Workspace and package metadata for the repository. · `package.json`
- [Build & release](https://github.com/nazmul-nhb/chronos-date/blob/main/tsdown.config.ts): tooling · TypeScript build, linting, publishing, and repository scripts. · `tsdown.config.ts`

## Connections

- Package → Entry: packages · Defines the published package surface.
- Package → Docs app: workspace · Hosts the documentation application alongside the library.
- Entry → Chronos: exports · Re-exports the main Chronos runtime.
- Entry → Wrapper fn: exports · Exposes the convenience wrapper API.
- Chronos → Utils: uses · Delegates date math, parsing, comparison, and formatting.
- Chronos → Static support: uses · Relies on guards, constants, and shared types.
- Wrapper fn → Chronos: wraps · Provides a function-style entry over the class runtime.
- Plugins → Chronos: extends · Plugins register behavior onto the core API.
- Plugins → Utils: depends on · Plugin logic reuses shared utility functions.
- Static support → Constants: includes · Static domain data used across the package.
- Static support → Types: defines · Public input and extension contracts.
- Docs app → Doc page: renders · Main docs route renders content pages.
- Docs app → Site shell: shell · Provides the site layout and global styling.
- Docs app → AI/search API: serves · Exposes search and chat endpoints.
- Docs app → LLM outputs: exports · Serves machine-readable documentation outputs.
- Docs app → Open Graph: generates · Creates social preview images.
- Doc page → Content tree: reads · Loads MDX docs by slug and section.
- Docs app → UI components: uses · Composes the interactive docs UI.
- Docs app → Docs lib: depends on · Uses generated metadata and shared docs helpers.
- Docs lib → Content tree: indexes · Transforms MDX content into navigable docs primitives.
- Docs lib → Entry: references · Docs examples and generated data point at the library API.
- Build & release → Entry: builds · TypeScript build and publish flow target the library package.
- Build & release → Docs app: maintains · Scripts support docs generation, changelog updates, and content sync.