Standardizing Date Handling Across Service Boundaries

Context

As the reporting platform evolved, date handling became fragmented across multiple services and frontends. Different endpoints accepted different formats—some expected YYYYMMDD, others expected YYYY-MM-DD. The frontend parsed dates differently depending on context, sometimes treating them as UTC, sometimes as local time.

This fragmentation wasn't the result of carelessness. Each service had made reasonable decisions in isolation. But as the system grew, these inconsistencies accumulated, creating subtle bugs that were expensive to diagnose and fix.

The Problem

Date handling inconsistencies manifested as production bugs and ambiguity in data contracts across the platform.

Timezone-related issues caused reports to return unexpected data when filtering by specific dates. Format mismatches between frontend and backend meant that dates stored correctly in the database could be parsed incorrectly on retrieval. New services couldn't confidently consume date values without defensive transformation logic.

Each bug felt isolated until we realized it wasn't: the problem was systemic. Without a shared standard, every team working with dates would reinvent their own handling logic, guaranteeing continued inconsistency and risk.

The Decision

Rather than treating each date bug as an isolated defect, we chose to establish ISO 8601 (YYYY-MM-DD format) as the standard across all services and frontends.

This decision required coordination across multiple teams: frontend (ui-web), reporting GraphQL services, and the backend API layer. It meant updating contracts that had been stable for years, and ensuring backward compatibility during transition.

The goal wasn't just consistency—it was clarity. By making the format explicit and standard, we reduced ambiguity about how dates should be parsed, stored, and transported.

Execution

Standardization required work at multiple layers:

API Contracts: Updated all date-accepting endpoints across reporting-gql and toolbox-gql to consistently accept and return ISO 8601 format. This included itemSalesReport, groupItemSalesReport, getRestaurantDetails, and other high-traffic endpoints.

GraphQL Validation: Introduced a strict ISO 8601 date scalar in the GraphQL layer to enforce validation at the API boundary rather than relying on downstream services to validate.

Frontend Utilities: Built frontend utilities for parsing dates as local dates (to avoid timezone shifts) and formatting consistently for API communication. Added backward compatibility handling for legacy compact date formats during transition.

Documentation: Created an Architecture Decision Record (ADR) that formalized the standard, documented rationale, and provided guidance for future date handling work across the platform.

This layered approach allowed services to adopt the standard incrementally while maintaining stability throughout the transition.

Impact

Date-related bugs decreased defensive transformation. Reporting accuracy improved when filtering by specific dates. The frontend and backend no longer maintained conflicting assumptions about date format or timezone handling.

Most importantly, the standard became a shared language. Teams could discuss date handling with precision, and future work in the space didn't require re-solving the same ambiguities.

The ISO 8601 standard is now enforced at multiple layers—GraphQL validation, API contracts, and documentation—reducing the likelihood of drift and ensuring consistency as the platform continues to evolve.

Reflection

Systemic problems rarely announce themselves as such. They look like isolated bugs, scattered across different services, each with reasonable local explanations.

The key was recognizing the pattern: not "the date parser is broken," but "we have no shared standard for date handling." Once that was clear, the solution followed naturally.

This work reinforces that some of the highest-impact efforts aren't about building new features—they're about establishing clarity and consistency across system boundaries. Standards that feel invisible when they work are the most valuable.