# tsevdos/elutils architecture

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

- Interactive diagram: https://gitdiagram.com/tsevdos/elutils
- Repository: https://github.com/tsevdos/elutils

## Overview

##### Main Components
- Public API and Entry Point: Represent the main file (src/index.ts) that re-exports all the utility modules.
- geoUtils: Functions related to geographic data and location operations. This module depends on static JSON data (administrative regions, cities, postal codes, etc.) found in the data folder.
- validationUtils: Functions meant for validating data such as postal codes, VAT numbers, phone numbers, etc.
- dateUtils: Contains date-related functionality (getting days, months, quarters, eras, and holidays).
- formatUtils: Offers formatting functions (e.g., formatting weights).
- languageUtils: Deals with Greek text transformations and comparisons.
- Data Store: A dedicated component that represents the JSON data files in the data directory. This component is used primarily by geoUtils to consult static data.
- Testing: A clear “Test Suite” component representing the __tests__ directory, which runs various Jest tests to ensure the utility functions behave as expected.
- Build Tools: Files like tsconfig.json and tsup.config.ts indicating TypeScript compilation and bundling.

##### Relationships and Interactions
- From each module, you could also indicate dependency to helper modules (if any) and documentation. Additionally, mark the testing suite as running tests specifically on each module.
- The build and CI/CD components are shown separately and linked to the entire codebase; they “watch over” code quality and automated deployment.

##### Architectural Patterns and Design Principles
- Modular Design: The clear separation into discrete modules enhances maintainability and testability.
- Single Responsibility Principle: Each module is dedicated to a specific kind of utility (geographic, date, validating, formatting, and language processing).
- Zero-dependency and Strong Typing: Emphasize that the library is self-contained with no external dependencies and that TypeScript’s type-checking is central to its design.
- Test-Driven Development Support: Presence of tests for each module indicates an emphasis on reliability.

##### Relevant Technologies
- TypeScript – for strongly-typed code.
- Jest – for running unit tests (see jest.config.cjs and test folder).
- tsup – used for bundling/build configuration (see tsup.config.ts).
- GitHub Actions – automated CI/CD (workflows for testing and publishing).
- Static JSON Data Files – store geographic and related data which are consumed by certain utility functions.
- ESLint and Prettier – code style and formatting tools.

## Diagram (Mermaid)

```mermaid
graph TD
  LC["Library Consumer"]:::consumer
  API["Public API (src/index.ts)"]:::api
  
  subgraph "Utility Modules"
    GEO["geoUtils (src/geoUtils.ts)"]:::module
    VAL["validationUtils (src/validationUtils.ts)"]:::module
    DATE["dateUtils (src/dateUtils.ts)"]:::module
    FORMAT["formatUtils (src/formatUtils.ts)"]:::module
    LANG["languageUtils (src/languageUtils.ts)"]:::module
  end
  
  DATA["Data Store (Static JSON)"]:::data
  DOCS["Documentation (docs/)"]:::docs
  TEST["Testing Suite (Jest, src/__tests__/)"]:::test
  BUILD["Build Tools (tsconfig.json, tsup.config.ts)"]:::build
  CICD["CI/CD Pipelines (.github/workflows)"]:::cicd

  LC -->|"calls"| API
  API -->|"exposes"| GEO
  API -->|"exposes"| VAL
  API -->|"exposes"| DATE
  API -->|"exposes"| FORMAT
  API -->|"exposes"| LANG

  GEO -->|"uses"| DATA

  GEO -->|"docs"| DOCS
  VAL -->|"docs"| DOCS
  DATE -->|"docs"| DOCS
  FORMAT -->|"docs"| DOCS
  LANG -->|"docs"| DOCS

  TEST -->|"tests"| GEO
  TEST -->|"tests"| VAL
  TEST -->|"tests"| DATE
  TEST -->|"tests"| FORMAT
  TEST -->|"tests"| LANG

  BUILD -->|"builds"| API
  BUILD -->|"builds"| GEO
  BUILD -->|"builds"| VAL
  BUILD -->|"builds"| DATE
  BUILD -->|"builds"| FORMAT
  BUILD -->|"builds"| LANG

  CICD -->|"triggers"| BUILD
  CICD -->|"triggers"| TEST

  classDef consumer fill:#B3E5FC,stroke:#333,stroke-width:2px;
  classDef api fill:#FFEEAA,stroke:#333,stroke-width:2px;
  classDef module fill:#CCFFCC,stroke:#333,stroke-width:2px;
  classDef data fill:#CCE5FF,stroke:#333,stroke-width:2px;
  classDef docs fill:#D5E8D4,stroke:#333,stroke-width:2px;
  classDef test fill:#FFF2CC,stroke:#333,stroke-width:2px;
  classDef build fill:#F8CECC,stroke:#333,stroke-width:2px;
  classDef cicd fill:#E1D5E7,stroke:#333,stroke-width:2px;

  click API "https://github.com/tsevdos/elutils/blob/main/src/index.ts"
  click GEO "https://github.com/tsevdos/elutils/blob/main/src/geoUtils.ts"
  click VAL "https://github.com/tsevdos/elutils/blob/main/src/validationUtils.ts"
  click DATE "https://github.com/tsevdos/elutils/blob/main/src/dateUtils.ts"
  click FORMAT "https://github.com/tsevdos/elutils/blob/main/src/formatUtils.ts"
  click LANG "https://github.com/tsevdos/elutils/blob/main/src/languageUtils.ts"
  click DATA "https://github.com/tsevdos/elutils/tree/main/data/"
  click DOCS "https://github.com/tsevdos/elutils/tree/main/docs/"
  click TEST "https://github.com/tsevdos/elutils/tree/main/src/__tests__/"
  click BUILD "https://github.com/tsevdos/elutils/blob/main/tsconfig.json"
  click CICD "https://github.com/tsevdos/elutils/blob/main/.github/workflows/ci.yml"
```
