Forem: bwi

The Role of a Software Architect – And Why It Often Can't Be Fulfilled

bwi — Tue, 24 Feb 2026 16:48:16 +0000

In many organizations, the title "Software Architect" exists. It is often used to signal technical maturity — both internally and externally. But maturity doesn't come from naming. It comes from the organizational anchoring of the function.

Architecture is a design function. It requires context, influence, time, and a clear mandate. If any of these is missing, architecture doesn't emerge — instead, what emerges is the sum of local decisions that no one holds together.

The question is therefore not: "Do we have an architect?"
But rather: "Do we have the conditions for architecture to actually happen?"

Architecture rarely fails due to a lack of competence.
It fails due to a lack of organizational honesty.

Architecture Is Not Implementation with More Experience

A common misconception is the assumption that a software architect is simply a particularly experienced developer — a "Senior Developer Plus."

Of course, an architect needs technical experience. A great deal of it, in fact.
But their primary task is not writing code.

Ralph Johnson put it succinctly in a widely cited discussion, later referenced by Martin Fowler in his essay "Who Needs an Architect?": "Architecture is the decisions that you wish you could get right early in a project." Why? Because they are hard to change later.

The architect's task, then, is to make exactly these decisions — decisions that make the code possible and sustainable in the first place:

How should the system evolve over the years?
What structure allows growth without exponential complexity?
Which decisions are reversible — and which are not?
Where do future risks arise (scaling, security, operations, compliance)?
What dependencies are we building right now — and what long-term costs do they create?

These are not implementation questions.
These are questions of structure, direction, and sustainability.

Mark Richards and Neal Ford articulated the first law of software architecture: "Everything in software architecture is a trade-off." And the corollary: "If you think you've found something that isn't a trade-off, you probably just haven't identified the trade-off yet."

A senior developer optimizes the solution.
A software architect shapes the solution space.

The difference lies not in the ability to implement, but in the focus of responsibility.

The Structural Tension: Responsibility Here, Decisions Everywhere

If architecture concerns this type of decision, the real question is not competence — but whether the organization actually enables these decisions to be made.

Architecture requires that someone can see and understand the big picture. Not in the sense of control, but in the sense of overview: What capabilities already exist? What initiatives are running in parallel? What integrations, data flows, and operational assumptions are in play?

In many organizations, responsibilities appear to be neatly divided: Business decides the what, engineering managers organize the teams, tech leads own day-to-day delivery — and the architect takes care of "the structure."

Sounds tidy. Often doesn't work.

Because architecture is not an isolated responsibility. It is the result of decisions being made everywhere:

When the business decides to expand into new markets, that has architectural consequences.
When the team structure changes, it affects whether microservices make sense or a monolith is the better choice.
When one team introduces a new programming language, another picks a new framework, and a third builds its own deployment pipeline — that creates exactly the island landscape that architecture is supposed to prevent.
How an application is deployed is an architectural decision. Team boundaries, system boundaries, repository structure, and deployment capabilities are tightly coupled — often as a cycle that extends into SLAs, availability, and compliance.

Conway articulated this as early as 1968: "Organizations which design systems are constrained to produce designs which are copies of the communication structures of these organizations." And Ruth Malan stated the consequence: "If the architecture of the system and the architecture of the organization are at odds, the architecture of the organization wins."

This creates a structural tension: The responsibility for long-term system evolution lies with architecture. The decision-shaping factors, however, are distributed across the organization. The expectation that "the architect will take care of it" exists — even when they weren't involved. And the mandate to participate in the relevant decisions is missing or unclear.

When these things don't align, a fatal situation arises: Architecture is expected but cannot be actively shaped. It reacts to decisions that have already been made, instead of co-shaping them in advance.

This is not a competence problem. It is an organizational-structural pattern.

That is why a software architect must at least be involved in all these areas — not to decide the "whether," but to raise "what does this mean for the system?" in time. Everything that extends beyond a single team should be architecturally visible. Not as an approval process. Not as bureaucracy. But because someone needs to maintain the overview.

Depending on team size and complexity, architecture can be practiced as a centralized, distributed, or rotating role. The title doesn't matter. What matters is that the function exists and is organizationally anchored.

When this doesn't happen, you don't see it immediately in the code — but in patterns: Locally sensible solutions emerge that don't fit together globally. Similar things are built multiple times because no one knows they already exist. Every solution brings its own terminology, data models, and interfaces. Integration and operations become more expensive with every island.

From the outside, this can look as if architecture is "unnecessary." Not because architecture has no value, but because the organization doesn't use it as a connecting function. Then architecture remains a collection of individual decisions that don't arise from a shared vision, but from accidental sequencing and local pressure.

This is not a criticism of individual developers — it is an observation about organizational mechanics.

A Practical Example

A system manages campaigns with start and end dates. In the beginning, a simple DateTime field suffices. The assumption: All users are in the same time zone, deadlines mean "end of the day," and nobody asks which day exactly is meant.

This works — as long as the assumption holds.

Then international customers arrive. A user in New York enters "June 5th" as a deadline. A user in Vienna sees the same date — but whose midnight applies? The system doesn't know, because the DateTime type doesn't carry this information. It stores a number without context.

Each team solves the problem locally:

The backend team silently converts everything to UTC — but loses the information about which time zone the user intended.
The frontend team displays dates in the browser's time zone — which may differ from the server's.
A third team builds a reporting export that outputs the database values directly — in UTC, without conversion.

No team made a mistake. Every decision was locally reasonable. But the system now displays three different times for the same event — depending on where you look.

The real problem lies deeper: "What is a date in our system?" was never asked as a question. Is it a point on the timeline? A calendar day in the user's sense? A deadline that requires a time zone? A recurring event governed by local rules? These are fundamentally different concepts — but the data model treats them all the same: as a single column of type timestamp.

Technically, all of this is solvable. But no longer easily. The data model must be split. Existing data must be migrated — without knowing which time zone was intended at the time of entry. Every interface, every report, every display must be reviewed.

The feature wasn't complex. The missing architectural embedding was. A single early decision — "What types of time exist in our system, and how do we model them?" — would have prevented the entire downstream effort.

And this is precisely where it becomes clear: Architecture without context can only manage islands — but cannot shape systems.

Architecture Needs Focus and Feedback

Architectural work doesn't happen in the context switch between two bug fixes. It emerges through analysis, modeling, evaluating alternatives, mentally playing through scenarios, and making deliberate decisions under uncertainty.

Typical components include:

Documenting decisions (e.g., ADRs)
Evaluating trade-offs
Defining guardrails
Evolution paths and refactoring strategies
Risk analysis
Dependency and integration maps
Communication and alignment across teams

When 90% of working time is reserved for feature implementation, there is effectively no room for any of this. Then architecture isn't shaped — it emerges as a byproduct. Then a DateTime field becomes a system-wide problem — not because the question was hard, but because nobody had the time to ask it. And that is one of the most expensive states a software system can be in.

At the same time, architecture also fails at the other extreme: when architects work far removed from day-to-day development. They define guidelines and design target states — without truly knowing the practical constraints of implementation. The result is "ivory tower architecture."

Good architecture therefore needs both:

Strategic distance, to think long-term.
Practical proximity, to stay realistic.

An architect doesn't code because features need to be delivered.
They code because architecture must be real — to validate assumptions, make risks visible, and test structures.

If either is missing, architecture becomes either reactive — or detached from reality.

One might argue that reactive architecture can be intentional. Modern architectural approaches deliberately follow the principle of deferring decisions as long as possible — until more information is available.

The difference lies not in the timing, but in the reason:

Strategy: We could decide earlier but intentionally choose to decide later. Example: We leave the storage technology open but define clear interfaces and performance checks until load profiles are measurable.
Constraint: We have to react now because we previously lacked information, influence, or time. Example: We pick "some" technology under time pressure, without load assumptions, without guardrails, without an exit path.

Both look "reactive" from the outside. But they are fundamentally different.

How to Recognize That Architecture Doesn't Truly Exist

Not as a title. But as a lived function.

Are structural decisions consciously documented — or just implemented?
Is there explicit time for architectural work — or does it happen "when there's a gap"?
Are architects involved in strategic product decisions?
Are major changes made visible across teams before implementation?
Is there transparency about which capabilities and modules already exist?
Are technical guardrails actively defined — or do they emerge implicitly?
Are there planned evolution paths — or only refactoring when needed?
Are long-term risks actively discussed — or only visible when they occur?

If most answers are "no," architecture probably doesn't exist as a shaping function.

And emergence is no substitute for responsibility.

Conclusion

A software architect is not simply a senior developer with a different title.
They are responsible for the structure, direction, and future viability of a system.

For this, they need context, influence, time, and a mandate. If any of these is missing, they cannot fulfill their role — no matter how competent they are.

That is why every organization that uses the title "Software Architect" should ask itself a simple question:

Do we truly want to shape architecture?
Or do we just want to pretend it exists?

Die Aufgabe eines Softwarearchitekten – und warum sie oft nicht stattfinden kann

bwi — Tue, 24 Feb 2026 16:48:14 +0000

Die Aufgabe eines Softwarearchitekten – und warum sie oft nicht stattfinden kann

In vielen Unternehmen gibt es den Titel „Softwarearchitekt". Oft wird er verwendet, um technische Reife zu signalisieren — intern wie extern. Doch Reife entsteht nicht durch Benennung. Sie entsteht durch die organisatorische Verankerung der Funktion.

Architektur ist eine Gestaltungsfunktion. Sie braucht Kontext, Einfluss, Zeit und ein klares Mandat. Fehlt eines davon, entsteht keine Architektur — sondern die Summe lokaler Entscheidungen, die niemand zusammenhält.

Die Frage ist deshalb nicht: „Haben wir einen Architekten?"
Sondern: „Haben wir die Voraussetzungen, damit Architektur stattfinden kann?"

Architektur scheitert selten an fehlender Kompetenz.
Sie scheitert an fehlender organisationaler Ehrlichkeit.

Architektur ist keine Implementierung mit mehr Erfahrung

Ein häufiger Irrtum ist die Annahme, ein Softwarearchitekt sei einfach ein besonders erfahrener Entwickler — ein „Senior Developer Plus".

Natürlich braucht ein Architekt technische Erfahrung. Viel sogar.
Aber seine primäre Aufgabe ist nicht das Schreiben von Code.

Ralph Johnson brachte es in einer vielzitierten Diskussion auf den Punkt, die Martin Fowler später in seinem Essay „Who Needs an Architect?" aufgriff: Architektur sind die Entscheidungen, die man gerne früh im Projekt richtig treffen würde — weil sie später schwer zu ändern sind.

Die Aufgabe eines Architekten ist es also, genau diese Entscheidungen zu treffen — Entscheidungen, die den Code überhaupt erst möglich und nachhaltig machen:

Wie soll sich das System über Jahre entwickeln?
Welche Struktur erlaubt Wachstum ohne exponentielle Komplexität?
Welche Entscheidungen sind reversibel — und welche nicht?
Wo entstehen zukünftige Risiken (Skalierung, Sicherheit, Betrieb, Compliance)?
Welche Abhängigkeiten bauen wir gerade auf — und welche langfristigen Kosten entstehen daraus?

Das sind keine Implementierungsfragen.
Das sind Struktur-, Richtungs- und Nachhaltigkeitsfragen.

Mark Richards und Neal Ford formulierten dazu das erste Gesetz der Softwarearchitektur: Alles in der Softwarearchitektur ist ein Trade-off — und wer glaubt, etwas gefunden zu haben, das keiner ist, hat den Trade-off vermutlich nur noch nicht erkannt.

Ein Senior Developer optimiert die Lösung.
Ein Softwarearchitekt gestaltet den Lösungsraum.

Der Unterschied liegt nicht in der Fähigkeit zu implementieren, sondern im Schwerpunkt der Verantwortung.

Das strukturelle Spannungsfeld: Verantwortung hier, Entscheidungen überall

Wenn Architektur diese Art von Entscheidungen betrifft, ist die eigentliche Frage nicht Kompetenz — sondern ob die Organisation diese Entscheidungen überhaupt möglich macht.

Architektur setzt voraus, dass jemand das große Ganze sehen und wissen kann. Nicht im Sinne von Kontrolle, sondern im Sinne von Überblick: Welche Fähigkeiten existieren bereits? Welche Vorhaben laufen parallel? Welche Integrationen, Datenflüsse und Betriebsannahmen sind im Spiel?

In vielen Organisationen werden Zuständigkeiten scheinbar sauber aufgeteilt: Business entscheidet das Was, Engineering Manager organisieren die Teams, Tech Leads verantworten die Umsetzung im Alltag — und der Architekt kümmert sich um „die Struktur".

Klingt ordentlich. Funktioniert so oft nicht.

Denn Architektur ist keine isolierte Zuständigkeit. Sie ist das Ergebnis von Entscheidungen, die überall getroffen werden:

Wenn das Business beschließt, in neue Märkte zu expandieren, hat das architektonische Konsequenzen.
Wenn die Teamstruktur geändert wird, beeinflusst das, ob Microservices sinnvoll sind oder ein Monolith die bessere Wahl ist.
Wenn ein Team eine neue Programmiersprache einführt, ein anderes ein neues Framework wählt und ein drittes eine eigene Deployment-Pipeline baut — dann entsteht genau die Insellandschaft, die Architektur verhindern soll.
Wie eine Applikation deployed wird, ist eine Architekturentscheidung. Teamzuschnitt, Systemschnitt, Repository-Struktur und Deployment-Fähigkeiten hängen eng zusammen — oft als Kreislauf, der bis in SLAs, Verfügbarkeit und Compliance reicht.

Conway formulierte das bereits 1968: Organisationen, die Systeme entwerfen, sind gezwungen, Designs zu produzieren, die die Kommunikationsstrukturen dieser Organisationen abbilden. Und Ruth Malan formulierte die Konsequenz: Wenn Systemarchitektur und Organisationsarchitektur im Widerspruch stehen, gewinnt die Organisation.

So entsteht ein strukturelles Spannungsfeld: Die Verantwortung für die langfristige Systementwicklung liegt bei der Architektur. Die entscheidungsprägenden Faktoren entstehen aber verteilt in der Organisation. Die Erwartung, dass „der Architekt schon dafür sorgt", besteht — auch wenn er gar nicht eingebunden war. Und das Mandat, an den relevanten Stellen mitzuwirken, fehlt oder ist unklar.

Wenn diese Dinge nicht zusammenpassen, entsteht eine fatale Situation: Architektur wird erwartet, kann aber nicht aktiv gestaltet werden. Sie reagiert auf Entscheidungen, die bereits getroffen wurden, statt sie im Vorfeld mitzuprägen.

Das ist kein Kompetenzproblem. Es ist ein organisationsstrukturelles Muster.

