# melleb/tinyduration architecture

> Architecture diagram of the GitHub repository melleb/tinyduration, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/melleb/tinyduration
- Repository: https://github.com/melleb/tinyduration

## Overview

##### Project type and purpose
- This is a lightweight TypeScript-based JavaScript library (an NPM package) called “TinyDuration.”
- Its sole responsibility is to parse ISO-8601 duration strings into a plain object and serialize such objects back into ISO-8601 strings.
- It ships to the NPM registry (< 1 KB minified+gzipped) and has zero runtime dependencies.

##### File structure
- Top-level: configuration for ESLint, Prettier, GitHub Actions CI, Changesets (for versioning), TypeScript, Jest tests, and .gitignore/.npmignore.
- src/index.ts: the single entry point exporting `parse()` and `serialize()`.
- src/index.test.ts: Jest tests covering both functions.
- dist (generated at publish time): transpiled JavaScript artifacts for distribution.

##### README for additional insights
- Confirms that this is a library (no server, database, or UI).
- Describes development workflow: `npm test`, `npm run lint`, `npm run prettify`, CI via GitHub Actions, Changesets for version bumps, `npx changeset publish`.

a. Main Components
- Developer workstation (TypeScript source + tests + config)
- Build & Test pipeline (TypeScript compiler → Jest tests → lint/format checks)
- CI/CD server (GitHub Actions)
- NPM Registry (artifact storage)
- Consumer application (any JS/TS project that installs tinyduration)

b. Relationships & Data Flow
1. Developer writes/edits `src/index.ts` & `src/index.test.ts`.
2. Local build: `tsc` compiles to `dist/`, `jest` runs tests, `eslint`/`prettier` validate style.
3. Push to GitHub: triggers CI workflow (runs the same build/test/lint steps).
4. When a Changeset version is merged and CI passes, the package is published to NPM.
5. Consumer apps install via `npm install tinyduration` and invoke `parse()`/`serialize()` at runtime.

c. Architectural patterns/design principles
- Single-responsibility: only two exported functions.
- Pure functions with no side effects.
- Zero runtime dependencies for minimal bundle size.
- Test-driven, with 100% coverage enforced by CI.
- Automated semantic versioning & changelog via Changesets.

d. Key technologies/frameworks
- TypeScript (source) → JavaScript (dist)
- Jest (unit testing)
- ESLint + Prettier (code quality)
- GitHub Actions (CI)
- Changesets (versioning & changelog)
- NPM (package distribution)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    Developer["Developer Workstation"]:::consumer

    %% Source Repository
    subgraph "Source Repository"
        TS["TypeScript Source Module"]:::code
        Tests["Test Suite"]:::code
        ESLint["ESLint Configuration"]:::code
        Prettier["Prettier Configuration"]:::code
        TSConfig["TypeScript Configuration"]:::code
        PackageCfg["package.json (Metadata & Jest Config)"]:::code
        NpmIgnore[".npmignore"]:::code
        License["LICENSE.md"]:::code
        Readme["README.md"]:::code
        ChangesetCFG["Changesets Config"]:::code
        ChangesetReadme["Changesets README"]:::code
        Changelog["CHANGELOG.md"]:::code
    end

    %% Local Dev Workflow
    subgraph "Local Dev Workflow"
        Build["TypeScript Compilation"]:::pipeline
        TestRunner["Jest Test Runner"]:::pipeline
        Lint["ESLint Linting"]:::pipeline
        Format["Prettier Formatting"]:::pipeline
        Dist["Compiled Artifacts (dist/)"]:::code
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        CI["GitHub Actions CI"]:::pipeline
        Publish["Changesets Publish"]:::pipeline
    end

    %% External Services
    npmReg["NPM Registry"]:::external
    Consumer["Consumer Application"]:::consumer

    %% Relationships
    Developer -->|"edits code"| TS
    Developer --> Tests

    TS --> Build
    TSConfig --> Build
    Build --> Dist

    TS --> TestRunner
    Tests --> TestRunner
    PackageCfg --> TestRunner

    ESLint --> Lint
    Prettier --> Format

    Developer -->|"runs local workflow"| Build
    Developer --> TestRunner
    Developer --> Lint
    Developer --> Format

    %% CI triggers
    Developer -->|"git push"| CI
    CI --> Build
    CI --> TestRunner
    CI --> Lint
    CI --> Format
    CI --> Publish

    Publish --> npmReg
    npmReg -->|"npm install tinyduration"| Consumer
    Consumer -->|"invokes parse()/serialize() at runtime"| Dist

    %% Click Events
    click TS "https://github.com/melleb/tinyduration/blob/main/src/index.ts"
    click Tests "https://github.com/melleb/tinyduration/blob/main/src/index.test.ts"
    click ESLint "https://github.com/melleb/tinyduration/blob/main/.eslintrc.js"
    click Prettier "https://github.com/melleb/tinyduration/blob/main/.prettierrc.js"
    click TSConfig "https://github.com/melleb/tinyduration/blob/main/tsconfig.json"
    click PackageCfg "https://github.com/melleb/tinyduration/blob/main/package.json"
    click NpmIgnore "https://github.com/melleb/tinyduration/blob/main/.npmignore"
    click License "https://github.com/melleb/tinyduration/blob/main/LICENSE.md"
    click Readme "https://github.com/melleb/tinyduration/blob/main/README.md"
    click ChangesetCFG "https://github.com/melleb/tinyduration/blob/main/.changeset/config.json"
    click ChangesetReadme "https://github.com/melleb/tinyduration/blob/main/.changeset/README.md"
    click Changelog "https://github.com/melleb/tinyduration/blob/main/CHANGELOG.md"
    click CI "https://github.com/melleb/tinyduration/blob/main/.github/workflows/ci.yml"

    %% Styles
    classDef code fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef pipeline fill:#E6FFDD,stroke:#2E7D32,color:#2E7D32
    classDef external fill:#FFE0B2,stroke:#F57C00,color:#E65100
    classDef consumer fill:#E0E0E0,stroke:#616161,color:#424242
```
