# ringsaturn/tzf architecture

> Architecture diagram of the GitHub repository ringsaturn/tzf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ringsaturn/tzf
- Repository: https://github.com/ringsaturn/tzf

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Pipeline
    subgraph "Data Pipeline"
        direction TB
        RawGeoJSON["Raw GeoJSON"]:::pipeline
        GeoJSON2PB["geojson2tzpb"]:::pipeline
        FullPB["Full PB Data"]:::pipeline
        LiteData["Lite Data"]:::pipeline
        CompressData["Compressed Data"]:::pipeline
        PreindexTiles["Preindex Tiles"]:::pipeline

        RawGeoJSON --> GeoJSON2PB --> FullPB --> LiteData
        LiteData --> CompressData
        LiteData --> PreindexTiles

        %% Utility libraries
        subgraph "Conversion Utilities"
            direction TB
            ConvUtils["convert.go"]:::pipeline
            PB2Geo["pb2geometry.go"]:::pipeline
            Revert["revert.go"]:::pipeline
            ConvUtils --> GeoJSON2PB
            PB2Geo --> GeoJSON2PB
            Revert --> GeoJSON2PB
        end

        subgraph "Reduction Library"
            direction TB
            ReduceLib["reduce.go"]:::pipeline
            CompressLib["compress.go"]:::pipeline
            ReduceLib --> LiteData
            CompressLib --> CompressData
        end

        subgraph "Preindex Library"
            direction TB
            PreindexLib["preindex.go"]:::pipeline
            ExcludeLogic["exclude.go"]:::pipeline
            PreindexLib --> PreindexTiles
            ExcludeLogic --> PreindexTiles
        end
    end

    %% Core Library
    subgraph "Core Library"
        direction TB
        Finder["Polygon Finder"]:::core
        FuzzyFinder["FuzzyFinder (Tile + RTree)"]:::core
        DefaultFinder["DefaultFinder"]:::core
        MapsUtil["internal/maps"]:::core

        FullPB --> Finder
        CompressData --> Finder
        PreindexTiles --> FuzzyFinder
        FullPB --> FuzzyFinder

        Finder --> DefaultFinder
        FuzzyFinder --> DefaultFinder

        %% Query flow
        DefaultFinder -->|"GetTimezoneName() → tile lookup"| FuzzyFinder
        FuzzyFinder -->|"if miss → fallback"| Finder
        Finder -->|"polygon ray-cast"| DefaultFinder
    end

    %% CLI / User Interface
    subgraph "CLI / UI"
        direction TB
        TZFCLI["tzf CLI"]:::cli
        TZFCLI --> DefaultFinder
    end

    %% External Dependencies
    subgraph "External Systems & Dependencies"
        direction TB
        ProtobufLib["Protobuf"]:::external
        GeoJSONLib["GeoJSON Lib"]:::external
        RTreeLib["RTree Lib"]:::external

        ProtobufLib --> FullPB
        ProtobufLib --> LiteData
        ProtobufLib --> CompressData
        ProtobufLib --> PreindexTiles

        GeoJSONLib --> GeoJSON2PB
        GeoJSONLib --> Finder

        RTreeLib --> FuzzyFinder
    end

    %% Click Events
    click GeoJSON2PB "https://github.com/ringsaturn/tzf/blob/main/cmd/geojson2tzpb/main.go"
    click ConvUtils "https://github.com/ringsaturn/tzf/blob/main/convert/convert.go"
    click PB2Geo "https://github.com/ringsaturn/tzf/blob/main/convert/pb2geometry.go"
    click Revert "https://github.com/ringsaturn/tzf/blob/main/convert/revert.go"
    click ReduceLib "https://github.com/ringsaturn/tzf/blob/main/reduce/reduce.go"
    click CompressLib "https://github.com/ringsaturn/tzf/blob/main/reduce/compress.go"
    click LiteData "https://github.com/ringsaturn/tzf/blob/main/cmd/reducetzpb/main.go"
    click CompressData "https://github.com/ringsaturn/tzf/blob/main/cmd/compresstzpb/main.go"
    click PreindexTiles "https://github.com/ringsaturn/tzf/blob/main/cmd/preindextzpb/main.go"
    click PreindexLib "https://github.com/ringsaturn/tzf/blob/main/preindex/preindex.go"
    click ExcludeLogic "https://github.com/ringsaturn/tzf/blob/main/preindex/exclude.go"
    click FullPB "https://github.com/ringsaturn/tzf/blob/main/pb/tzf/v1/tzinfo.proto"
    click FullPB "https://github.com/ringsaturn/tzf/blob/main/gen/go/tzf/v1/tzinfo.pb.go"
    click Finder "https://github.com/ringsaturn/tzf/blob/main/tzf.go"
    click FuzzyFinder "https://github.com/ringsaturn/tzf/blob/main/tzf_fuzzy.go"
    click DefaultFinder "https://github.com/ringsaturn/tzf/blob/main/tzf_default_finder.go"
    click MapsUtil "https://github.com/ringsaturn/tzf/blob/main/internal/maps/maps.go"
    click TZFCLI "https://github.com/ringsaturn/tzf/blob/main/cmd/tzf/main.go"
    click python "https://github.com/ringsaturn/tzf/blob/main/python/README.md"

    %% Styles
    classDef pipeline fill:#D0E7FF,stroke:#000,color:#000
    classDef core fill:#DFFFE0,stroke:#000,color:#000
    classDef cli fill:#FFE0B2,stroke:#000,color:#000
    classDef external fill:#DDDDDD,stroke:#000,color:#000
```