Deshalb muss ein Softwarearchitekt in all diesen Bereichen zumindest einbezogen werden — nicht um das „Ob" zu entscheiden, sondern um das „Was bedeutet das für das System?" rechtzeitig einzubringen. Alles, was über ein einzelnes Team hinausgeht, sollte architektonisch sichtbar sein. Nicht als Genehmigungsprozess. Nicht als Bürokratie. Sondern weil jemand den Überblick behalten muss.

Je nach Teamgröße und Komplexität kann Architektur als Rolle zentral, verteilt oder rotierend gelebt werden. Wichtig ist nicht der Titel. Wichtig ist, dass die Funktion existiert und organisatorisch verankert ist.

Wenn das nicht passiert, sieht man es nicht sofort im Code — sondern in Mustern: Es entstehen lokal sinnvolle Lösungen, die global nicht zusammenpassen. Ähnliche Dinge werden mehrfach gebaut, weil niemand weiß, dass es sie schon gibt. Jede Lösung bringt ihre eigenen Begriffe, Datenmodelle und Schnittstellen mit. Integration und Betrieb werden mit jeder Insel teurer.

Von außen kann das so wirken, als sei Architektur „unnötig". Nicht, weil Architektur keinen Wert hätte, sondern weil die Organisation sie nicht als verbindende Funktion nutzt. Dann bleibt Architektur eine Sammlung von Einzelentscheidungen, die nicht aus einem gemeinsamen Bild heraus entstehen, sondern aus zufälliger Reihenfolge und lokalem Druck.

Das ist keine Kritik an einzelnen Entwickler:innen — es ist eine Beobachtung über Organisationsmechanik.

Ein Beispiel aus der Praxis

Ein System verwaltet Kampagnen mit Start- und Enddaten. Am Anfang reicht ein einfaches DateTime-Feld. Die Annahme: Alle Nutzer sitzen in derselben Zeitzone, Deadlines sind „Ende des Tages", und niemand fragt, welcher Tag genau gemeint ist.

Das funktioniert — solange die Annahme stimmt.

Dann kommen internationale Kunden. Ein Nutzer in New York gibt „5. Juni" als Deadline ein. Ein Nutzer in Wien sieht dasselbe Datum — aber wessen Mitternacht gilt? Das System weiß es nicht, weil der Typ DateTime diese Information nicht trägt. Er speichert eine Zahl ohne Kontext.

Jedes Team löst das Problem lokal:

Das Backend-Team konvertiert alles stillschweigend nach UTC — verliert dabei aber die Information, welche Zeitzone der Nutzer gemeint hat.
Das Frontend-Team zeigt Daten in der Browser-Zeitzone an — die sich vom Server unterscheiden kann.
Ein drittes Team baut einen Reporting-Export, der die Datenbank-Werte direkt ausgibt — in UTC, ohne Umrechnung.

Kein Team hat einen Fehler gemacht. Jede Entscheidung war lokal nachvollziehbar. Aber das System zeigt jetzt für dasselbe Ereignis drei verschiedene Uhrzeiten an — je nachdem, wo man hinschaut.

Das eigentliche Problem liegt tiefer: „Was ist ein Datum in unserem System?" wurde nie als Frage gestellt. Ist es ein Zeitpunkt auf dem Zeitstrahl? Ein Kalendertag im Sinne des Nutzers? Eine Deadline, die eine Zeitzone braucht? Ein wiederkehrendes Ereignis, das sich nach lokalen Regeln richtet? Das sind fundamental verschiedene Konzepte — aber das Datenmodell behandelt sie alle gleich: als eine einzelne Spalte vom Typ timestamp.

Technisch ist all das lösbar. Aber nicht mehr einfach. Das Datenmodell muss aufgespalten werden. Bestehende Daten müssen migriert werden — ohne zu wissen, welche Zeitzone bei der Eingabe gemeint war. Jede Schnittstelle, jeder Report, jede Anzeige muss geprüft werden.

Nicht das Feature war komplex. Die fehlende architektonische Einbettung war es. Eine einzige frühe Entscheidung — „Welche Typen von Zeit gibt es in unserem System, und wie modellieren wir sie?" — hätte den gesamten Folgeaufwand verhindert.

Und genau hier zeigt sich: Architektur ohne Kontext kann nur Inseln verwalten — aber keine Systeme gestalten.

Architektur braucht Fokus und Feedback

Architekturarbeit entsteht nicht im Task-Wechsel zwischen zwei Bugfixes, sondern durch Analyse, Modellierung, Bewertung von Alternativen, gedankliches Durchspielen von Szenarien und bewusste Entscheidungen unter Unsicherheit.

Typische Bestandteile sind:

Dokumentation von Entscheidungen (z. B. ADRs)
Bewertung von Trade-offs
Definition von Leitplanken
Evolutionspfade und Refactoring-Strategien
Risikoanalyse
Abhängigkeits- und Integrationslandkarten
Kommunikation und Alignment über Teams hinweg

Wenn 90 % der Arbeitszeit für Feature-Implementierung reserviert sind, bleibt für all das faktisch kein Raum. Dann wird Architektur nicht gestaltet — sie entsteht als Nebenprodukt. Dann wird aus einem DateTime-Feld ein systemweites Problem — nicht weil die Frage schwer war, sondern weil niemand die Zeit hatte, sie zu stellen. Und das ist einer der teuersten Zustände, die ein Softwaresystem haben kann.

Gleichzeitig scheitert Architektur auch am anderen Ende: wenn Architekten weit entfernt von der täglichen Entwicklung arbeiten. Sie definieren Leitlinien und entwerfen Zielbilder — ohne die praktischen Einschränkungen der Umsetzung wirklich zu kennen. Die Folge ist „Elfenbeinturm-Architektur".

Gute Architektur braucht deshalb beides:

Strategischen Abstand, um langfristig zu denken.
Praktische Nähe, um realistisch zu bleiben.

Ein Architekt programmiert nicht, weil Features umgesetzt werden müssen.
Er programmiert, weil Architektur real sein muss — um Annahmen zu überprüfen, Risiken sichtbar zu machen und Strukturen zu erproben.

Fehlt eines davon, wird Architektur entweder reaktiv — oder realitätsfern.

Man könnte einwenden, dass reaktive Architektur gewollt sein kann. Moderne Architekturansätze verfolgen bewusst das Prinzip, Entscheidungen möglichst spät zu treffen — dann, wenn mehr Informationen verfügbar sind.

Der Unterschied liegt nicht im Zeitpunkt, sondern im Grund:

Strategie: Wir könnten früher entscheiden, tun es aber absichtlich später. Beispiel: Wir lassen die Storage-Technologie offen, definieren aber klare Schnittstellen und Performance-Checks, bis Lastprofile messbar sind.
Zwang: Wir müssen jetzt reagieren, weil uns vorher Informationen, Einfluss oder Zeit gefehlt haben. Beispiel: Wir wählen „irgendeine" Technologie unter Zeitdruck, ohne Lastannahmen, ohne Leitplanken, ohne Ausstiegspfad.

Beides sieht von außen „reaktiv" aus. Ist aber fundamental verschieden.

Woran du erkennst, dass Architektur nicht wirklich existiert

Nicht als Titel. Sondern als gelebte Funktion.

Werden strukturelle Entscheidungen bewusst dokumentiert — oder nur umgesetzt?
Gibt es explizite Zeit für Architekturarbeit — oder passiert sie „wenn gerade Luft ist"?
Sind Architekten in strategische Produktentscheidungen eingebunden?
Werden größere Änderungen vor Umsetzung teamübergreifend sichtbar gemacht?
Gibt es Transparenz darüber, welche Fähigkeiten und Module bereits existieren?
Werden technische Leitplanken aktiv definiert — oder entstehen sie implizit?
Gibt es geplante Evolutionspfade — oder nur Refactorings bei Bedarf?
Werden langfristige Risiken aktiv diskutiert — oder erst sichtbar, wenn sie auftreten?

Wenn die meisten Antworten „nein" sind, existiert Architektur vermutlich nicht als gestaltende Funktion.

Und Emergenz ist kein Ersatz für Verantwortung.

Fazit

Ein Softwarearchitekt ist nicht einfach ein Senior Developer mit anderem Titel.
Er ist verantwortlich für Struktur, Richtung und Zukunftsfähigkeit eines Systems.

Dafür braucht er Kontext, Einfluss, Zeit und ein Mandat. Wenn davon etwas fehlt, kann er seine Aufgabe nicht erfüllen — egal wie kompetent er ist.

Deshalb sollte jedes Unternehmen, das den Titel „Softwarearchitekt" verwendet, sich eine einfache Frage stellen:

Wollen wir Architektur wirklich gestalten?
Oder wollen wir nur so tun, als gäbe es sie?

Showing a Date Needs Three Decisions

bwi — Mon, 09 Feb 2026 17:36:07 +0000

Why showing a date always involves three implicit decisions

Date representations feel trivial.
They are everywhere.
And because of that, they are rarely questioned.

MM/dd/yyyy
dd.MM.yyyy
dd. MMMM yyyy

They look harmless.
They look technical.
They look solved.

But they aren't.

Behind every date representation are decisions — and most systems make them implicitly.

The core insight

A date representation always consists of three parameters. Always.

Format

Language

Region / cultural conventions

Even if we do not specify them explicitly.
Even if we rely on defaults.

Defaults do not remove these parameters.
They merely hide them.

1. Format — structure

The format defines how the date is structured:

dd.MM.yyyy
MM/dd/yyyy
dd. MMMM yyyy

It controls:

order (day / month / year)
separators (., /, ,)
numeric vs textual representation

What it does not define:

language
region
cultural expectation

A format describes shape, not meaning.

2. Language — words

Language determines which words are used:

January / Januar / Jänner
Monday / Montag
March / März

But language alone says nothing about:

date order
separators
customary notation

"German" is not enough.
"English" is not enough.

3. Region / cultural conventions — expectations

The region defines what people expect to see:

dd.MM.yyyy vs MM/dd/yyyy
dots vs slashes
typical short and long forms
week start

Two users can:

speak the same language
read the same month name
and still expect different representations

These three parameters always exist

Even when we only specify one.

Example:

en

What does this actually mean?

In most systems, it implicitly becomes something like:

Language: English
Region: US
Format: MM/dd/yyyy

But these are assumptions, not facts.

No one explicitly chose them.
No one documented them.
No one can reliably explain them later.

Language + region as locale tags (IETF BCP 47)

So we have three parameters — but in practice, two of them (language and region) are usually expressed together as a locale tag.
A locale tag does not replace the format — it only covers language and region.
Most platforms follow a standard for this: IETF BCP 47.

So when we write de-AT or en-US, we are not just picking a language.
We are selecting a language and a regional set of conventions.

A (common) BCP 47 tag has the form:

language-region

Language: ISO 639 (usually lowercase), e.g. de, en
Region: ISO 3166 (usually uppercase), e.g. AT, US, GB

The important part: language and region are independent dimensions.
Any combination can be meaningful:

en-AT — English language, Austrian conventions
de-US — German language, US conventions

Also note the order: AT is a region, so it comes second (en-AT), not first.

Some systems use an underscore notation like en_AT.
In the browser Intl APIs, the standard form is the hyphen: en-AT.

But even a full locale tag only covers two of the three decisions. The format is still a separate choice.

Defaults are not decisions

When we specify only part of the information, the system fills in the rest:

browser
operating system
runtime
library
framework

Each layer makes a reasonable guess.

Fallbacks do not replace missing parameters.
They only hide them.

Internally, there is still:

a concrete format
a concrete language
a concrete region

They are just implicit.

Example 1: `dd. MMMM yyyy`

Format: dd. MMMM yyyy

This only means:

"Write the month name in full."

But which one?

January
Januar
Jänner

Without language and region, the format alone is meaningless.

Example 2: German is not just German

Language: German

What does that imply?

de-DE → Januar
de-AT → Jänner

Both are correct.
Both are German.
And yet, they are not interchangeable.

Language alone is insufficient.

Example 3: English is not a culture

Locale: en-AT

This means:

Language: English
Region: Austria

A perfectly valid and realistic scenario:

English UI
Austrian date conventions

English does not imply US culture.
It never did.

These parameters can come from different sources

In real systems, they rarely originate from one place.

Typical sources include:

Browser / OS — implicit, uncontrolled
User profile — explicit, but often incomplete
Admin / organization — standardized, intentional
Context / use case — UI, export, contract, audit log

Consider a real scenario:

A user's browser is set to de-DE.
Their organization is based in Austria.
An admin has configured dates to display in long format.

If the system resolves the locale from the browser, the user sees Januar. If it resolves from the organization, they see Jänner. Which one wins depends on the implementation — and that's rarely documented.

Either way, someone sees a date that doesn't match their expectation.

There is no single "correct" date.

Even the format is a decision

Most platforms offer predefined format levels:

short
medium
long
full

But you can also define a fully custom format like dd. MMMM yyyy.

Either way, the choice of format is not a technical detail.
It is a product decision:

In which context do users see a short date? When do they see a long one?
Who decides — the developer, the admin, the product?

These are not implementation details. They belong to product design, configuration, and context — not just code.

The common mistake

We say:

"We support localization."

And what we actually mean is:

a format
a default locale
some Intl APIs

What we really have is:

a collection of implicit assumptions.

And those assumptions have consequences:

A contract rendered with 01/02/2025 — is that January 2nd or February 1st?
A user in Vienna sees Januar and wonders why the system doesn't know their country.
An audit log stores dates in the server's locale — which changes after a migration.

These are not edge cases.
They are the natural result of treating three decisions as one.

The key takeaway

A date is only reasonably represented when
format, language, and region are all explicitly defined.

Everything else is guessing.

Once you accept that these three decisions always exist, the remaining question is no longer if you should define them — but where.

What to do

Always pass format, language, and region explicitly — never rely on one to imply the others.
Treat format selection (short, long, full) as a product decision, not a developer default.
Define a clear priority for where each parameter comes from: user profile, tenant, admin policy, or context.
Never persist or export dates in a locale-dependent format without documenting which locale.
When in doubt, make the decision visible — in configuration, in documentation, in code.

In the browser: `Intl.DateTimeFormat`

The browser is one of the most common user interfaces — and it already has an API that models all three decisions explicitly: Intl.DateTimeFormat.

Format: `dateStyle`

The dateStyle option controls the shape of the output:

const date = new Date("2025-01-02");

new Intl.DateTimeFormat("de-AT", { dateStyle: "short" }).format(date)
// → "02.01.25"

new Intl.DateTimeFormat("de-AT", { dateStyle: "medium" }).format(date)
// → "02.01.2025"

new Intl.DateTimeFormat("de-AT", { dateStyle: "long" }).format(date)
// → "2. Jänner 2025"

new Intl.DateTimeFormat("de-AT", { dateStyle: "full" }).format(date)
// → "Donnerstag, 2. Jänner 2025"

