How ringsaturn/tzf works
Project type and purpose
• This is a Go library (“TZF”) plus accompanying CLI tools that implements a high-performance geospatial timezone lookup.
• It also includes a data-processing pipeline (GeoJSON → Protobuf → Reduced/Compressed/Preindexed formats) to generate the binary data the library consumes.
File structure
• Top-level components:
• cmd/… : command-line utilities (geojson2tzpb, reducetzpb, compresstzpb, preindextzpb, and the tzf CLI)
• convert/, preindex/, reduce/ : support libraries for data transformation
• pb/ : Protobuf schemas and generated code under gen/go/tzf/v1
• internal/maps : internal map-data utilities
• tzf.go and supporting files (tzf_fuzzy.go, tzf_default_finder.go) : core library API
• python/ : Python binding instructions
• Configuration/build: go.mod, Makefile, buf.yaml, GitHub workflows
• Third-party deps under THIRD_PARTY_LICENSES
Readme insights
• Describes two main runtime components:
a. Finder (polygon-based)
b. FuzzyFinder (tile-based)
• DefaultFinder combines both for fast, mostly accurate lookups
Main components
a. Data Pipeline (offline preprocessing)
• Raw GeoJSON (timezone-boundary-builder)
• Full Protobuf data (cmd/geojson2tzpb → pb/tzinfo.proto)
• Lite data (cmd/reducetzpb)
• Compressed data (cmd/compresstzpb)
• Preindexed tiles (cmd/preindextzpb)
b. Core Library (runtime)
• Finder (polygon) ← NewFinderFromPB
• FuzzyFinder (tile + RTree) ← NewFuzzyFinderFromPB
• DefaultFinder ← combine Finder + FuzzyFinder
• Internal modules: maps, geojson ray-casting, RTree filter
c. CLI Interface
• cmd/tzf: wraps DefaultFinder for stdin or flags
d. External dependencies
• Protobuf (google.golang.org/protobuf)
• Geometry libs (paulmach/orb, tidwall/geojson, tidwall/rtree)
Relationships and interactions
• Offline: GeoJSON → Protobuf → Lite/Compressed/Preindex
• At init: user calls NewDefaultFinder() → loads Preindex + Compressed or Full data via protobuf → builds in-memory indices
• Query path: user code or tzf CLI → DefaultFinder.GetTimezoneName() →
1) FuzzyFinder (tile lookup + RTree)
2) if miss, CompressedFinder → precise polygon ray-cast
• Reuse global Finder instance to avoid repeat init overhead
Architectural patterns and design principles
• Pipeline pattern for data transformation commands
• Separation of concerns: data generation vs. runtime lookup
• Builder/factory functions for constructing different Finder types
• Composite pattern in DefaultFinder combining two finders
• Use of spatial indices (RTree, pre-indexing) to optimize average-case performance
Technologies/frameworks/libraries to call out
• Go modules and Protobuf for code gen (buf, pb/tzinfo.proto)
• RTree spatial index (tidwall/rtree)
• Polyline compression (go-polyline)