How ChronoShield is built

ChronoShield is a piece of infrastructure you're being asked to call from your scheduling, billing, or agent code. That's a trust ask. This page explains exactly how it works under the hood — the architecture choices, the correctness guarantees, the deployment story — so you can evaluate it the way you'd evaluate any production dependency.

Tech stack

Bundled IANA tzdata, decoupled from system ICU

Most Node servers' "time math" depends on the host OS's ICU library, which is updated whenever the OS is updated — sometimes never. That means two identical-looking deploys can give different DST answers depending on which Linux base image they happened to land on.

ChronoShield ships its own bundled IANA-zone implementation based on moment-timezone's tzdata, wrapped in a custom BundledIANAZone class that conforms to Luxon's Zone interface. The whole zone database travels with the npm package; ICU is never consulted.

Why it matters: a customer running ChronoShield self-hosted on Alpine Linux gets the same answers as our Railway-hosted deploy on Debian. No surprise on a base-image bump. No "works on staging, broken in prod."

Parity sweep against Luxon's IANAZone

The bundled implementation is correct only if it produces the same answers as a known-good reference. Every CI run sweeps offsets for every zone moment-timezone knows about (~600+) at six representative timestamps and asserts byte-equality with Luxon's IANAZone.

• Timestamps include 2026 NY spring-forward and fall-back windows, mid-summer 1985, end-of-2000, and 2035 (parity envelope).
• ~3,500+ comparisons per CI run.
• Any divergence fails the build and prints the exact zone, instant, and the two offsets that disagreed.
• A separate fuzz suite seeds random zone × timestamp pairs around DST transitions specifically — the moments where bundled and reference are most likely to drift on a tzdb update.

Browse the test suite at github.com/Mike-Mait/ChronoShield-API/tree/master/tests; the parity-relevant files are bundled-zone-parity.test.ts and bundled-zone-fuzz.test.ts. Or see the curated edge-case list at /correctness.

Monthly tzdb refresh cadence

The IANA tzdb releases roughly monthly, sometimes more often when a country changes its DST policy on short notice (Iran, Turkey, Egypt, Brazil have all done this in recent years). ChronoShield tracks that release schedule via a scheduled GitHub Action that checks for new tzdb versions, opens a PR with the updated bundle, and runs the full parity + fuzz suite before merge.

The currently-served version is always exposed at /v1/datetime/version:

GET /v1/datetime/version
→ {
    "tzdb_version": "2026b",
    "tzdb_source": "moment-timezone",
    "tzdb_source_version": "0.6.2",
    "api_version": "1.3.0"
  }

Compare this to pytz, which has historically lagged tzdb releases by months. Or to a Lambda function whose tzdata is pinned to whatever ICU shipped with the runtime when AWS last published the layer. ChronoShield's cadence is a deliberate choice to remove that drift from your concern set.

BC DST projection — far past, far future

tzdb has a "rule envelope" — a range of years for which DST transitions are explicitly listed. Outside the envelope, libraries either error or extrapolate by repeating the most recent rule. The behavior is undefined enough that two libraries can disagree on whether "1900-06-15 noon in America/New_York" was in DST.

ChronoShield uses a documented projection strategy (the same one Luxon uses by default) and tests against it explicitly. If you call validate or convert with a year outside the parity envelope, you get the same answer ChronoShield's bundled implementation and Luxon agree on — no silent reinterpretation.

Performance: pure computation in the request path

Validate, resolve, and convert are pure functions: no database lookups, no filesystem reads, no external API calls in the hot path. The bundled tzdata is loaded once at server start and served from memory.

• p95 latency: <50ms (server-side compute, excluding network).
• API key + usage counter writes happen on the response path, not the request path — so a slow DB doesn't block the answer.
• Rate limit check is an in-memory comparison using a key entry that's hydrated from Postgres on first lookup and cached.

Deployment topology

Production runs on Railway with PostgreSQL for key/usage persistence. Live status: chronoshield-api.betteruptime.com.

Boot-time schema verification: the server runs prisma migrate deploy + a probe query against the api_keys table on startup. If the DB schema is missing, the process crashes with a loud error rather than coming up in a half-broken state and silently issuing memory-only keys that vanish on restart.

Health check: Docker/Railway use /health; richer operational state at /status.

Self-hosting

For air-gapped, regulatory, or data-residency reasons, the entire stack runs from a Docker Compose file in the public repo. Postgres + Redis + the API itself, with healthchecks wired up.

git clone https://github.com/Mike-Mait/ChronoShield-API
cd ChronoShield-API
cp .env.example .env  # set master API_KEY etc.
docker compose up

Same code that runs at chronoshieldapi.com. No proprietary fork. Self-hosted deployments still receive the monthly tzdb refresh via the open-source release cadence on GitHub.