Same locale. Only the format changes.

Language + Region: the locale tag

The locale tag is where language and region are combined (BCP 47).
In Intl, use the hyphen form: de-AT (not de_AT).

const date = new Date("2025-01-02");

new Intl.DateTimeFormat("de-DE", { dateStyle: "long" }).format(date)
// → "2. Januar 2025"

new Intl.DateTimeFormat("de-AT", { dateStyle: "long" }).format(date)
// → "2. Jänner 2025"

new Intl.DateTimeFormat("en-US", { dateStyle: "long" }).format(date)
// → "January 2, 2025"

new Intl.DateTimeFormat("en-GB", { dateStyle: "long" }).format(date)
// → "2 January 2025"

new Intl.DateTimeFormat("en-AT", { dateStyle: "long" }).format(date)
// → "2 January 2025"

Same date. Same format level. Completely different output — because language and region differ.

What happens when we leave things out?

new Intl.DateTimeFormat("en").format(new Date("2025-01-02"))
// → depends on the browser's region assumption
// Could be "1/2/2025" (US) or "02/01/2025" (GB)

new Intl.DateTimeFormat().format(new Date("2025-01-02"))
// → depends entirely on the browser/OS default locale

This is exactly the problem: the API works — but only if we pass all three decisions explicitly.

When we leave the locale vague or omit dateStyle, the browser fills in the gaps. Silently. Differently on every machine.

The API already supports this

Intl.DateTimeFormat does not force us to guess. It lets us express all three decisions in a single call:

new Intl.DateTimeFormat("de-AT", { dateStyle: "long" })

Format: long
Language: German
Region: Austria

Three parameters. One line. No ambiguity.

The tools exist. The question is whether we use them — or let the defaults decide for us.

Server-side runtimes follow the same model (for example: CultureInfo in .NET, Locale in Java) — but that's a topic for another post.

Conclusion

Every date representation requires three parameters
They exist even when we do not specify them
Defaults are assumptions, not decisions
Implicit decisions are the most dangerous ones

Localization does not start with APIs.
It starts where a product takes responsibility.

Configuration Needs Semantics

bwi — Fri, 30 Jan 2026 00:06:04 +0000

Configuration is everywhere.

It's the mechanism that lets applications change behavior without recompiling, redeploying, or rewriting code.
Timeouts, limits, feature switches, credentials, rollout toggles — configuration is how software adapts to its environment.

And anything that's everywhere is easy to treat as trivial.

In many systems, configuration consists of a boolean here, a string there, maybe a rule evaluated at runtime.
And this works surprisingly well. You can build entire products on top of nothing more than key–value pairs.

But while the code may not care, the people working with the system do.
And that is where problems begin.

This article is not about how to implement configuration. It is about why configuration needs semantics — and what happens when it doesn’t.

Everything Could Be Configuration

Imagine a small billing service with a single config.json:

{
  "paymentTimeoutSeconds": 30,
  "enableNewCheckoutFlow": true,
  "goldPlanAccess": true,
  "stripeApiKey": "sk_live_..."
}

Technically, these are just values.

Semantically, these values represent very different kinds of concerns:
some describe behavior,
some control rollout,
some grant access,
and some should be treated as confidential.

From a purely technical perspective, all of them could be modeled the same way:

true / false
strings
numbers
rules evaluated against context

And in many systems, they are exactly that.

This is appealing because it is:

simple
flexible
uniform

But this uniformity comes at a cost.

Why This Works Technically — and Fails Mentally

The runtime does not care why a value exists.
It only cares what the value is.

But humans are different.

When developers, architects, or product owners make decisions based on configuration, they inevitably form expectations.

In many systems, configuration is just a JSON file, an environment variable,
or a key–value store.
From that alone, you cannot tell whether a value represents one kind of configuration or another.

You also cannot answer questions like:

how long something is expected to exist
who owns it
whether it may be removed
whether it is temporary or permanent
whether it is safe to change

The configuration source is semantically silent.
Expectations come not from the file, but from how values are used in code.

If everything is consumed the same way, then everything means the same thing.

This is not a technical failure.
It is a mental model failure.

Meaning does not come from data types or storage.
It comes from intent.

Semantics Through Explicit Categories

To avoid this, configuration needs more than values.
It needs meaning.

One way to provide that meaning is by using explicit categories.
Not because the system requires them — but because humans do.

Below are four common categories that often get conflated, despite answering very different questions.

Configuration

Defines:

Baseline system behavior.

Characteristics:

usually stable
changed infrequently
no inherent expiration
not security-sensitive
not contractually relevant

Examples:

timeouts
thresholds
limits
algorithm parameters

Configuration sets the baseline behavior of a system.

Secrets

Defines:

Confidential data that must be protected.

Characteristics:

security boundaries
different storage requirements
restricted access
often rotated

Examples:

passwords
API keys
certificates

A secret may be “just a string” technically — but semantically it represents a security constraint, not behavior.

A secret stored as a string will eventually be logged — not out of malice, but out of invisibility.

Feature Flags

Defines:

Temporary activation of behavior.

Characteristics:

explicitly temporary
expected to disappear
often tied to rollout or experimentation
create maintenance pressure

A crucial aspect of feature flags is expected end-of-life.

Just calling something a feature flag does not make it temporary.
Only active, operational pressure to remove it does.

Without expiration tracking, warnings, or any mechanism that makes overstaying visible, you have not created a feature flag — you have created configuration with a different label.

In other words, the distinction between a feature flag and permanent configuration is not semantic, but operational: if nothing tracks expiry, notifies you of neglect, or surfaces overdue removal, then "feature flag" is just a name that was given once, not a property the system still enforces.

And this expectation strongly influences how developers:

review code
accept shortcuts
tolerate complexity

Entitlements

Defines:

Long-term access to behavior.

Characteristics:

stable
contractually relevant
audit-sensitive
rarely removed

Entitlements represent permissions, not rollout state.
They are expected to persist.

Same Mechanism, Different Meaning

From an implementation perspective, feature flags and entitlements may look identical:

a boolean
a rule evaluated against context
a configuration value

But semantically, they create very different expectations.

Aspect	Feature Flag	Entitlement
Expected lifetime	Temporary	Long-term
Removal	Expected	Rare
Review strictness	Often relaxed	High
Audit relevance*	Low	High

*Audit relevance here refers to contractual, legal, or billing-related accountability —
not technical logging.

These categories are not immutable — but moving between them should be an explicit decision, not an accident.

When these distinctions are blurred, systems don’t break immediately.
They slowly accumulate misunderstandings.

In many SaaS systems, a single capability goes through both stages:

During rollout, it is guarded by a feature flag (for example, enableNewCheckoutFlow).
Once stable and part of a paid plan, access is governed by an entitlement (for example, goldPlanAccess).

These are different concerns and often belong to different systems of record.
Confusing them leads to permanent flags and unclear contracts.

Maintenance, Planning, and Self-Deception

The most dangerous failure mode is not technical debt.
It is self-deception.

When something temporary is modeled as permanent — or vice versa — teams begin to lie to themselves:

“We’ll clean this up later.”
“This is just a flag.”
“It’s basically a permission.”

The code still compiles.
The system still runs.

But planning becomes unreliable, and maintenance decisions quietly lose clarity.

Warnings as Support, Not Enforcement

Explicit semantics are not about forcing behavior.
They are about making assumptions visible.

Instead of blocking changes, systems can surface signals:

warnings when temporary decisions overstay their intent
growing visibility when cleanup is deferred

Nothing is blocked.
Nothing breaks.

But the system no longer allows decisions to remain silent.

This protects developers and architects by turning vague pressure into explicit signals.

This is not enforcement.
It is a way to make assumptions and technical debt visible.

Conclusion

Configuration is not just about values.
It is about expectations.

Without semantics, configuration becomes a generic container where everything looks the same — and therefore means nothing.

Explicit categories do not make systems rigid.
They make intentions visible.

And visibility is often the difference between maintainable systems and ones that quietly drift out of control.

Indeterminate Is Not a Value

bwi — Wed, 28 Jan 2026 19:13:05 +0000

Indeterminate Is Not a Value

In Part 1, we established what a checkbox actually is: a binary control with presence-based semantics. We learned that "unchecked" doesn't mean "No" — it means "no participation."

Sometimes you need to represent more than two business states. Some UIs use a checkbox with a dash (—) or filled square for that.

This article explains what indeterminate means in HTML, what it does not mean, and the two distinct scenarios where it is commonly used.

Later, it also introduces a cleaner alternative when you truly need three business states: the participation pattern (checkbox + separate value control).

Part 1: Indeterminate Is Display-Only

What Indeterminate Looks Like

You've probably seen it: a checkbox that's neither checked nor unchecked, but shows a dash (—) or a filled square. This is the indeterminate state.

It looks like a third state. It feels like a third state.

It is not a third state.

What the Specification Actually Says

The HTML specification is explicit:

The indeterminate IDL attribute [...] gives the appearance of a third state.

Key word: appearance. It looks like a third state, but technically it isn't one.

And from MDN:

indeterminate is a JavaScript property only
There is no HTML attribute for it
It has no effect on form submission
It only changes how the checkbox looks

In other words:

Indeterminate is not a value. It's a visualization.

You Cannot Set It in HTML

This doesn't work:

<!-- This does nothing -->
<input type="checkbox" indeterminate>

You can only set it via JavaScript:

checkbox.indeterminate = true;

What Happens When the User Clicks?

Behavior on click: When the user clicks an indeterminate checkbox, the browser immediately clears the indeterminate state and toggles checked as normal.

The user cannot "select" indeterminate. They can only move away from it.

Part 2: Two Completely Different Reasons for Indeterminate

There are two completely different reasons to show an indeterminate checkbox — and they should not be treated as the same thing.

Reason A: Mixed (Aggregation)

Scenario: A parent checkbox with multiple child checkboxes.

All children checked → Parent shows checked
All children unchecked → Parent shows unchecked
Some children checked, some not → Parent shows indeterminate

What indeterminate means here:

"The children have different values."

Key characteristics:

The parent has no value of its own
The visual state is computed from children
Clicking the parent is a command (set all children to true/false)
Nothing should be stored for the parent

This is the correct use of indeterminate as defined by ARIA (the accessibility standard for web applications):

aria-checked="mixed" indicates a mixed mode value for a tri-state checkbox.

Reason B: Unset (Unknown/Never Answered)

Scenario: A checkbox that has never been interacted with.

User has never clicked it
No default value was set
The system doesn't know the answer

What indeterminate means here:

"No decision has been made yet."

Important distinction: From here on, we are no longer talking about the checkbox itself. The checkbox is still binary — it's still either ticked or not ticked. We are talking about the business meaning that the checkbox represents — what it means for your application or process.

Key characteristics:

There is no business value yet — not "yes", not "no", but "we don't know"
It's about user interaction history, not aggregation
First click should set a value (typically true)
The absence itself might be significant (e.g., "never answered" vs "answered no")

The Problem: Same Visual, Different Meaning

Both scenarios often use the same visual representation — the indeterminate dash.

But they mean completely different things:

Aspect	Mixed (Aggregation)	Unset (Unknown)
Source	Computed from children	Missing data
Has a domain value?	No (derived)	No (not yet decided)
Should be stored?	Never	Maybe (as "unknown")
User can select it?	No	No
What click does	Command to children	Sets initial value

When a system uses the same checkbox component for both without making the distinction explicit, bugs follow.

Part 3: The Value Question

A common question:

If a checkbox is indeterminate, what is its value?

Answer

A checkbox doesn't have an "indeterminate" value.

It has either:

true (checked)
false (unchecked)
no value (the concept is modeled elsewhere)

indeterminate is purely how it's displayed.

For Mixed (Parent Checkbox)

The parent checkbox has no value of its own.

// Parent state is DERIVED
function getParentState(children) {
    const checked = children.filter(c => c.checked);
    if (checked.length === 0) return { checked: false, indeterminate: false };
    if (checked.length === children.length) return { checked: true, indeterminate: false };
    return { checked: false, indeterminate: true }; // checked still exists but is visually suppressed when indeterminate is true
}

Note: When indeterminate is true, the checked value is visually hidden but still exists. It just doesn't represent anything meaningful.

For Unset (Unknown)

The value is outside the checkbox:

// Domain model
type Answer = true | false | undefined;

// UI mapping
function toCheckboxState(answer: Answer) {
    if (answer === undefined) {
        return { checked: false, indeterminate: true };
    }
    return { checked: answer, indeterminate: false };
}

The undefined lives in your model, not in the checkbox.

The checkbox never becomes tri-state. Only the meaning we project onto it does.

Part 4: The Participation Pattern

Remember from Part 1: "Unchecked means no participation."

What if you actually need three states?

Yes
No
I don't want to answer / Not applicable

A single checkbox cannot do this. But two controls can:

The Pattern: Checkbox + Value Control

<label>
    <input type="checkbox" id="participation">
    I want to answer this question
</label>

<fieldset id="answer" disabled>
    <label><input type="radio" name="vote" value="yes"> Yes</label>
    <label><input type="radio" name="vote" value="no"> No</label>
</fieldset>

participation.addEventListener('change', () => {
    answer.disabled = !participation.checked;
});

Semantics:

Checkbox unchecked → "I don't want to participate" (no value sent)
Checkbox checked + Yes → "Yes"
Checkbox checked + No → "No"

This cleanly separates:

Participation (checkbox)
Value (radio/select)

Why This Is Better Than Tri-State

A tri-state checkbox tries to pack three meanings into one control:

Checked = Yes
Unchecked = No
Indeterminate = Unknown

But as we've seen:

Indeterminate has no value
The visual is ambiguous (mixed vs unknown)

The participation pattern is:

Explicit
Accessible
Unambiguous
Actually works with HTML semantics

Part 5: When to Use What

Use a Simple Checkbox When:

You need a binary opt-in (newsletter subscription)
"Not selected" means "does not apply" (consent checkboxes)
You're toggling a UI feature (show/hide advanced options)

Use Parent/Child Checkboxes When:

You have a hierarchical selection (folder contents)
"Select all" functionality
Parent state is always computed, never stored

Use the Participation Pattern When:

"No answer" is meaningfully different from "No"
You need to track whether something was explicitly answered
The question is optional but the answer must be definitive

Use Radio Buttons When:

You need explicit Yes/No
All options are mutually exclusive
"No selection" should not be possible

Use a Select/Dropdown When:

You have more than 2-3 options
You need a "Please select..." placeholder
Space is constrained

Part 6: Practical Rules

Based on everything we've discussed, here are practical rules for keeping checkbox semantics consistent:

1. Indeterminate Is Display-Only

Never try to store "indeterminate" as a value.

It's a visualization. Treat it that way.

2. Mixed Should Be Computed

Parent checkbox state = function of children. Always.

