# mhshajib/chronz architecture

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

- Interactive diagram: https://gitdiagram.com/mhshajib/chronz
- Repository: https://github.com/mhshajib/chronz

## Overview

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`](https://github.com/mhshajib/chronz/blob/main/convert.go) (Convert), [`parse.go`](https://github.com/mhshajib/chronz/blob/main/parse.go) (Parse), [`examples/gorm_postgres/main.go`](https://github.com/mhshajib/chronz/blob/main/examples/gorm_postgres/main.go) (GORM demo), [`examples/mongo/main.go`](https://github.com/mhshajib/chronz/blob/main/examples/mongo/main.go) (Mongo demo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_chronz["chronz<br/>timezone library"]
  node_ctx["Context<br/>[ctx.go]"]
  node_parse["Parse<br/>time parsing<br/>[parse.go]"]
  node_convert["Convert<br/>time conversion<br/>[convert.go]"]
end

subgraph group_gorm["GORM adapter"]
  node_gorm_adapt["GORM"]
  node_serializer["Serializer<br/>[serializer.go]"]
  node_args["Query args<br/>gorm predicates<br/>[args.go]"]
end

subgraph group_mongo["Mongo adapter"]
  node_mongo_adapt["Mongo"]
  node_wrap["Wrapper<br/>[wrap.go]"]
  node_pipeline["Pipeline<br/>mongo hooks<br/>[pipeline.go]"]
end

subgraph group_examples["Examples"]
  node_gorm_demo["GORM demo<br/>example module<br/>[main.go]"]
  node_mongo_demo["Mongo demo<br/>example module<br/>[main.go]"]
end

node_chronz -->|"timezone intent"| node_ctx
node_chronz -->|"parse input"| node_parse
node_chronz -->|"normalize"| node_convert
node_ctx -->|"resolve zone"| node_convert
node_parse -->|"parsed time"| node_convert
node_gorm_adapt -->|"field I/O"| node_serializer
node_gorm_adapt -->|"query I/O"| node_args
node_serializer -->|"store/read"| node_convert
node_args -->|"normalize filters"| node_parse
node_mongo_adapt -->|"collection mode"| node_wrap
node_mongo_adapt -->|"hook mode"| node_pipeline
node_wrap -->|"write/read"| node_convert
node_pipeline -->|"transform"| node_convert
node_gorm_demo -->|"uses"| node_gorm_adapt
node_gorm_demo -->|"sets context"| node_chronz
node_mongo_demo -->|"uses"| node_mongo_adapt
node_mongo_demo -->|"sets context"| node_chronz

click node_ctx "https://github.com/mhshajib/chronz/blob/main/ctx.go"
click node_parse "https://github.com/mhshajib/chronz/blob/main/parse.go"
click node_convert "https://github.com/mhshajib/chronz/blob/main/convert.go"
click node_serializer "https://github.com/mhshajib/chronz/blob/main/chronz_gorm/serializer.go"
click node_args "https://github.com/mhshajib/chronz/blob/main/chronz_gorm/args.go"
click node_wrap "https://github.com/mhshajib/chronz/blob/main/chronz_mongo/wrap.go"
click node_pipeline "https://github.com/mhshajib/chronz/blob/main/chronz_mongo/pipeline.go"
click node_gorm_demo "https://github.com/mhshajib/chronz/blob/main/examples/gorm_postgres/main.go"
click node_mongo_demo "https://github.com/mhshajib/chronz/blob/main/examples/mongo/main.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_chronz,node_ctx,node_parse,node_convert toneBlue
class node_gorm_adapt,node_serializer,node_args toneAmber
class node_mongo_adapt,node_wrap,node_pipeline toneMint
class node_gorm_demo,node_mongo_demo toneRose
```

## Components

### Core library

Root timezone context and conversion logic.

- **chronz**: timezone library · Root boundary for request-scoped timezone normalization and conversion.
- [Context](https://github.com/mhshajib/chronz/blob/main/ctx.go): context helpers · Stores and reads timezone intent from context.Context. · `ctx.go`
- [Parse](https://github.com/mhshajib/chronz/blob/main/parse.go): time parsing · Turns user-provided values into time values using layouts and input formats. · `parse.go`
- [Convert](https://github.com/mhshajib/chronz/blob/main/convert.go): time conversion · Converts between local time and UTC for storage and presentation. · `convert.go`

### GORM adapter

Serializer and query-argument integration for GORM.

- **GORM**: gorm adapter · Bridges Chronz into GORM serialization and query handling.
- [Serializer](https://github.com/mhshajib/chronz/blob/main/chronz_gorm/serializer.go): gorm serializer · Custom serializer for persisting and loading timezone-aware time fields. · `chronz_gorm/serializer.go`
- [Query args](https://github.com/mhshajib/chronz/blob/main/chronz_gorm/args.go): gorm predicates · Normalizes time arguments used in SQL filters and comparisons. · `chronz_gorm/args.go`

### Mongo adapter

Wrapper and pipeline integration for MongoDB.

- **Mongo**: mongo adapter · Bridges Chronz into MongoDB collection and hook workflows.
- [Wrapper](https://github.com/mhshajib/chronz/blob/main/chronz_mongo/wrap.go): collection wrapper · Intercepts collection operations to apply timezone conversion locally. · `chronz_mongo/wrap.go`
- [Pipeline](https://github.com/mhshajib/chronz/blob/main/chronz_mongo/pipeline.go): mongo hooks · Shared document and result transformation logic used by hook-based integration. · `chronz_mongo/pipeline.go`

### Examples

Standalone demo modules showing end-to-end usage.

- [GORM demo](https://github.com/mhshajib/chronz/blob/main/examples/gorm_postgres/main.go): example module · Standalone Postgres example module for serializer registration and context-driven storage. · `examples/gorm_postgres/main.go`
- [Mongo demo](https://github.com/mhshajib/chronz/blob/main/examples/mongo/main.go): example module · Standalone MongoDB example module for context-driven inserts and reads. · `examples/mongo/main.go`

## Connections

- 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.
