How mhshajib/chronz works
1. Repository shape
- This is a Go library, not an application.
- The root module github.com/mhshajib/chronz contains the core timezone logic.
- Two adapter packages extend it for specific persistence layers: chronz_gorm and chronz_mongo.
- examples/ contains two self-contained demo modules, each with its own go.mod and Docker Compose setup.
2. Core subsystem: chronz
- The root package is the central boundary for timezone awareness.
- Its job is to read timezone intent from context.Context, then convert timestamps consistently between local time and UTC.
- The README shows two ways to express timezone in context: an explicit IANA timezone name or a country_id that maps to a region.
- A default timezone can also be configured globally, which acts as a fallback when context does not carry one.
3. Context propagation model
- ctx.go likely defines the context keys and helper functions such as WithTZName, WithCountryID, and accessors like TZNameFromCtx.
- This is the main control plane for the library: every adapter depends on context to decide how timestamps should be interpreted.
- The design makes timezone behavior request-scoped rather than global, while still allowing a default fallback.
4. Parsing and conversion pipeline
- parse.go appears to handle turning user-provided values into time values, including string parsing and layout handling.
- convert.go likely performs the actual UTC/local transformations.
- The core data flow is:
- inbound application time + context timezone → normalize to UTC for storage
- UTC read from storage + context timezone → convert to local time for display/use
- This is the central invariant of the repository: storage stays UTC, presentation is localized.
5. GORM/Postgres adapter: chronz_gorm
- This package integrates the core logic with GORM’s serializer and query argument handling.
- serializer.go likely provides the custom TZTimeSerializer used with schema.RegisterSerializer("tztime", ...).
- args.go likely handles query parameters so date/time filters can be normalized before hitting SQL.
- The adapter is narrow: it does not own timezone policy, it just translates GORM field/query behavior into the core conversion routines.
6. How GORM data flows
- On write: application code uses a context containing timezone, then GORM serializes timestamps into UTC before inserting/updating Postgres.
- On read: database UTC values are deserialized and converted back into the caller’s timezone.
- For query predicates, helper functions format or normalize incoming time values so SQL comparisons match the stored UTC representation.
- This makes the adapter important at both persistence and query boundaries.
7. MongoDB adapter: chronz_mongo
- This package provides two integration styles: a collection wrapper and hook-based interception.
- wrap.go likely exposes a TZCollection-style wrapper that intercepts Mongo operations explicitly.
- pipeline.go likely contains logic used by hooks or wrapped collection methods to transform documents or query results.
- Compared with GORM, the Mongo adapter is more operationally flexible because it can be enabled globally or applied per collection.
8. How Mongo data flows
- Insert/update paths convert time fields from the caller’s local timezone to UTC before documents are stored.
- Read paths convert UTC timestamps back to the timezone derived from context.
- Hook mode pushes this behavior into the driver/client layer, while wrapper mode keeps the change local to the collection instance.
- The architectural boundary here is the Mongo driver client/collection, with Chronz sitting between app code and the database.
9. Integration patterns outside the repo
- The README describes HTTP middleware and gRPC interceptors, but those are shown as integration patterns rather than first-class packages in this tree.
- The intended architecture is that upstream transport layers extract timezone identifiers from headers/metadata and place them into context.
- Downstream storage adapters then consume the same context to keep conversion behavior consistent end to end.
10. Examples as executable architecture documentation
- examples/gorm_postgres demonstrates GORM serializer registration, context setup, and Postgres interaction.
- examples/mongo demonstrates context-driven inserts and reads against MongoDB.
- Each example is isolated as its own module, which keeps dependency setups separate from the root library.
- The Docker Compose files show that the examples expect backing databases as external services.
11. Important architectural boundary
- Chronz does not appear to manage persistence itself, nor does it own transport concerns like HTTP or gRPC.
- Its responsibility is strictly timezone normalization and conversion, with adapters translating that behavior into database-specific integration points.
- That separation is the main diagram to capture: request context → core timezone logic → storage adapter → database, and back again on reads.
12. Repository-level tooling and packaging
- go.mod at the root defines the library module; the examples each have their own modules.
- There are no build pipelines or deployment manifests beyond the example Docker Compose files.
- The project is therefore best understood as a reusable Go SDK with database adapters and runnable demos, rather than a standalone service.
Main entry points: convert.go Convert · parse.go Parse · gorm_postgres/main.go GORM demo · mongo/main.go Mongo demo
Components 12
Core library
Root timezone context and conversion logic.
- chronz · Root boundary for request-scoped timezone normalization and conversion.
- Context · Stores and reads timezone intent from context.Context.
ctx.go - Parse · Turns user-provided values into time values using layouts and input formats.
parse.go - Convert · Converts between local time and UTC for storage and presentation.
convert.go
GORM adapter
Serializer and query-argument integration for GORM.
- GORM · Bridges Chronz into GORM serialization and query handling.
- Serializer · Custom serializer for persisting and loading timezone-aware time fields.
chronz_gorm/serializer.go - Query args · Normalizes time arguments used in SQL filters and comparisons.
chronz_gorm/args.go
Mongo adapter
Wrapper and pipeline integration for MongoDB.
Examples
Standalone demo modules showing end-to-end usage.
- GORM demo · Standalone Postgres example module for serializer registration and context-driven storage.
examples/gorm_postgres/main.go - Mongo demo · Standalone MongoDB example module for context-driven inserts and reads.
examples/mongo/main.go
Connections 17
- chronz → Context: timezone intent · Context carries IANA names or country-based timezone hints.
- chronz → Parse: parse input · Parses user-provided temporal values before normalization.
- chronz → Convert: normalize · Converts values between local time and UTC.
- Context → Convert: resolve zone · Resolved timezone selection feeds conversion behavior.
- Parse → Convert: parsed time · Parsed time values are normalized through the conversion layer.
- GORM → Serializer: field I/O · Serializer applies Chronz logic on model fields.
- GORM → Query args: query I/O · Query helpers normalize filter values before SQL execution.
- Serializer → Convert: store/read · Serializes writes to UTC and deserializes reads to local time.
- Query args → Parse: normalize filters · Parses and normalizes query inputs before comparison.
- Mongo → Wrapper: collection mode · Wrapper applies conversion around collection operations.
- Mongo → Pipeline: hook mode · Shared transformation logic used by hooks and interception.
- Wrapper → Convert: write/read · Converts documents on insert, update, and read paths.
- Pipeline → Convert: transform · Applies timezone conversion to pipeline-managed documents.
- GORM demo → GORM: uses · Example shows GORM integration against Postgres.
- GORM demo → chronz: sets context · Example seeds timezone intent into request context.
- Mongo demo → Mongo: uses · Example shows Mongo integration through wrapper or hooks.
- Mongo demo → chronz: sets context · Example seeds timezone intent into request context.