If you're storing a parent checkbox value alongside its children, you're creating a consistency problem.

3. Separate "Unknown" from "Mixed"

If both concepts exist in your system, they need different UI treatments.

Same visual + different meaning = bugs.

4. When In Doubt, Add a Control

If a checkbox feels overloaded, it probably is.

The participation pattern (checkbox + value control) is almost always clearer than a tri-state checkbox.

5. Make Assumptions Explicit

Document what "unchecked" means in your system.

Is it false? Is it null? Is it "not answered"? Is it "does not participate"?

If you can't answer this question clearly, neither can the next developer.

Summary

Concept	What It Is	What It's For
`checked`	Boolean property	The actual state
`indeterminate`	Visual hint (JS only)	Showing "mixed" or "unknown"
Mixed state	Computed from children	Parent/child hierarchies
Unknown/Unset	Missing value in model	Optional questions
Participation pattern	Checkbox + separate control	When you need 3+ states

The checkbox is still simple. It's binary, presence-based, and does exactly one thing.

The complexity comes from what we try to make it represent.

Why Checkboxes Are Not as Simple as They Seem

bwi — Wed, 28 Jan 2026 19:06:51 +0000

Checkboxes are often described as the simplest form control. They look trivial, behave predictably, and everyone thinks they understand them.

Until assumptions diverge.

This article is not about bugs or blame. It's about understanding what a checkbox actually is — step by step, from plain HTML through JavaScript to modern frameworks.

Because most checkbox problems don't start with broken code. They start with different assumptions quietly colliding.

Part 1: The HTML Foundation

What a Checkbox Actually Is

According to UI definitions, a checkbox is a control that allows the user to make a binary choice — essentially "on/off" in terms of selection state. Binary means: exactly two options, nothing in between.

In the HTML specification, a checkbox exposes its state through checkedness — a boolean indicating whether the control is checked. There is no built-in tri-state value.

That's it. A checkbox answers exactly one question:

Is this option selected?

It does not represent:

Yes vs. No as a domain answer
True vs. False as business meaning
Unknown, unset, or partial states

UI State vs. Form Submission

As a UI control, a checkbox gives you exactly one thing: whether it is checked or not checked.

But HTML checkboxes often live inside HTML forms. And forms are not about UI state — they are about data transmission.

So a second concept shows up. Not a second state, but a second role: what data should be sent when the form is submitted?

Two Separate Roles: `checked` vs. `value`

HTML checkboxes have two completely separate concepts that are often confused:

checked

A boolean UI state (true / false)
Represents whether the checkbox is ticked
This is the actual state of the control

value

A string payload — think of it as a label that gets sent along
Only relevant during form submission
Only sent if the checkbox is checked

In simple terms: The checkbox decides if something is sent. The value decides what is sent.

A simple example:

<input type="checkbox" name="newsletter" value="subscribe-me">

What happens on form submission? (Submitting a form simply means: sending the entered information to another system, like a server.)

Checkbox State	What Gets Sent
Checked	`newsletter=subscribe-me`
Unchecked	(nothing)

Notice: A checkbox never submits true or false. It submits a string if checked, and nothing if unchecked.

This makes HTML checkboxes presence-based, not value-based.

Key Takeaway

Key takeaway:

Unchecked does not mean "No".
Unchecked means "no participation".

In plain HTML:

checked → a statement is made
unchecked → no statement is made

Unchecked does not mean:

false
no
0

It simply means: This field does not participate in the submission.

Why This Matters: The Consent Pattern

Consider the classic example:

"I accept the terms and conditions."

This is not a Yes/No question. It's a confirmation:

checked → confirmation exists
unchecked → confirmation missing

There is no meaningful "No" answer. You either confirm, or you don't. This is exactly what checkboxes are designed for.

If your question truly needs both "Yes" and "No" as explicit answers, a checkbox is the wrong control. Use radio buttons or a dropdown instead.

A Checkbox Without `name`

What about this?

<input type="checkbox" id="showAdvanced">

This checkbox:

has a checked state
can be toggled by the user
can be read and written via JavaScript

But it never submits anything — because only form controls with a name attribute participate in form submission.

This makes such checkboxes ideal for:

UI-only toggles (dark mode, show/hide sections)
Parent/controller checkboxes
Derived or aggregated display states

Part 2: Adding JavaScript

What Actually Changes?

When JavaScript enters the picture, something important happens:

Nothing about the checkbox itself changes.

checked is still a boolean
value is still a string
The control is still binary

JavaScript simply gives us access to the existing state:

// Reading
const isChecked = checkbox.checked; // always true or false

// Writing
checkbox.checked = true;

And it lets us react to changes:

checkbox.addEventListener('change', (event) => {
    console.log(event.target.checked);
});

JavaScript does not add new semantics. It only makes the existing state readable and writable.

The `checked` Property

The DOM property checkbox.checked is always a boolean:

Always true or false
Never null
Never undefined

This is the single source of truth for the checkbox state.

Type Coercion Pitfalls

A common source of bugs: JavaScript will happily coerce any value to a boolean:

let value; // undefined
checkbox.checked = value;
// checkbox shows as unchecked

let text = "false";
checkbox.checked = text;
// checkbox shows as CHECKED! (non-empty string is truthy)

No error. No warning. The assignment just works.

But meaning gets collapsed:

Boolean(undefined)  // false
Boolean(null)       // false
Boolean(false)      // false
Boolean("")         // false
Boolean("false")    // true (!)
Boolean(0)          // false

At this point, different concepts — false, null, "never touched", empty string — suddenly look identical in the UI.

The Key Rule

Truthy/falsy is a control-flow feature, not a domain model.

Checkbox logic must be explicit, not coerced. Just because JavaScript doesn't throw an error doesn't mean your logic is correct.

JavaScript Still Doesn't Provide "No"

Even with JavaScript:

checked === true → a statement exists
checked === false → no statement exists

JavaScript does not turn unchecked into an explicit "No". Unchecked still means: This checkbox is not participating.

Part 3: Modern Applications and Frameworks

The Shift: From Form Submit to Data Objects

In modern web applications, checkboxes are rarely submitted via classic HTML forms.

Instead, we typically:

Read the checkbox state in JavaScript
Map it to a true/false property in a data object
Send that data object to a server

(Technical note: These data objects are often called "DTOs" — Data Transfer Objects — and are usually sent as JSON, a text format that computers can easily read.)

const formData = {
    name: nameInput.value,
    subscribed: newsletterCheckbox.checked  // boolean
};

fetch('/api/users', {
    method: 'POST',
    body: JSON.stringify(formData)
});

Under this very common pattern:

A checkbox is interpreted as a boolean value.

This is a reasonable and pragmatic choice. But it's still an interpretation, not an inherent property of the checkbox.

How Frameworks Handle It

Frameworks like Angular, React, or Vue build on this boolean assumption.

Angular has a dedicated CheckboxControlValueAccessor that:

Reads event.target.checked (boolean)
Writes directly to the checked property
Ignores the HTML value attribute for single-checkbox boolean mapping

This makes checkbox handling feel straightforward:

// Angular Reactive Forms
this.form = new FormGroup({
    newsletter: new FormControl(false)  // boolean
});

The framework abstracts away the HTML details and gives you a clean boolean interface.

This abstraction is convenient, but it can hide mismatches between UI state and domain meaning.

Where `null` and `undefined` Come From

If the checkbox is always true or false, where do null and undefined come from?

Not from the checkbox itself. They come from:

Initialization — You create a form control without a default value
Mapping/Serialization — Your code only sets properties when they're truthy
API Responses — Backend sends null for "not set"

In older Angular versions (before Typed Forms), a FormControl without an initial value had null as its value — not undefined, not false. This is an Angular design decision, not a checkbox behavior.

The Model Mismatch

A common mismatch: four different systems have four different models:

System	Model
HTML	Presence-based (checked = participates)
JavaScript	Type coercion (everything becomes boolean)
Framework	State container (FormControl has a value)
Domain/Backend	Business meaning (true/false/null/unknown)

Each model is correct within its context.

Problems arise when these models collide without explicit translation layers.

Part 4: The Perspective Problem

No Bugs, Just Colliding Assumptions

In practice:

There is no bug here.
There are just multiple correct assumptions that don't align.

HTML behaves correctly
JavaScript behaves correctly
Angular Forms behave correctly
Developers act reasonably

The system as a whole becomes inconsistent — not the individual parts.

When Perspectives Collide

If you only know one layer, everyone else seems to be doing it wrong:

Know C#/Backend? → "Why doesn't the UI send false?"
Know HTML? → "Unchecked means nothing gets sent, obviously."
Know JavaScript? → "!!value is completely normal."
Know Angular? → "The FormControl has null, what's the problem?"

Each perspective is internally logical. But each also blinds you to the others.

The Real Takeaway

A checkbox is not complicated. But it's also not magical.

It provides:

A binary UI state
Presence-based semantics

Everything else — booleans, DTOs, defaults, workflows, null handling — is an assumption we add on top.

Problems arise when different parts of a system operate under different assumptions, without ever making them explicit.

Summary

Layer	What You Get
HTML	Binary control, presence-based submission
JavaScript	Read/write access, implicit type coercion
Frameworks	Boolean abstraction, state management
Your Code	Whatever meaning you assign

The checkbox did exactly what it was designed to do.

The question is: Did everyone agree on what that means?

Frontend – Temporal, APIs, and DateTimePickers That Don't Lie

bwi — Thu, 22 Jan 2026 22:10:07 +0000

Part 8 of 8 in the series Time in Software, Done Right

You've modeled time correctly on the backend. You've stored it properly in the database. Now you need to handle it in the browser — where users pick dates and times, and where your API sends data back and forth.

JavaScript's Date object has been the source of countless bugs. The Temporal API finally gives us proper types. But even with good types, you still need to think about what your DateTimePicker is actually asking users to select, and how to send that data across the wire.

This article covers the Temporal API, API contract design, and the principles behind DateTimePickers that don't mislead users.

Why JavaScript's Date Is Problematic

The Date object has been with us since 1995. It has... issues:

// Months are 0-indexed (January = 0)
new Date(2026, 5, 5)  // June 5th, not May 5th

// Parsing is inconsistent across browsers
new Date("2026-06-05")  // Midnight UTC? Midnight local? Depends on browser.

// No timezone support beyond local and UTC
const d = new Date();
d.getTimezoneOffset();  // Minutes offset, but which zone? You don't know.

// Mutable (a constant footgun)
const d = new Date();
d.setMonth(11);  // Mutates in place

There's no LocalDate, no LocalDateTime, no ZonedDateTime. Just one type that tries to do everything and does none of it well.

The Temporal API

The Temporal API is the modern replacement for Date. It's currently at Stage 3 — the final candidate stage before standardization — and requires a polyfill in most browsers (e.g., @js-temporal/polyfill). Browser support is coming, but for now, plan on using the polyfill.

Type Mapping

Concept	Temporal Type	NodaTime Equivalent
Physical moment	`Temporal.Instant`	`Instant`
Calendar date	`Temporal.PlainDate`	`LocalDate`
Wall clock time	`Temporal.PlainTime`	`LocalTime`
Date + time (no zone)	`Temporal.PlainDateTime`	`LocalDateTime`
IANA timezone	`Temporal.TimeZone`	`DateTimeZone`
Full context	`Temporal.ZonedDateTime`	`ZonedDateTime`

The names differ (Plain vs Local), but the concepts are identical. If you've understood NodaTime, you already understand Temporal.

Basic Usage

// Just a date
const date = Temporal.PlainDate.from("2026-06-05");
const date2 = new Temporal.PlainDate(2026, 6, 5);  // Months are 1-indexed!

// Just a time
const time = Temporal.PlainTime.from("10:00");

// Date and time (no zone)
const local = Temporal.PlainDateTime.from("2026-06-05T10:00");

// With timezone
const zone = Temporal.TimeZone.from("Europe/Vienna");
const zoned = local.toZonedDateTime(zone);

// Get the instant
const instant = zoned.toInstant();

Converting Between Types

// ZonedDateTime → components
const zoned = Temporal.ZonedDateTime.from("2026-06-05T10:00[Europe/Vienna]");
const local = zoned.toPlainDateTime();     // PlainDateTime
const instant = zoned.toInstant();          // Instant
const tzId = zoned.timeZoneId;              // "Europe/Vienna"

// Instant → ZonedDateTime (for display)
const instant = Temporal.Instant.from("2026-06-05T08:00:00Z");
const inVienna = instant.toZonedDateTimeISO("Europe/Vienna");
const inLondon = instant.toZonedDateTimeISO("Europe/London");

DST Handling

Temporal handles DST ambiguities explicitly:

// Time that doesn't exist (spring forward gap)
const local = Temporal.PlainDateTime.from("2026-03-29T02:30");
const zone = Temporal.TimeZone.from("Europe/Vienna");

// Default ("compatible"): shifts forward for gaps, picks earlier occurrence for overlaps
const zoned = local.toZonedDateTime(zone, { disambiguation: "compatible" });
const zoned = local.toZonedDateTime(zone, { disambiguation: "reject" });      // Throws

// Time that exists twice (fall back overlap)
const local = Temporal.PlainDateTime.from("2026-10-25T02:30");
const zoned = local.toZonedDateTime(zone, { disambiguation: "earlier" });  // First occurrence
const zoned = local.toZonedDateTime(zone, { disambiguation: "later" });    // Second occurrence

API Contracts: Sending Time Across the Wire

When your frontend talks to your backend, you need a clear contract for time values. There are several approaches.

Option 1: ISO Strings (Simple)

For instants, use ISO 8601 with Z suffix:

{
  "createdAt": "2026-06-05T08:00:00Z"
}

Unambiguous. Both sides parse it the same way.

Option 2: Structured Object (Recommended for User Intent)

For human-scheduled times, send the components:

{
  "appointment": {
    "localStart": "2026-06-05T10:00:00",
    "timeZoneId": "Europe/Vienna"
  }
}

The backend receives exactly what the user chose. It can:

Validate the timezone ID
Handle DST ambiguities with domain-specific logic
Compute the instant
Store all three values

Option 3: ZonedDateTime String

Temporal and some APIs support bracketed timezone notation:

{
  "startsAt": "2026-06-05T10:00:00[Europe/Vienna]"
}

This is compact and unambiguous, but not all JSON parsers handle it natively. You'll need custom parsing.

What NOT to Do

// DON'T: Ambiguous local time
{ "startsAt": "2026-06-05T10:00:00" }  // What timezone?

// DON'T: Offset without timezone ID
{ "startsAt": "2026-06-05T10:00:00+02:00" }  // Which +02:00 zone?

// DON'T: Unix timestamp for user-scheduled events
{ "startsAt": 1780758000 }  // Lost the user's intent

TypeScript Interfaces

Define clear types for your API:

