# kotlin/kotlinx-datetime architecture

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

- Interactive diagram: https://gitdiagram.com/kotlin/kotlinx-datetime
- Repository: https://github.com/kotlin/kotlinx-datetime

## Overview

This project is a multiplatform Kotlin library dedicated to date and time handling – the kotlinx-datetime library. The core purpose of the project is to provide a minimalist and pragmatic API for representing moments in time (Instant), local date and time components, time zones, and various arithmetic operations, all while handling the complexities of platform-specific implementations.

##### Main Components
- API/Interface Layer: Represent the public API (e.g., types like Instant, LocalDateTime, LocalDate, LocalTime, Clock, TimeZone, etc.) that users of the library interact with.
- Common Core/Shared Logic: Modules under “core/common” and “core/commonJs” that contain the core business logic for parsing, formatting, arithmetic, and universal functions that perform date/time calculations.
- Platform-Specific Implementations: Separate modules for each target platform:
– JVM (core/jvm)
– JS (core/js and core/wasmJs)
– Native (core/native)
– Android Native (core/androidNative)
– Darwin (core/darwin, core/darwinDevices, core/darwinSimulator)
– Linux, Windows, and others (core/linux, core/windows)
– Additional platform-specific support such as wasmWasi.
- Time Zone Data Components: The “timezones” directory (including “timezones/full” and subdirectories with tzdb files) that manages time zone database information, and modules like core/tzdbOnFilesystem and core/tzfile which implement file-based time zone support.
- Build & Infrastructure: Directories like build.gradle.kts, buildSrc, and teamcity to manage build configurations, continuous integration settings, and scripts.
- Supporting Modules: Modules such as “serialization” that provide test cases and additional functionality (e.g., converting date/time values to strings and vice versa), and “benchmarks” for performance testing.

##### Out Relationships and Interactions
- That the TimeZone functionality interacts with both the API and common modules (with its distinction between fixed offsets and zone rules) and also depends on data loaded from the time zone (tzdb) modules.
- Separate blocks for the build system components that orchestrate the overall project assembly and testing (e.g., TeamCity, Gradle scripts).

##### Architectural Patterns and Design Principles
- Multiplatform Architecture: Clearly separate the shared logic components from platform-specific modules. Use a layered approach where the top layer is the API, the middle layer is the shared core, and the bottom layer includes platform-specific implementations.
- Separation of Concerns: Split components into clear responsibilities—common functionality, concrete platform adaptations, and external dependencies (like time zone data resources).
- Dependency Inversion: Note how the public API depends on abstract types and the shared logic which in turn delegates to specific lower-level implementations, allowing you to plug in different implementations per platform without altering the high-level API.
- Extensibility: Highlight that the structure supports additional platforms (for example, further WASM support or additional time zone providers) with minimal changes at the public API level.

## Diagram (Mermaid)

