# paulstoffregen/time architecture

> Architecture diagram of the GitHub repository paulstoffregen/time, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paulstoffregen/time
- Repository: https://github.com/paulstoffregen/time
- Video tour (about a minute): https://gitdiagram.com/paulstoffregen/time/video

## Overview

Arduino Time is a compact timekeeping library: a sketch reads or sets Unix-style time through the public API, while the runtime advances its clock and can periodically synchronize through a callback. The core also converts between timestamps and calendar fields and provides date-name strings. README-documented RTC, NTP, GPS, and serial examples demonstrate interchangeable time sources; their implementation details were not sampled, so those connections are shown as documented rather than source-verified.

Main entry points: [`TimeLib.h`](https://github.com/paulstoffregen/time/blob/master/TimeLib.h) (Time API), [`Time.cpp`](https://github.com/paulstoffregen/time/blob/master/Time.cpp) (Clock and conversions), [`examples/TimeRTC/TimeRTC.ino`](https://github.com/paulstoffregen/time/blob/master/examples/TimeRTC/TimeRTC.ino) (RTC example), [`examples/TimeNTP/TimeNTP.ino`](https://github.com/paulstoffregen/time/blob/master/examples/TimeNTP/TimeNTP.ino) (NTP example)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Time library"]
  node_api["Time API<br/>[TimeLib.h]"]
  node_clock["Clock and conversions<br/>[Time.cpp]"]
  node_date_strings["Date strings<br/>[DateStrings.cpp]"]
end

subgraph group_sources["Time-source examples"]
  node_rtc["RTC example<br/>[TimeRTC.ino]"]
  node_ntp["NTP example<br/>[TimeNTP.ino]"]
  node_gps["GPS example<br/>[TimeGPS.ino]"]
  node_serial["Serial example<br/>[TimeSerial.ino]"]
end

node_sketch(("Arduino sketch"))
node_external_sources(("External time sources"))

node_sketch -->|"uses"| node_api
node_api -->|"exposes"| node_clock
node_api -->|"exposes"| node_date_strings
node_clock -->|"reads clock ticks"| node_clock
node_clock -->|"calls sync provider"| node_external_sources
node_rtc -.->|"synchronizes through"| node_api
node_ntp -.->|"synchronizes through"| node_api
node_gps -.->|"synchronizes through"| node_api
node_serial -.->|"synchronizes through"| node_api
node_external_sources -.->|"includes RTC"| node_rtc
node_external_sources -.->|"includes NTP"| node_ntp
node_external_sources -.->|"includes GPS"| node_gps
node_external_sources -.->|"includes serial"| node_serial

click node_api "https://github.com/paulstoffregen/time/blob/master/TimeLib.h"
click node_clock "https://github.com/paulstoffregen/time/blob/master/Time.cpp"
click node_date_strings "https://github.com/paulstoffregen/time/blob/master/DateStrings.cpp"
click node_rtc "https://github.com/paulstoffregen/time/blob/master/examples/TimeRTC/TimeRTC.ino"
click node_ntp "https://github.com/paulstoffregen/time/blob/master/examples/TimeNTP/TimeNTP.ino"
click node_gps "https://github.com/paulstoffregen/time/blob/master/examples/TimeGPS/TimeGPS.ino"
click node_serial "https://github.com/paulstoffregen/time/blob/master/examples/TimeSerial/TimeSerial.ino"

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_api,node_clock,node_date_strings toneBlue
class node_rtc,node_ntp,node_gps,node_serial toneAmber
class node_sketch,node_external_sources toneIndigo
```

## Components

### Time library

- [Time API](https://github.com/paulstoffregen/time/blob/master/TimeLib.h): `TimeLib.h`
- [Clock and conversions](https://github.com/paulstoffregen/time/blob/master/Time.cpp): `Time.cpp`
- [Date strings](https://github.com/paulstoffregen/time/blob/master/DateStrings.cpp): `DateStrings.cpp`

### Time-source examples

- [RTC example](https://github.com/paulstoffregen/time/blob/master/examples/TimeRTC/TimeRTC.ino): `examples/TimeRTC/TimeRTC.ino`
- [NTP example](https://github.com/paulstoffregen/time/blob/master/examples/TimeNTP/TimeNTP.ino): `examples/TimeNTP/TimeNTP.ino`
- [GPS example](https://github.com/paulstoffregen/time/blob/master/examples/TimeGPS/TimeGPS.ino): `examples/TimeGPS/TimeGPS.ino`
- [Serial example](https://github.com/paulstoffregen/time/blob/master/examples/TimeSerial/TimeSerial.ino): `examples/TimeSerial/TimeSerial.ino`

### Other components

- **Arduino sketch**
- **External time sources**

## Connections

- Arduino sketch → Time API: uses (evidence: `Readme.md`)
- Time API → Clock and conversions: exposes (evidence: `Time.cpp`)
- Time API → Date strings: exposes (evidence: `DateStrings.cpp`)
- Clock and conversions → Clock and conversions: reads clock ticks (evidence: `Time.cpp`)
- Clock and conversions → External time sources: calls sync provider (evidence: `Time.cpp`)
- RTC example → Time API: synchronizes through (evidence: `Readme.md`)
- NTP example → Time API: synchronizes through (evidence: `Readme.md`)
- GPS example → Time API: synchronizes through (evidence: `Readme.md`)
- Serial example → Time API: synchronizes through (evidence: `Readme.md`)
- External time sources → RTC example: includes RTC (evidence: `Readme.md`)
- External time sources → NTP example: includes NTP (evidence: `Readme.md`)
- External time sources → GPS example: includes GPS (evidence: `Readme.md`)
- External time sources → Serial example: includes serial (evidence: `Readme.md`)