// For instants (logs, events, timestamps)
interface AuditEvent {
  occurredAt: string;  // ISO 8601 with Z: "2026-06-05T08:00:00Z"
}

// For user-scheduled times
interface ScheduledTime {
  local: string;       // ISO 8601 without offset: "2026-06-05T10:00:00"
  timeZoneId: string;  // IANA zone: "Europe/Vienna"
}

interface Appointment {
  title: string;
  start: ScheduledTime;
  end: ScheduledTime;
}

// For date-only values
interface Person {
  name: string;
  dateOfBirth: string;  // ISO 8601 date: "1990-03-15"
}

DateTimePicker Design Principles

A DateTimePicker is a UI component that lets users select a date, time, or both. But "picking a time" isn't as simple as it sounds.

Principle 1: Know What You're Asking For

Before building (or choosing) a picker, decide:

What does the user select?	What do you send to the backend?
Just a date	`PlainDate` → `"2026-06-05"`
Just a time	`PlainTime` → `"10:00"`
Date and time	`PlainDateTime` → `"2026-06-05T10:00"`
Date, time, and timezone	`ZonedDateTime` → `{ local, timeZoneId }`

Most pickers handle the first three. The fourth requires explicit timezone UI.

Principle 2: Timezone Display — When and How

Show the timezone when:

Users in different timezones use the system
The selected timezone might differ from the user's local timezone
The business operates across timezones

Hide the timezone when:

All users are in the same timezone
The context is unambiguous (e.g., "your local time")
Showing it would cause confusion without adding clarity

How to show it:

Display the current timezone near the picker: "Vienna (UTC+2)"
Allow changing it only if the user might need a different zone
Don't default to UTC — default to the user's timezone or the organization's timezone

Principle 3: Handle DST Gaps and Overlaps

When the user picks a time that falls in a DST transition:

Gap (time doesn't exist):

Option A: Prevent selection (disable those times in the picker)
Option B: Accept and adjust (shift forward), but inform the user
Option C: Show a warning and ask the user to choose a different time

Overlap (time exists twice):

Option A: Ask which one they mean (before DST change or after)
Option B: Pick one automatically and note it
Option C: Ignore it (acceptable for many use cases)

The right choice depends on your domain. A medical appointment might need explicit handling; a casual reminder might not.

Principle 4: Don't Lie About What's Stored

If your backend stores local + timeZoneId, your picker should collect exactly that. Don't:

Show a local picker but send UTC (user sees 10:00, backend gets 08:00)
Show UTC but let users think it's local
Convert silently and hope nobody notices

The picker's display should match what gets stored.

Principle 5: Consider the Editing Experience

When users edit an existing time:

Show them what they originally entered (the local time)
Don't show a converted UTC value
If the timezone changed since creation, decide: show original zone or current zone?

Principle 6: Validation Belongs on Both Ends

The frontend picker should:

Prevent obviously invalid dates (February 30th)
Warn about DST issues if relevant
Send well-formed data

The backend should:

Validate the timezone ID is real
Handle DST ambiguities according to business rules
Never trust that the frontend did it right

A Minimal Picker Contract

For a DateTimePicker that collects a scheduled time:

Input (initial value):

interface DateTimePickerValue {
  local: string;       // "2026-06-05T10:00"
  timeZoneId: string;  // "Europe/Vienna"
}

Output (on change):

interface DateTimePickerValue {
  local: string;       // "2026-06-05T14:30"
  timeZoneId: string;  // "Europe/Vienna"
}

The picker:

Displays date and time inputs
Optionally displays or allows changing the timezone
Emits the combined value on change

The parent component:

Receives the structured value
Sends it to the backend as-is
Doesn't do timezone math

Putting It Together: Frontend to Database

Here's the full flow:

1. User picks a time in a DateTimePicker

UI shows: June 5, 2026 at 10:00 AM (Vienna)

2. Frontend sends to API

POST /appointments
{
  "title": "Team Standup",
  "start": {
    "local": "2026-06-05T10:00:00",
    "timeZoneId": "Europe/Vienna"
  }
}

3. Backend (NodaTime) processes

var local = LocalDateTime.FromDateTime(DateTime.Parse(dto.Start.Local));
var zone = DateTimeZoneProviders.Tzdb[dto.Start.TimeZoneId];
var instant = local.InZoneLeniently(zone).ToInstant();

// Store all three
var appointment = new Appointment
{
    LocalStart = local,
    TimeZoneId = dto.Start.TimeZoneId,
    InstantUtc = instant
};

4. Database stores

INSERT INTO appointments (local_start, time_zone_id, instant_utc)
VALUES ('2026-06-05 10:00:00', 'Europe/Vienna', '2026-06-05 08:00:00+00');

5. Later: API returns to frontend

{
  "title": "Team Standup",
  "start": {
    "local": "2026-06-05T10:00:00",
    "timeZoneId": "Europe/Vienna"
  },
  "instantUtc": "2026-06-05T08:00:00Z"
}

6. Frontend displays

To the organizer (Vienna): "June 5 at 10:00 AM"
To a participant in London: "June 5 at 9:00 AM (10:00 AM Vienna)"

Detecting the User's Timezone

We've covered storing and displaying times with timezones. But how do you know what timezone the user is in?

Browser Detection

const userZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
// "Europe/Vienna", "Europe/London", etc.

This returns an IANA timezone ID — exactly what you need.

Caveats

VPNs and proxies may cause the browser to report a different zone than the user expects
Corporate networks sometimes override timezone settings
User preference might differ from their physical location (e.g., someone living in Vienna but working with a London team)

Best Practice

Use browser detection as a default, but let users confirm or change it:

Detect the timezone automatically
Show it clearly in the UI: "Your timezone: Europe/Vienna"
Let users change it if needed
Store their preference (per user, not per session)

Don't silently assume the detected timezone is correct. A user in Vienna might be scheduling a meeting for their London office.

Timezone Is Not a Locale (and Not a Language)

Timezone, language, and locale are often treated as one setting — but they are three independent concerns.

Language (i18n) controls text:
- "Today" vs "Heute" vs "Aujourd'hui"
Locale (l10n) controls formatting:
- 1,000.00 vs 1.000,00
- MM/DD/YYYY vs DD.MM.YYYY
Timezone controls when things happen:
- Europe/Vienna
- America/New_York
- Asia/Tokyo

They often change together — but they are not coupled.

Example

A French-speaking user in New York expects French UI, French date formatting, and New York time. Inferring Europe/Paris from fr is wrong.

DateTimePicker Rule

A DateTimePicker should not assume timezone based on language or locale.

Timezone must come from explicit user choice, browser detection, or application context.

Key Takeaways

Temporal API gives JavaScript proper types: PlainDate, PlainDateTime, ZonedDateTime, Instant
API contracts should be explicit: use ISO strings for instants, structured objects for user intent
DateTimePickers need to know what they're collecting: date, time, datetime, or datetime + zone
Show timezones when they matter, hide them when they'd confuse
Handle DST explicitly — don't let invalid times slip through silently
Don't lie about what's stored — the picker should match the backend model
Validate on both ends — trust but verify

This concludes the series "Time in Software, Done Right." You now have a complete mental model for handling time — from concepts to code, from backend to database to frontend.

The next time someone says "just store it as UTC," you'll know when that's right, and when it's a trap.

PostgreSQL – Storing Time Without Lying to Yourself

bwi — Thu, 22 Jan 2026 22:07:23 +0000

Part 7 of 8 in the series Time in Software, Done Right

You've modeled time correctly in your application. You have LocalDateTime, TimeZoneId, and Instant. Now you need to persist it.

PostgreSQL has excellent time support — but its type names are misleading, and the default behaviors can surprise you. This article explains what PostgreSQL actually does, which types to use, and how to avoid the common traps.

The Two Timestamp Types

PostgreSQL has two timestamp types:

timestamp without time zone (or just timestamp)
timestamp with time zone (or timestamptz)

The names suggest one stores a timezone and one doesn't. That's not quite right.

timestamp without time zone

This stores exactly what you give it — a date and time with no timezone context.

INSERT INTO test (ts) VALUES ('2026-06-05 10:00:00');
SELECT ts FROM test;
-- Result: 2026-06-05 10:00:00

No conversion happens. No timezone is stored. It's just a calendar value.

Use for: LocalDateTime — when you're storing what the user said, not when it happened globally.

timestamp with time zone

This is where the name lies. PostgreSQL does not store a timezone. It converts the input to UTC and stores UTC internally. On retrieval, it converts back to the session's timezone.

SET timezone = 'Europe/Vienna';
INSERT INTO test (tstz) VALUES ('2026-06-05 10:00:00');

SET timezone = 'Europe/London';
SELECT tstz FROM test;
-- Result: 2026-06-05 04:00:00-04

Same row, different display — because PostgreSQL stored UTC internally and converted on output.

Use for: Instant — when you're storing a global moment.

What PostgreSQL Actually Stores

Let's be precise:

Type	What's Stored	What Happens on Insert	What Happens on Select
`timestamp`	Raw datetime	Nothing	Nothing
`timestamptz`	Instant (normalized to UTC)	Converts input to UTC	Converts UTC to session timezone

The critical insight: timestamptz stores UTC, not a timezone. The "with time zone" means "timezone-aware" — it participates in timezone conversions. It doesn't mean "includes a timezone."

The Session Timezone Trap

With timestamptz, PostgreSQL uses your session's timezone for conversions:

SET timezone = 'UTC';
INSERT INTO events (instant_utc) VALUES ('2026-06-05 10:00:00');
-- Stored as: 2026-06-05 10:00:00 UTC

SET timezone = 'Europe/Vienna';
INSERT INTO events (instant_utc) VALUES ('2026-06-05 10:00:00');
-- Stored as: 2026-06-05 08:00:00 UTC (Vienna is UTC+2 in summer)

Same literal, different stored value — because PostgreSQL assumed the input was in the session timezone.

Best practice: Always use explicit UTC or offsets when inserting into timestamptz:

INSERT INTO events (instant_utc) VALUES ('2026-06-05 10:00:00+00');  -- Explicit UTC
INSERT INTO events (instant_utc) VALUES ('2026-06-05 10:00:00Z');    -- Also UTC
INSERT INTO events (instant_utc) VALUES ('2026-06-05 12:00:00+02');  -- Explicit offset

Or set your application's session timezone to UTC and keep it there.

The Recommended Schema

For human-scheduled events (meetings, deadlines, appointments), use the pattern from earlier articles:

CREATE TABLE appointments (
    id              uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    title           text NOT NULL,

    -- Source of truth: what the user chose
    local_start     timestamp NOT NULL,
    time_zone_id    text NOT NULL,

    -- Derived: for global queries and sorting
    instant_utc     timestamptz NOT NULL
);

Why three columns?

local_start — The user said "10:00". That's the intent.
time_zone_id — The user meant "Vienna". That's the context.
instant_utc — For queries like "what's happening now?" and for sorting.

If timezone rules change, you recalculate instant_utc from local_start + time_zone_id.

Choosing the Right Type for Each Concept

Concept	PostgreSQL Type	Example
Instant / UTC moment	`timestamptz`	Log timestamp, `created_at`
Local datetime (user intent)	`timestamp`	Meeting time, deadline
Date only	`date`	Birthday, holiday
Time only	`time`	Opening hours
IANA timezone ID	`text`	`'Europe/Vienna'`

Querying Patterns

Pattern A: "What's on my calendar on June 5th in Vienna?"

Query by local date + timezone:

SELECT *
FROM appointments
WHERE time_zone_id = 'Europe/Vienna'
  AND local_start >= '2026-06-05'
  AND local_start <  '2026-06-06';

This finds all appointments that display as June 5th in Vienna, regardless of the global instant.

Pattern B: "What's happening globally in the next hour?"

Query by instant:

SELECT *
FROM appointments
WHERE instant_utc >= NOW()
  AND instant_utc <  NOW() + INTERVAL '1 hour';

This finds all appointments happening in the next hour, regardless of their local calendars.

Pattern C: "What's happening at 10:00 in any timezone?"

Query by local time (rare but sometimes needed):

SELECT *
FROM appointments
WHERE local_start::time = '10:00:00';

Indexing Strategies

For instant queries (most common)

CREATE INDEX idx_appointments_instant ON appointments (instant_utc);

This covers "what's happening now" and range queries across timezones.

For local calendar queries

CREATE INDEX idx_appointments_local ON appointments (time_zone_id, local_start);

This covers "what's on the calendar for this timezone" queries. The timezone comes first because you'll almost always filter by it.

For both

If you query both ways heavily, create both indexes. The storage cost is usually worth it.

Common Mistakes

Mistake 1: Using timestamptz for user intent

-- DON'T: Storing a meeting time as timestamptz
INSERT INTO meetings (starts_at) VALUES ('2026-06-05 10:00:00');

You've lost the "10:00" intent. If timezone rules change, you can't recover it.

Mistake 2: Using timestamp for log timestamps

-- DON'T: Storing a log timestamp without timezone
INSERT INTO logs (occurred_at) VALUES ('2026-06-05 10:00:00');

Is that UTC? Server time? You don't know. Use timestamptz and be explicit.

Mistake 3: Trusting session timezone

-- DON'T: Assuming session timezone is what you expect
INSERT INTO events (instant_utc) VALUES ('2026-06-05 10:00:00');

What timezone was the session in? Be explicit: '2026-06-05 10:00:00+00'.

Mistake 4: Storing timezone names in timestamptz

-- DON'T: Thinking this stores "Vienna"
INSERT INTO events (instant_utc) VALUES ('2026-06-05 10:00:00 Europe/Vienna');

PostgreSQL converts to UTC immediately. The string 'Europe/Vienna' is gone. If you need the timezone, store it separately.

AT TIME ZONE: The Conversion Operator

PostgreSQL's AT TIME ZONE converts between timestamps and timezones:

-- timestamptz → timestamp in a specific zone
SELECT instant_utc AT TIME ZONE 'Europe/Vienna' AS local_vienna
FROM appointments;

-- timestamp → timestamptz (interpreting as a specific zone)
SELECT local_start AT TIME ZONE time_zone_id AS instant
FROM appointments;

This is useful for display and for reconstructing the instant from stored local + timezone.

Gotcha: The behavior differs based on the input type:

timestamptz AT TIME ZONE 'X' → returns timestamp (strips timezone, shows in X)
timestamp AT TIME ZONE 'X' → returns timestamptz (interprets as X, converts to UTC)

Handling Timezone Rule Changes

When IANA updates timezone rules:

Past events: Nothing to do. PostgreSQL's timestamptz already stores UTC. Historical conversions use historical rules (if your system's tzdata is updated).
Future events: Recalculate instant_utc from local_start + time_zone_id.

-- Recalculate instant_utc for future Vienna appointments
UPDATE appointments
SET instant_utc = local_start AT TIME ZONE time_zone_id
WHERE time_zone_id = 'Europe/Vienna'
  AND instant_utc > NOW();