```mermaid
graph TD

  %% Public API Layer
  subgraph "Public API Layer"
    API["kotlinx-datetime API"]:::api
  end

  %% Shared Core Layer
  subgraph "Shared Core Layer"
    CORE["Common Core"]:::core
  end

  %% Platform-Specific Implementations
  subgraph "Platform-Specific Implementations"
    JVM["JVM Module"]:::platform
    JS["JS Module"]:::platform
    WASMJS["Wasm JS Module"]:::platform
    NATIVE["Native Module"]:::platform
    ANDROID_NATIVE["Android Native Module"]:::platform
    DARWIN["Darwin Module"]:::platform
    DARWIN_DEVICES["Darwin Devices Module"]:::platform
    DARWIN_SIMULATOR["Darwin Simulator Module"]:::platform
    LINUX["Linux Module"]:::platform
    WINDOWS["Windows Module"]:::platform
    WASMWASI["WasmWasi Module"]:::platform
  end

  %% Time Zone Data Components
  subgraph "Time Zone Data Components"
    TZ["Timezones Data"]:::timezone
    TZDB["TZDB Filesystem"]:::timezone
    TZFILE["TZ File Support"]:::timezone
  end

  %% Build & Infrastructure
  subgraph "Build & Infrastructure"
    BUILD_GRADLE["Gradle Script"]:::build
    BUILD_SRC["BuildSrc"]:::build
    TEAMCITY["TeamCity Configurations"]:::build
  end

  %% Supporting Modules
  subgraph "Supporting Modules"
    SERIALIZATION["Serialization Module"]:::support
    BENCHMARKS["Benchmarks Module"]:::support
  end

  %% Relationships and Interactions
  API -->|"delegates"| CORE

  %% Core layer delegates to platform-specific implementations
  CORE -->|"conversion_logic"| JVM
  CORE -->|"conversion_logic"| JS
  CORE -->|"conversion_logic"| WASMJS
  CORE -->|"conversion_logic"| NATIVE
  CORE -->|"conversion_logic"| ANDROID_NATIVE
  CORE -->|"conversion_logic"| DARWIN
  CORE -->|"conversion_logic"| DARWIN_DEVICES
  CORE -->|"conversion_logic"| DARWIN_SIMULATOR
  CORE -->|"conversion_logic"| LINUX
  CORE -->|"conversion_logic"| WINDOWS
  CORE -->|"conversion_logic"| WASMWASI

  %% Time zone data interactions with API and core
  API -->|"TZ_handling"| TZ
  CORE -->|"TZ_parsing"| TZ

  %% Time zone data sources
  TZDB -->|"provides_data"| TZ
  TZFILE -->|"provides_data"| TZ

  %% Build & Infrastructure influence
  BUILD_GRADLE -.->|"build_config"| API
  BUILD_SRC -.->|"build_support"| API
  TEAMCITY -.->|"CI_config"| API

  %% Supporting Modules influence
  SERIALIZATION -.->|"test_serialization"| API
  BENCHMARKS -.->|"performance_tests"| API

  %% Styles
  classDef api fill:#f9c74f,stroke:#333,stroke-width:2px;
  classDef core fill:#90be6d,stroke:#333,stroke-width:2px;
  classDef platform fill:#f94144,stroke:#333,stroke-width:2px;
  classDef timezone fill:#4361ee,stroke:#333,stroke-width:2px;
  classDef build fill:#577590,stroke:#333,stroke-width:2px;
  classDef support fill:#277da1,stroke:#333,stroke-width:2px;

click API "https://github.com/kotlin/kotlinx-datetime/blob/master/core/api/kotlinx-datetime.api"
click CORE "https://github.com/kotlin/kotlinx-datetime/tree/master/core/common"
click JVM "https://github.com/kotlin/kotlinx-datetime/tree/master/core/jvm"
click JS "https://github.com/kotlin/kotlinx-datetime/tree/master/core/js"
click WASMJS "https://github.com/kotlin/kotlinx-datetime/tree/master/core/wasmJs"
click NATIVE "https://github.com/kotlin/kotlinx-datetime/tree/master/core/native"
click ANDROID_NATIVE "https://github.com/kotlin/kotlinx-datetime/tree/master/core/androidNative"
click DARWIN "https://github.com/kotlin/kotlinx-datetime/tree/master/core/darwin"
click DARWIN_DEVICES "https://github.com/kotlin/kotlinx-datetime/tree/master/core/darwinDevices"
click DARWIN_SIMULATOR "https://github.com/kotlin/kotlinx-datetime/tree/master/core/darwinSimulator"
click LINUX "https://github.com/kotlin/kotlinx-datetime/tree/master/core/linux"
click WINDOWS "https://github.com/kotlin/kotlinx-datetime/tree/master/core/windows"
click WASMWASI "https://github.com/kotlin/kotlinx-datetime/tree/master/core/wasmWasi"
click TZ "https://github.com/kotlin/kotlinx-datetime/tree/master/timezones"
click TZDB "https://github.com/kotlin/kotlinx-datetime/tree/master/core/tzdbOnFilesystem"
click TZFILE "https://github.com/kotlin/kotlinx-datetime/tree/master/core/tzfile"
click BUILD_GRADLE "https://github.com/kotlin/kotlinx-datetime/blob/master/build.gradle.kts"
click BUILD_SRC "https://github.com/kotlin/kotlinx-datetime/tree/master/buildSrc"
click TEAMCITY "https://github.com/kotlin/kotlinx-datetime/blob/master/.teamcity"
click SERIALIZATION "https://github.com/kotlin/kotlinx-datetime/tree/master/serialization"
click BENCHMARKS "https://github.com/kotlin/kotlinx-datetime/tree/master/benchmarks"
```