This is why storing local_start + time_zone_id matters — you have everything needed to recalculate.

Working with EF Core and Npgsql

If you're using .NET with Npgsql, the mapping is straightforward:

// In your DbContext
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
    optionsBuilder.UseNpgsql(connectionString, o => o.UseNodaTime());
}

With UseNodaTime():

Instant ↔ timestamptz
LocalDateTime ↔ timestamp
LocalDate ↔ date
LocalTime ↔ time

The types align naturally with our model.

Full Example: Creating and Querying Appointments

-- gen_random_uuid() requires this extension
CREATE EXTENSION IF NOT EXISTS pgcrypto;

-- Create table
CREATE TABLE appointments (
    id              uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    title           text NOT NULL,
    local_start     timestamp NOT NULL,
    time_zone_id    text NOT NULL,
    instant_utc     timestamptz NOT NULL
);

-- Create indexes
CREATE INDEX idx_appointments_instant ON appointments (instant_utc);
CREATE INDEX idx_appointments_local ON appointments (time_zone_id, local_start);

-- Insert an appointment (10:00 Vienna = 08:00 UTC in summer)
INSERT INTO appointments (title, local_start, time_zone_id, instant_utc)
VALUES (
    'Team Standup',
    '2026-06-05 10:00:00',
    'Europe/Vienna',
    '2026-06-05 10:00:00' AT TIME ZONE 'Europe/Vienna'
);

-- Query: What's on the Vienna calendar for June 5th?
SELECT title, local_start
FROM appointments
WHERE time_zone_id = 'Europe/Vienna'
  AND local_start >= '2026-06-05'
  AND local_start <  '2026-06-06';

-- Query: What's happening globally in the next 2 hours?
SELECT title, instant_utc, time_zone_id
FROM appointments
WHERE instant_utc >= NOW()
  AND instant_utc <  NOW() + INTERVAL '2 hours';

-- Display in viewer's timezone
SELECT 
    title,
    instant_utc AT TIME ZONE 'Europe/London' AS starts_at_london
FROM appointments;

A Note on ORMs, Query Builders, and Event Stores

The PostgreSQL model described here — storing local_start, time_zone_id, and a derived instant_utc — is independent of how you access the database.

EF Core / Npgsql: Works well with explicit mappings (see Article 6 for full NodaTime integration).
Dapper: Maps naturally to simple columns; you compute instants in application code.
Marten / Event Sourcing: Events typically store an Instant (occurred_at) plus domain-specific local values when needed.
Raw SQL: The same rules apply — PostgreSQL doesn't care how the data got there.

The key idea is not the ORM — it's the data model.

If you store human intent (local + timezone) separately from physical moments (instant), the approach works across tools, frameworks, and architectural styles.

Key Takeaways

timestamp stores raw datetime — use for LocalDateTime (user intent)
timestamptz converts to/from UTC — use for Instant (global moments)
timestamptz does not store a timezone — it stores UTC and converts on read
For human-scheduled events: store local_start + time_zone_id + instant_utc
Be explicit with timezones on insert — don't trust session settings
Index instant_utc for global queries, index (time_zone_id, local_start) for calendar queries
When rules change: recalculate instant_utc from the stored local + timezone

Next up: Frontend – Temporal, APIs, and DateTimePickers That Don't Lie — bringing it all together in the browser.

.NET in Practice – Modeling Time with NodaTime

bwi — Thu, 22 Jan 2026 22:05:54 +0000

Part 6 of 8 in the series Time in Software, Done Right

You've made it through the conceptual articles. You understand the difference between instants and local times, between global and local events, between storing intent and storing math.

Now let's make it real in .NET.

The BCL has improved significantly — DateOnly and TimeOnly (since .NET 6) are solid types for dates and times. But for timezone-aware scheduling — meetings, deadlines, appointments that need to survive DST changes — you'll want NodaTime. It gives you the types the BCL is still missing.

This article shows you how to use NodaTime to model time correctly, store it properly, and avoid the traps we've discussed throughout this series.

Why DateTime Falls Short (and What the BCL Fixed)

DateTime in .NET is a single type that tries to represent multiple concepts:

var a = DateTime.Now;           // Local time on this machine
var b = DateTime.UtcNow;        // UTC instant
var c = new DateTime(2026, 6, 5, 10, 0, 0);  // Is this local? UTC? Unspecified?

The problem is the Kind property:

DateTimeKind.Local — local to this machine (not a specific timezone)
DateTimeKind.Utc — a UTC instant
DateTimeKind.Unspecified — could be anything

When you create new DateTime(2026, 6, 5, 10, 0, 0), the Kind is Unspecified. Is that 10:00 in Vienna? 10:00 in London? 10:00 UTC? The type doesn't know, and neither does your code.

The BCL Got Better: DateOnly and TimeOnly

.NET 6 added two types that address part of this problem:

DateOnly birthday = new DateOnly(1990, 3, 15);    // Just a date, no time confusion
TimeOnly openingTime = new TimeOnly(9, 0);         // Just a time, no date confusion

These are great! If you just need a date or just a time, use them. They're in the BCL, well-supported by EF Core, and do exactly what they say.

What the BCL Still Doesn't Have

But for the full picture — especially timezone-aware scheduling — the BCL still falls short:

No Instant type (you use DateTime with Kind.Utc or DateTimeOffset)
No LocalDateTime with proper semantics (you use DateTime with Kind.Unspecified)
No ZonedDateTime that combines local time with a timezone
No first-class IANA timezone support (TimeZoneInfo uses Windows zones by default)

DateTimeOffset is better than DateTime — it includes an offset — but as we discussed in Article 4, an offset is a snapshot, not a meaning. +02:00 could be Vienna in summer, Berlin in summer, Cairo, or Johannesburg. You can't tell.

For simple cases: DateOnly, TimeOnly, DateTime, and DateTimeOffset are fine.

For timezone-aware scheduling: NodaTime gives you the right types for the right concepts.

The NodaTime Types You Need

Here's how NodaTime maps to the concepts we've covered (and their BCL equivalents where they exist):

Concept	NodaTime Type	BCL Equivalent	Example
Physical moment	`Instant`	`DateTime` (UTC) / `DateTimeOffset`	Log timestamp, token expiry
Calendar date	`LocalDate`	`DateOnly` ✓	Birthday, holiday
Wall clock time	`LocalTime`	`TimeOnly` ✓	"Opens at 09:00"
Date + time (no zone)	`LocalDateTime`	`DateTime` (Unspecified)	User's chosen meeting time
IANA timezone	`DateTimeZone`	`TimeZoneInfo` (partial)	`Europe/Vienna`
Full context	`ZonedDateTime`	❌ None	Meeting at 10:00 Vienna
Snapshot with offset	`OffsetDateTime`	`DateTimeOffset`	What the clock showed at a moment

The ✓ marks where the BCL type is a good choice. For DateOnly and TimeOnly, you can often skip NodaTime entirely.

The gap is ZonedDateTime — the combination of a local time and an IANA timezone that lets you handle DST correctly. That's where NodaTime shines.

Let's see each in action.

Instant: For Physical Moments

Use Instant when you're recording when something happened — independent of any human's calendar.

// Current moment
Instant now = SystemClock.Instance.GetCurrentInstant();

// From a Unix timestamp
Instant fromUnix = Instant.FromUnixTimeSeconds(1735689600);

// For logs, audits, event sourcing
public class AuditEntry
{
    public Instant OccurredAt { get; init; }
    public string Action { get; init; }
}

Instant is unambiguous. There's no timezone to confuse, no Kind property to check. It's just a point on the timeline.

LocalDate, LocalTime, LocalDateTime: For Human Concepts

These types represent calendar and clock values without a timezone attached.

// Just a date (NodaTime)
LocalDate birthday = new LocalDate(1990, 3, 15);

// Just a date (BCL - equally good!)
DateOnly birthdayBcl = new DateOnly(1990, 3, 15);

// Just a time (NodaTime)
LocalTime openingTime = new LocalTime(9, 0);

// Just a time (BCL - equally good!)
TimeOnly openingTimeBcl = new TimeOnly(9, 0);

// Date and time together (NodaTime)
LocalDateTime meetingTime = new LocalDateTime(2026, 6, 5, 10, 0);

For dates and times alone, use whichever you prefer — DateOnly/TimeOnly are in the BCL and work great with EF Core.

For date+time combinations that you'll later combine with a timezone, NodaTime's LocalDateTime is clearer because it's part of a coherent type system that includes ZonedDateTime.

A LocalDateTime of 2026-06-05T10:00 means "June 5th at 10:00" — but it doesn't yet specify where. That's intentional. You'll combine it with a timezone to get the full picture.

DateTimeZone: The Ruleset

A DateTimeZone represents an IANA timezone — not just an offset, but the complete ruleset including DST transitions and historical changes.

// Get a timezone by IANA ID
DateTimeZone vienna = DateTimeZoneProviders.Tzdb["Europe/Vienna"];
DateTimeZone london = DateTimeZoneProviders.Tzdb["Europe/London"];

// The provider gives you access to all IANA zones
IDateTimeZoneProvider tzdb = DateTimeZoneProviders.Tzdb;

DateTimeZoneProviders.Tzdb uses the IANA tz database, which is updated regularly with new rules. When you update NodaTime's tzdb data, your code automatically handles new DST rules.

ZonedDateTime: The Full Picture

ZonedDateTime combines a LocalDateTime with a DateTimeZone — giving you everything you need.

LocalDateTime local = new LocalDateTime(2026, 6, 5, 10, 0);
DateTimeZone zone = DateTimeZoneProviders.Tzdb["Europe/Vienna"];

// Combine them
ZonedDateTime zoned = local.InZoneLeniently(zone);

// Now you can get the instant
Instant instant = zoned.ToInstant();

// Or display in different zones
ZonedDateTime inLondon = instant.InZone(DateTimeZoneProviders.Tzdb["Europe/London"]);
Console.WriteLine(inNewYork.ToString("uuuu-MM-dd HH:mm x", CultureInfo.InvariantCulture));
// Output: 2026-06-05 04:00 -04
// (Requires: using System.Globalization;)

Why "Leniently"?

The InZoneLeniently method handles DST edge cases automatically:

If the local time falls in a gap (doesn't exist), it shifts forward
If the local time falls in an overlap (exists twice), it picks the earlier occurrence

For explicit control, NodaTime offers several options:

// Called on LocalDateTime
ZonedDateTime zoned = local.InZoneLeniently(zone);   // Auto-resolve gaps/overlaps
ZonedDateTime zoned = local.InZoneStrictly(zone);    // Throws if ambiguous

// Called on DateTimeZone (same behavior, different syntax)
ZonedDateTime zoned = zone.AtLeniently(local);
ZonedDateTime zoned = zone.AtStrictly(local);

// With custom resolver
ZonedDateTime zoned = local.InZone(zone, Resolvers.LenientResolver);

The Pattern: Store Intent, Derive Instant

Here's the core pattern from Article 4, implemented in NodaTime:

public class Appointment
{
    // Source of truth: what the user chose
    public LocalDateTime LocalStart { get; init; }
    public string TimeZoneId { get; init; }

    // Derived: for queries and sorting
    public Instant InstantUtc { get; private set; }

    public void RecalculateInstant()
    {
        var zone = DateTimeZoneProviders.Tzdb[TimeZoneId];
        var zoned = LocalStart.InZoneLeniently(zone);
        InstantUtc = zoned.ToInstant();
    }
}

When timezone rules change, you call RecalculateInstant() on future appointments. Past appointments stay correct because IANA contains historical rules.

Real-World Examples

Example 1: Logging (Use Instant)

public class LogEntry
{
    public Instant Timestamp { get; init; }
    public string Level { get; init; }
    public string Message { get; init; }

    public static LogEntry Create(string level, string message)
    {
        return new LogEntry
        {
            Timestamp = SystemClock.Instance.GetCurrentInstant(),
            Level = level,
            Message = message
        };
    }
}

Example 2: Birthday (Use LocalDate)

public class Person
{
    public string Name { get; init; }
    public LocalDate DateOfBirth { get; init; }

    public int GetAge(LocalDate today)
    {
        return Period.Between(DateOfBirth, today, PeriodUnits.Years).Years;
    }
}

No timezone needed — birthdays are calendar concepts.

Example 3: Meeting (Use LocalDateTime + TimeZone)

public class Meeting
{
    public string Title { get; init; }
    public LocalDateTime LocalStart { get; init; }
    public string TimeZoneId { get; init; }
    public Instant InstantUtc { get; init; }

    public static Meeting Create(string title, LocalDateTime localStart, string timeZoneId)
    {
        var zone = DateTimeZoneProviders.Tzdb[timeZoneId];
        var instant = localStart.InZoneLeniently(zone).ToInstant();

        return new Meeting
        {
            Title = title,
            LocalStart = localStart,
            TimeZoneId = timeZoneId,
            InstantUtc = instant
        };
    }

    // Display in any timezone
    public string GetDisplayTime(DateTimeZone viewerZone)
    {
        var inViewerZone = InstantUtc.InZone(viewerZone);
        // Note: uuuu is NodaTime's recommended year specifier (absolute year)
        return inViewerZone.ToString("uuuu-MM-dd HH:mm", CultureInfo.InvariantCulture);
    }
}

Example 4: Deadline (Use LocalDateTime + TimeZone)

public class Deadline
{
    public LocalDateTime LocalDeadline { get; init; }
    public string TimeZoneId { get; init; }
    public Instant InstantUtc { get; init; }

    public bool IsPastDeadline(Instant now)
    {
        return now > InstantUtc;
    }

    public Duration TimeRemaining(Instant now)
    {
        return InstantUtc - now;
    }
}

EF Core Integration

NodaTime doesn't map to SQL types out of the box, but there are excellent packages for this.

For PostgreSQL: Npgsql.EntityFrameworkCore.PostgreSQL.NodaTime

// In your DbContext configuration
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
    optionsBuilder.UseNpgsql(connectionString, o => o.UseNodaTime());
}

This maps:

Instant → timestamp with time zone
LocalDateTime → timestamp without time zone
LocalDate → date
LocalTime → time

What about ZonedDateTime? There's no single PostgreSQL type for it — that's the whole point of our pattern. You decompose it into separate columns:

LocalDateTime → timestamp without time zone
TimeZoneId → text
Optionally: Instant → timestamp with time zone (for queries)

Here's how to extract the parts from a ZonedDateTime:

ZonedDateTime zoned = local.InZoneLeniently(zone);

// Decompose for storage
LocalDateTime localPart = zoned.LocalDateTime;
string timeZoneId = zoned.Zone.Id;           // e.g. "Europe/Vienna"
Instant instantPart = zoned.ToInstant();

For SQL Server: Consider Value Converters

public class AppointmentConfiguration : IEntityTypeConfiguration<Appointment>
{
    public void Configure(EntityTypeBuilder<Appointment> builder)
    {
        builder.Property(a => a.LocalStart)
            .HasConversion(
                v => v.ToDateTimeUnspecified(),
                v => LocalDateTime.FromDateTime(v));

        builder.Property(a => a.InstantUtc)
            .HasConversion(
                v => v.ToDateTimeUtc(),
                v => Instant.FromDateTimeUtc(v));

        builder.Property(a => a.TimeZoneId)
            .HasMaxLength(64);
    }
}

Sample Entity

public class Appointment
{
    public Guid Id { get; init; }
    public string Title { get; init; }

    // Stored as timestamp without time zone
    public LocalDateTime LocalStart { get; init; }

    // Stored as text/varchar
    public string TimeZoneId { get; init; }

    // Stored as timestamp with time zone (for queries)
    public Instant InstantUtc { get; init; }
}

Handling DST Transitions

When creating appointments that might fall in DST gaps or overlaps, be explicit:

public class AppointmentService
{
    public ZonedDateTime ResolveLocalTime(LocalDateTime local, string timeZoneId)
    {
        var zone = DateTimeZoneProviders.Tzdb[timeZoneId];
        var mapping = zone.MapLocal(local);

        return mapping.Count switch
        {
            0 => zone.AtLeniently(local),        // Gap: shift forward to valid time
            1 => mapping.Single(),                // Normal: exactly one mapping
            2 => mapping.First(),                 // Overlap: pick earlier occurrence
            _ => throw new InvalidOperationException()
        };
    }
}

For more control (e.g., asking the user to choose during overlaps):

public ZonedDateTime ResolveWithUserChoice(
    LocalDateTime local, 
    string timeZoneId,
    Func<ZonedDateTime, ZonedDateTime, ZonedDateTime> overlapResolver)
{
    var zone = DateTimeZoneProviders.Tzdb[timeZoneId];
    var mapping = zone.MapLocal(local);

    return mapping.Count switch
    {
        0 => zone.AtLeniently(local),
        1 => mapping.Single(),
        2 => overlapResolver(mapping.First(), mapping.Last()),
        _ => throw new InvalidOperationException()
    };
}

Converting from DateTime

If you have existing code using DateTime, here's how to convert:

// DateTime (UTC) to Instant
DateTime dtUtc = DateTime.UtcNow;
Instant instant = Instant.FromDateTimeUtc(dtUtc);

// DateTime (unspecified) to LocalDateTime
DateTime dt = new DateTime(2026, 6, 5, 10, 0, 0);
LocalDateTime local = LocalDateTime.FromDateTime(dt);

// Instant to DateTime (UTC)
DateTime backToUtc = instant.ToDateTimeUtc();

// LocalDateTime to DateTime (unspecified)
DateTime backToUnspecified = local.ToDateTimeUnspecified();

Testing Time-Dependent Code

Code that calls SystemClock.Instance.GetCurrentInstant() directly is hard to test. You can't control "now".

NodaTime solves this with IClock:

// Production: inject the real clock
public class AppointmentService(IClock clock)
{
    public bool IsUpcoming(Appointment appointment)
    {
        var now = clock.GetCurrentInstant();
        return appointment.InstantUtc > now;
    }
}

// In production
var service = new AppointmentService(SystemClock.Instance);

// In tests: use a fake clock
var fakeNow = Instant.FromUtc(2026, 6, 5, 8, 0);
var fakeClock = new FakeClock(fakeNow);
var service = new AppointmentService(fakeClock);

// Now you can test time-dependent logic deterministically

Rule: Never call SystemClock.Instance directly in business logic. Inject IClock instead. Your tests will thank you.

Key Takeaways

Use NodaTime for anything beyond simple logging — it gives you the right types for the right concepts
Instant for physical moments (logs, events, tokens)
LocalDate for calendar dates (birthdays, holidays)
LocalDateTime + DateTimeZone for human-scheduled times (meetings, deadlines)
Store intent: LocalDateTime + TimeZoneId as your source of truth
Derive instant: compute InstantUtc for queries and sorting
Handle DST explicitly: use InZoneLeniently or check MapLocal for edge cases
EF Core: use Npgsql.EntityFrameworkCore.PostgreSQL.NodaTime for PostgreSQL, or value converters for other databases

Next up: PostgreSQL – Storing Time Without Lying to Yourself — the database side of the equation.

Global Events, Local Events, and Recurring Rules

bwi — Thu, 22 Jan 2026 22:03:41 +0000

Part 5 of 8 in the series Time in Software, Done Right

"All stores open at 10:00."

Simple requirement, right? But this sentence hides a massive ambiguity that will determine your entire data model.

Do all stores open at the same moment worldwide (a global event)?

Or does each store open when its local clock shows 10:00 (a local event)?

Same words. Completely different meanings. Completely different storage.

This article will help you spot the difference — and handle the even trickier case of recurring events, where Daylight Saving Time (DST) creates times that don't exist and times that exist twice.

Global Events vs Local Events

Let's make the distinction crystal clear.

Global Event: Same Moment, Different Clocks

A global event happens at one physical instant. Everyone experiences it at the same moment, but their clocks show different times.

Examples:

Product launch: "New iPhone available at 10:00 AM Pacific" — that's 7:00 PM in Vienna
Livestream start: "Keynote begins at 18:00 UTC" — same instant everywhere
Stock market close: The NYSE closes at one moment, regardless of where traders are
Server maintenance window: "Downtime from 02:00-04:00 UTC"

How to store: Instant (UTC). Everyone converts to their local clock for display.

event_type:     global
instant_utc:    2026-06-05T17:00:00Z

When you query "what's happening now?", you compare against the current instant. Done.

Local Event: Same Clock, Different Moments

A local event happens when local clocks show a specific time. The physical moment is different for each timezone.

Examples:

Store opening hours: "All stores open at 10:00" — means 10:00 in London, 10:00 in Vienna, 10:00 in Tokyo
TV broadcast: "News at 8 PM" — 8 PM in your timezone
Daily standup: "Team meeting at 09:00 Vienna time"
Deadline: "Submit by 23:59 in your local timezone"

How to store: local_start + time_zone_id. Each location has its own timezone.

event_type:     local
local_start:    10:00
time_zone_id:   (per location)

When the London store opens at 10:00 AM GMT, the Vienna store is still closed (it's 11:00 AM there). The Vienna store opens when its clock shows 10:00.

The Critical Question

When someone says "all X happen at 10:00", ask:

"Do they all happen at the same moment (global), or do they each happen when local clocks show 10:00 (local)?"

The answer changes everything:

Requirement	Type	Storage
"Product available at 10:00 Pacific"	Global	`Instant`
"Stores open at 10:00"	Local	`LocalTime + TimeZone` per location
"Meeting at 14:00 Vienna"	Local	`LocalDateTime + TimeZone`
"Server restart at 03:00 UTC"	Global	`Instant`

Get this wrong, and your stores either all open at the wrong time, or your "global launch" happens at different moments in different regions.

Recurring Rules: A Different Beast

Recurring events aren't timestamps at all. They're rules that generate timestamps.

"Every Monday at 10:00"
"First Friday of each month"
"Every day at 03:00"
"Yearly on December 25th"

You don't store a list of dates. You store the rule, and compute the occurrences when needed.

recurrence_rule:    FREQ=WEEKLY;BYDAY=MO
local_time:         10:00
time_zone_id:       Europe/Vienna

This rule, combined with the timezone, generates concrete ZonedDateTime instances: Monday June 1st at 10:00 Vienna, Monday June 8th at 10:00 Vienna, and so on.

Why Recurrence Must Be Local

Recurring events are almost always local events.

"Team standup every Monday at 10:00" means 10:00 on the team's wall clock — not a fixed UTC instant that drifts relative to their calendar as DST changes.

If you store a recurring event as "every Monday at 08:00 UTC" (because Vienna is UTC+2 in summer), what happens in winter when Vienna switches to UTC+1? Your 08:00 UTC becomes 09:00 Vienna time. The standup just moved by an hour.

Store the rule in local time. Let the timezone handle DST.

DST Edge Cases: The Hard Part

Here's where recurring rules get interesting. DST creates two nasty edge cases that trip up even experienced teams — if you haven't encountered them yet, you probably will.

Edge Case 1: The Time That Doesn't Exist

In most of Europe, clocks spring forward on the last Sunday of March. At 02:00, clocks jump to 03:00.

The times 02:00, 02:15, 02:30, 02:45 don't exist that day.

What if you have a recurring event at 02:30 every day?

March 28th at 02:30 Vienna — exists normally
March 29th at 02:30 Vienna — doesn't exist (clocks skip from 01:59 to 03:00)
March 30th at 02:30 Vienna — exists normally

What should happen?

Most systems choose one of:

Skip the occurrence (it's in a gap, treat it as if it didn't happen)
Shift forward to 03:00 (the first valid moment after the gap)
Shift backward to 01:59 (the last valid moment before the gap)

NodaTime calls these resolution strategies. There's no universally "correct" answer — it depends on your domain.

A 02:30 AM cron job that does cleanup? Probably shift forward to 03:00.

A 02:30 AM medication reminder? Maybe shift backward — better early than missed.

The point: You need to decide, and your code needs to handle it explicitly.

Edge Case 2: The Time That Exists Twice

In autumn, clocks fall back. In most of Europe, at 03:00 on the last Sunday of October, clocks jump back to 02:00.

The times 02:00 to 02:59 exist twice that day — once before the change, once after.

What if you have a recurring event at 02:30?

October 25th at 02:30 Vienna — exists once
October 26th at 02:30 Vienna — exists twice (once in summer time, once in winter time)
October 27th at 02:30 Vienna — exists once

What should happen?

Options:

Pick the first occurrence (summer time, before clocks change)
Pick the second occurrence (winter time, after clocks change)
Trigger both (if it's a job that should run twice)

Again, domain-dependent. A daily backup at 02:30? Probably run once, pick whichever. A reminder? Probably the first one.

Cron Jobs vs Calendar Events

Cron jobs and calendar events look similar but behave differently with DST.

Cron: Usually System Time (Often UTC)

Traditional cron runs on the system clock. If your server is in UTC, a 0 2 * * * job runs at 02:00 UTC every day — no DST weirdness, but it drifts relative to local calendars.

If your server uses local time, cron will experience DST gaps and overlaps. Most cron implementations:

Skip jobs that fall into a gap
Run once for jobs that fall into an overlap (not twice)

But this varies by implementation. Check your system's documentation.

Calendar Events: User Intent

Calendar events are about user intent. "Remind me at 09:00 every day" means 09:00 on my wall clock, regardless of DST.

If you're building a calendar or reminder system, you need:

Store the rule in local time + timezone
Compute occurrences by applying the rule to the timezone
Handle gaps and overlaps with explicit resolution strategies

Holidays: The Complex Recurrence Rules

Some recurring events don't follow simple patterns:

Easter: First Sunday after the ecclesiastical full moon on or after March 21st (yes, really)
Thanksgiving (US): Fourth Thursday of November
Ramadan: Based on the Islamic lunar calendar — starts on a different Gregorian date each year
Chinese New Year: Based on the lunisolar calendar

For these, you typically need:

A specialized library (like NodaTime's IsoDayOfWeek calculations, or dedicated holiday libraries)
A database of dates (for religious holidays that depend on moon sightings)
Possibly user input ("Ramadan starts on X this year")

Don't try to compute Easter from scratch. Use a library.

Practical Guidance

For One-Time Events

Ask: "Same moment worldwide, or same local time?"

Same moment: Store as Instant (UTC)
Same local time: Store as local_start + time_zone_id

For Recurring Events

Store the rule, not a list of occurrences
Store local time + timezone, not UTC
Decide your DST resolution strategy (skip, shift forward, shift backward)
Document it — future you will thank present you

For Cron Jobs

If possible, run in UTC to avoid DST surprises
If you must use local time, test what happens on DST transition days
Consider whether a skipped or doubled job matters for your use case

Key Takeaways

Global events happen at one instant; store as UTC
Local events happen when local clocks match; store as local time + timezone
Recurring rules generate timestamps; store the rule, not the instances
DST creates gaps (times that don't exist) and overlaps (times that exist twice)
Cron and calendars behave differently with DST — know which you're building
Complex holidays (Easter, Ramadan) need specialized libraries or data
When in doubt, ask: "Same moment, or same clock reading?"

Next up: .NET in Practice – Modeling Time with NodaTime — making all this theory real in code.

Instant vs Local – When UTC Helps and When It Hurts

bwi — Thu, 22 Jan 2026 22:01:57 +0000

Part 4 of 8 in the series Time in Software, Done Right

"Just store everything in UTC."

You've probably heard this advice. It sounds simple, clean, universal. And for some use cases, it's exactly right.

But for others, it's a trap that will corrupt your data in ways you won't notice until it's too late.

This article explains when UTC is the right choice, when it destroys meaning, and what model actually works for human-facing times.

Two Fundamentally Different Questions

When you're storing a time, you need to ask yourself which question you're answering:

Question A: "What physical moment did this happen?"

Question B: "What did the human mean when they said '10:00 in Vienna'?"

These are not the same question. They need different storage strategies.

When UTC Is Perfect

UTC (or Instant) is the right choice when you're recording physical moments — things that happened at a specific point in time, independent of any human's calendar.

Use UTC for:

Log entries — "Request received at 2026-01-21T13:05:12Z"
Audit trails — "User clicked 'Submit' at this instant"
Token expiry — "This token is valid for 3600 seconds from now"
Event sourcing — "This event occurred at this physical moment"
Timestamps for ordering — "Did A happen before or after B?"
Durations and intervals — "How long did this take?"

In all these cases, you don't care about calendars, timezones, or what the clock on someone's wall showed. You care about the moment itself.

UTC is perfect for this. It's unambiguous, comparable, and never changes.

When UTC Destroys Meaning

UTC is the wrong choice when you're storing human intent — times that exist because a person chose them, in a specific calendar context.

Don't use UTC alone for:

Meetings — "Team standup at 10:00 Vienna time"
Appointments — "Doctor's appointment at 14:30"
Deadlines — "Submit by June 5th, 23:59 Vienna"
Opening hours — "Store opens at 09:00"
Recurring events — "Every Monday at 10:00"
Birthdays and anniversaries — "Party on March 15th at 19:00"

Why? Because these times have meaning beyond the instant.

This isn't obvious at first — many systems start this way and run into problems later.

The Problem with "Just Convert to UTC"

Let's say a user in Vienna schedules a meeting for June 5th at 10:00.

If you convert immediately to UTC and store only that:

stored: 2026-06-05T08:00:00Z

You've lost information. You no longer know:

That the user meant "10:00 in Vienna"
That Vienna was in CEST (Central European Summer Time) at that moment
What should happen if timezone rules change

Now imagine: the EU abolishes Daylight Saving Time in 2027. Vienna stays on permanent standard time (UTC+1 instead of UTC+2 in summer).

Your stored UTC value 08:00Z now displays as 09:00 Vienna time — not 10:00!

The user said "10:00". The meeting should still be at 10:00. But you stored the math, not the meaning.

Why Offsets Don't Help

"But I stored 2026-06-05T10:00:00+02:00 — that includes the offset!"

Yes, but an offset is a snapshot, not a meaning.

+02:00 could be:

Vienna in summer
Berlin in summer
Cairo
Johannesburg
Kaliningrad

You can't tell which one. And more importantly: if the rules change, you can't recalculate.

An offset tells you what the clock showed at the moment of storage. It doesn't tell you what the user meant, or what the correct time should be in the future.

The Correct Model: Store Intent, Derive Math

Here's the model that actually works:

Source of truth:    local + timeZoneId
Derived value:      instantUtc

For a meeting at 10:00 Vienna:

local:        2026-06-05T10:00
timeZoneId:   Europe/Vienna
instantUtc:   2026-06-05T08:00:00Z  (derived)

What you store as truth:

The local datetime the user chose (10:00)
The IANA timezone (Europe/Vienna)

What you derive for queries:

The UTC instant (computed from local + zone)

Why IANA Timezones Matter

An IANA timezone like Europe/Vienna is not just an offset. It's a ruleset:

Historical offsets (what was the offset in 1980?)
Current offset
DST transitions (when does the clock change?)
Future rules (as currently known)
Political changes (when a country changes its timezone policy)

When you store Europe/Vienna, you're saying: "Apply whatever rules Vienna has — past, present, or future."

This is why the model survives rule changes.

What Happens When Rules Change

Timezone rules change more often than you'd think:

Russia abolished DST in 2011
Mexico abolished DST in 2022
EU has been discussing abolishing DST for years
Morocco changes its offset for Ramadan every year
Egypt — the chaos champion: introduced DST in 1940, suspended it in 2011, reintroduced it in 2014, suspended it during Ramadan that same year, abolished it in 2015, restored it in 2023

With the correct model:

For past events:

The IANA database contains historical rules
Your instantUtc was correct at the time and stays correct
Recalculating gives the same result (safe, idempotent)

For future events:

When rules change, you recalculate instantUtc
The human intent (10:00 Vienna) stays the same
The physical moment shifts to match the new rules

When Do You Actually Recalculate?

So instantUtc "can always be recalculated" — but when does that actually happen?

Trigger: Your IANA timezone database gets updated.

The IANA maintains the tz database, which gets updated several times a year. When a country announces a DST change or offset shift, the database is updated, and eventually that update reaches your system:

Your OS ships a tzdata update
NodaTime releases a new tzdb version
Your runtime (JVM, .NET, Node) updates its bundled data

What to do when this happens:

Past events: Nothing. Recalculating them is safe — the result will be identical because historical rules don't change.
Future events: Recalculate instantUtc for any event whose timezone was affected.

How to implement this:

Batch job: When you update your tz data, run a migration that recalculates instantUtc for future events in affected zones.
Lazy recalculation: Recompute instantUtc on read, and store the tz database version used. If it's stale, recalculate.
Hybrid: Batch for known changes, lazy as a safety net.

Most applications can get away with a simple batch job that runs after tz updates. If you're caching instantUtc in a search index or external system, remember to update those too.

The good news: this is rare (a few times a year, usually affecting only a handful of zones), and if you've stored local + timeZoneId, you have everything you need to recalculate correctly.

The Two Query Patterns

This model supports both ways of querying time:

Pattern A: "What's on my calendar on June 5th in Vienna?"

Query by local datetime + timezone:

WHERE time_zone_id = 'Europe/Vienna'
  AND local_start >= '2026-06-05'
  AND local_start <  '2026-06-06'

This finds everything on that calendar day, regardless of the global instant.

Pattern B: "What's happening globally at this moment?"

Query by instant:

WHERE instant_utc = '2026-06-05T08:00:00Z'

This finds everything happening at that physical moment, regardless of local calendars.

Both queries are valid. Both are useful. The model supports both.

How Many Columns Do You Actually Need?

Not every time field needs the same treatment. It depends on what you're storing:

Instant-only fields (logs, audits, occurredAt):
→ 1 column — timestamp with time zone or Instant

Date-only fields (birthday, holiday):
→ 1 column — date or LocalDate

Human-scheduled time (appointment, meeting, deadline):
→ 2 columns minimum:

local_start (timestamp without time zone)
time_zone_id (text — IANA zone)

Optional 3rd column: instant_utc as a cached/derived value — only if you need efficient global queries.

A Practical Example

For one human-facing timestamp (like an appointment start), the robust representation is:

-- Example using PostgreSQL types (concepts apply to any database)
local_start    timestamp without time zone NOT NULL,
time_zone_id   text NOT NULL,  -- IANA zone, e.g. 'Europe/Vienna'

-- Optional: cached for fast global queries/sorting
instant_utc    timestamp with time zone

The exact types vary by database (datetime in SQL Server, DATETIME in MySQL, etc.), but the pattern is the same: local datetime + timezone ID + optional UTC instant.

When do you need instant_utc?

Indexing and range queries across timezones
Sorting events globally
"What's happening right now?" queries
Avoiding recalculation in hot paths

If you never query globally, you can skip it and compute on read.

In practice, many teams wrap these two (or three) values into:

An app-level value object (ZonedDateTime, a custom DTO)
A composite database type
A domain type with constraints

The logical model stays the same — you're just packaging it.

The Mantra

Store intent, not math.

local + timeZoneId = what the human meant
instantUtc = what the computer needs for calculations

The human intent is the source of truth. The UTC instant is derived, cached, and can always be recalculated.

If you store only UTC, you've thrown away the intent. You can never get it back.

Key Takeaways

UTC is perfect for physical moments (logs, audits, tokens)
UTC alone is wrong for human intent (meetings, deadlines, appointments)
Offsets are snapshots, not meaning — they can't survive rule changes
The correct model: local + IANA timezone as truth, UTC instant as derived
IANA timezones contain rules, not just offsets — they handle past and future
When rules change: past events stay correct, future events get recalculated
Store intent, not math

Next up: Global Events, Local Events, and Recurring Rules — when "everyone at 10:00" means completely different things.

Deadlines Are Hard – Why "Submit by June 5th" Is Broken

bwi — Thu, 22 Jan 2026 21:57:19 +0000

Part 3 of 8 in the series Time in Software, Done Right

"Submit by June 5th."

Sounds clear, right? Everyone knows what June 5th means.

Except... they don't. And if you build a system around this requirement, you're setting up your users to fail.

This article is about deadline fairness — and why most deadline definitions are technically broken.

The Problem in One Sentence

If a deadline is defined in a way that users cannot objectively act correctly, the problem is not the user — it's the deadline.

A user shouldn't need to guess what timezone the server is in. They shouldn't need to submit "just to be safe" hours before they think the deadline is. They shouldn't lose because of ambiguity they can't control.

What's Missing from "June 5th"?

When someone says "the deadline is June 5th", what do they actually mean?

June 5th at 00:00? (start of day)
June 5th at 23:59? (end of day)
June 5th at 17:00? (end of business hours)
Some other time?

And more importantly: in which timezone?

The user's timezone?
The server's timezone?
The organization's timezone?
UTC?

"June 5th" contains none of this information. It's a Local Date — and as we established in Article 1, a Local Date is not a moment.

The Three Timezones in Every Deadline

When a deadline involves a user and a server, there are (at least) three timezones in play:

1. User Time

Where the user physically is. A user in Sydney sees their clock, their calendar, their "June 5th".

2. Server Time

Where the server runs. AWS us-east-1, Azure westeurope, a data center somewhere. The server has its own clock.

3. Organization Time

The business context. A company headquartered in Vienna might define all deadlines in Europe/Vienna, regardless of where users or servers are.

When someone says "June 5th", which of these three do they mean?

Usually: nobody knows. And that's the problem.

A Real Scenario

Let's trace through what happens with an ambiguous deadline:

Business requirement: "Users must submit by June 5th"
Developer interprets: "End of day UTC" → stores 2026-06-05T23:59:59Z
Frontend displays: "Due: June 5th" (no time, no timezone shown)
User in New York: Sees "June 5th", submits at 11:00 PM on June 5th local time
Server receives: The request at 2026-06-06T03:00:00Z (New York is UTC-4 in June)
Result: Rejected — the UTC deadline has already passed

The user submitted on June 5th in their timezone. They did everything right from their perspective. But they failed because "June 5th" meant something different to the server.

Now imagine this is:

A tax filing
A university application
A legal submission
A grant proposal

The stakes are real. The ambiguity is unacceptable.

"End of Day" Doesn't Help

Sometimes people try to fix this by saying "end of day June 5th" or "by end of business June 5th".

This doesn't solve anything:

End of day — whose day? What time? 23:59? 23:59:59? 23:59:59.999?
End of business — whose business? What timezone? What if it's a holiday?

You've just replaced one ambiguity with another.

The Only Fix: Be Explicit

A technically correct deadline has three components:

Date — June 5th
Time — 23:59 (or 17:00, or whatever makes sense)
Timezone — Europe/Vienna (or the user's timezone, explicitly stated)

Example of a clear deadline:

"Submit by June 5th, 2026 at 23:59 Europe/Vienna"

Now there's no ambiguity. Users in any timezone can convert this to their local time. The system can enforce it precisely. Everyone knows exactly when the deadline is.

But What If We Want User-Local Deadlines?

Sometimes the business intent really is: "Each user has until the end of June 5th in their own timezone."

That's a valid requirement! But it's a different requirement — and it needs different handling:

Capture the user's timezone (or let them choose)
Store the deadline as: Local Date + User's Timezone
Evaluate per user: Convert their timezone's "end of June 5th" to an Instant, compare to now

This is more complex, but it's honest. You're explicitly saying "the deadline is local to each user" rather than pretending a global deadline is local.

What Systems Must Enforce

If you're building a system that handles deadlines, here's what you need:

At Definition Time (when creating the deadline)

Require a time, not just a date
Require a timezone (or default to a clearly documented one)
Reject incomplete definitions — don't guess

At Display Time (when showing the deadline)

Show the full datetime with timezone at least once
Optionally show converted to user's local time ("June 5th 23:59 Vienna = June 6th 07:59 your time")

At Evaluation Time (when checking if deadline passed)

Convert everything to Instant (UTC) for comparison
Use the stored timezone, not the server's timezone
Log the exact Instant of submission for disputes

When Developers Must Push Back

Sometimes you receive a requirement like "deadline is June 5th" and you know it's incomplete.

Push back. Ask:

"What time on June 5th?"
"In which timezone?"
"Should users in other timezones get the same absolute deadline, or the same local experience?"

If the business can't answer these questions, the deadline isn't defined yet — and you shouldn't build it.

Implementing an ambiguous deadline doesn't make you fast. It makes you responsible for the bugs.

The Fairness Test

Here's a simple test for any deadline in your system:

Can a user, acting in good faith, always determine whether they've met the deadline?

If the answer is "no" — if a user could submit on what they believe is the correct day and still fail because of timezone confusion — the deadline is broken.

Fix the definition, not the user's expectations.

Key Takeaways

"June 5th" is not a deadline — it's an incomplete specification
Every deadline needs: date + time + timezone
There are (at least) three timezones in play: user, server, organization
"End of day" and "end of business" are just as ambiguous as bare dates
User-local deadlines are valid but need explicit handling
If users can't determine whether they've met the deadline, the deadline is broken — not the user

Next up: Instant vs Local — When UTC Helps and When It Hurts — the core model for storing time correctly.

Forem: bwi

The Role of a Software Architect – And Why It Often Can't Be Fulfilled

Architecture Is Not Implementation with More Experience

The Structural Tension: Responsibility Here, Decisions Everywhere

A Practical Example

Architecture Needs Focus and Feedback

How to Recognize That Architecture Doesn't Truly Exist

Conclusion

Die Aufgabe eines Softwarearchitekten – und warum sie oft nicht stattfinden kann

Die Aufgabe eines Softwarearchitekten – und warum sie oft nicht stattfinden kann

Architektur ist keine Implementierung mit mehr Erfahrung

Das strukturelle Spannungsfeld: Verantwortung hier, Entscheidungen überall

Ein Beispiel aus der Praxis

Architektur braucht Fokus und Feedback

Woran du erkennst, dass Architektur nicht wirklich existiert

Fazit

Showing a Date Needs Three Decisions

Why showing a date always involves three implicit decisions

The core insight

1. Format — structure

2. Language — words

3. Region / cultural conventions — expectations

These three parameters always exist

Language + region as locale tags (IETF BCP 47)

Defaults are not decisions

Example 1: dd. MMMM yyyy

Example 2: German is not just German

Example 3: English is not a culture

These parameters can come from different sources

Even the format is a decision

The common mistake

The key takeaway

What to do

In the browser: Intl.DateTimeFormat

Format: dateStyle

Language + Region: the locale tag

What happens when we leave things out?

The API already supports this

Conclusion

Configuration Needs Semantics

Everything Could Be Configuration

Why This Works Technically — and Fails Mentally

Semantics Through Explicit Categories

Configuration

Secrets

Feature Flags

Entitlements

Same Mechanism, Different Meaning

Maintenance, Planning, and Self-Deception

Warnings as Support, Not Enforcement

Conclusion

Indeterminate Is Not a Value

Indeterminate Is Not a Value

Part 1: Indeterminate Is Display-Only

What Indeterminate Looks Like

What the Specification Actually Says

You Cannot Set It in HTML

What Happens When the User Clicks?

Part 2: Two Completely Different Reasons for Indeterminate

Reason A: Mixed (Aggregation)

Reason B: Unset (Unknown/Never Answered)

The Problem: Same Visual, Different Meaning

Part 3: The Value Question

Answer

For Mixed (Parent Checkbox)

For Unset (Unknown)

Part 4: The Participation Pattern

The Pattern: Checkbox + Value Control

Why This Is Better Than Tri-State

Part 5: When to Use What

Use a Simple Checkbox When:

Use Parent/Child Checkboxes When:

Use the Participation Pattern When:

Use Radio Buttons When:

Use a Select/Dropdown When:

Part 6: Practical Rules

1. Indeterminate Is Display-Only

2. Mixed Should Be Computed

3. Separate "Unknown" from "Mixed"

4. When In Doubt, Add a Control

Example 1: `dd. MMMM yyyy`

In the browser: `Intl.DateTimeFormat`

Format: `dateStyle`

Two Separate Roles: `checked` vs. `value`

A Checkbox Without `name`

The `checked` Property

Where `null` and `undefined` Come From