# tidwall/tile38 architecture

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

- Interactive diagram: https://gitdiagram.com/tidwall/tile38
- Repository: https://github.com/tidwall/tile38

## Overview

##### Project Type and Purpose
- Tile38 is an open source, in-memory geolocation data store with functionalities for spatial indexing and real‑time geofencing. The README makes it clear that the primary server (tile38-server) supports a variety of spatial queries and geofence monitoring, while additional executables (tile38-cli, tile38-benchmark, etc.) provide command‑line interaction and performance testing.

##### Analyzing the File Structure
- Notice the top-level directories and files:
- The "cmd" directory includes several executables, such as tile38-server (the core service), tile38-cli (for command line interface), tile38-benchmark (for performance testing), and tile38-luamemtest. This suggests distinct modes of operation.
- The "core" directory holds command definitions including static and generated code, which implies a central place for processing commands.
- The "internal" directory is broken into packages like “buffer”, “clip”, “collection”, “endpoint”, “server”, “field”, and “glob”. These illustrate detailed modules for spatial data handling, command processing, network endpoints (supporting multiple protocols like HTTP, websockets, RESP, etc.), and persistence (like AOF files).
- The “tests” directory covers a comprehensive suite of tests verifying behavior for geofencing, searching, client commands, etc.
- The existence of build scripts (Makefile, Dockerfile, etc.) and GitHub workflows shows continuous integration and container support.

##### Key Components
a. Main Components:
- tile38-server: The core in-memory geolocation server.
- tile38-cli: A command line tool that interacts with the server.
- tile38-benchmark: A performance benchmarking tool.
- Supporting libraries and internal modules: Modules for spatial indexing (e.g., internal/collection, internal/clip), command parsing and execution (e.g., core/commands, internal/server), and network endpoint support (various files in internal/endpoint for HTTP, gRPC, etc.).

b. Relationships and Interactions:
- The CLI and benchmark tools are client applications that connect to the server using various protocols (HTTP, websockets, RESP).
- Within the server, there is a layered architecture:
- The Network Layer (internal/endpoint) handles different protocols and client connections.
- The Command Parser/Processor (core/commands and related tests) interprets incoming commands.
- The Spatial Index and Data Store (internal/collection and internal/object) manage geolocation data in-memory and support spatial queries (nearby, within, intersects).
- Additional modules (internal/server, internal/field, internal/glob) support operations like geofencing, field filtering, and pattern matching.
- Persistence mechanisms are managed under internal/server (AOF persistence, configuration management, and metrics).
- Communication flows from external clients sending commands to the network layer, then being parsed and processed by the command engine, which in turn interacts with the in-memory spatial storage and triggers any observable side‑effects (such as geofence events delivered via pub/sub or webhooks).

c. Architectural Patterns and Design Principles:
- Modularity: The project breaks functionalities into well‑defined internal packages. For example, separate packages for “clip”, “collection”, and “endpoint” indicate clean separation of concerns.
- Multi-Protocol Support: The internal/endpoint modules provide an abstraction over various transport protocols (HTTP, telnet/RESP, websockets, and even gRPC).
- Real‑time Processing: Emphasis on geofencing (where long‑running connections are maintained) and spatial indexing for real‑time queries.
- Command Centered Design: The “core/commands” and associated JSON files suggest that the server uses a command–oriented architecture, much like Redis.

d. Technologies and Frameworks:
- Written fully in Go, using Go modules for dependency management (go.mod, go.sum).
- Uses Docker for containerized deployments (Dockerfile included).
- CI/CD workflows available via GitHub Actions.
- Supports Prometheus metrics, which may be integrated into the overall monitoring of the system.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% External Clients
    CLI["Tile38 CLI"]:::external
    Benchmark["Tile38 Benchmark"]:::external
    LuaMemTest["Tile38 LuaMemTest"]:::external

    %% Core Server Node
    ServerMain["Tile38 Server"]:::internal

    %% Internal Modules Subgraph
    subgraph "Tile38 Server Internal Modules"
        NL["Network Endpoints"]:::internal
        CP["Command Parser & Engine"]:::internal
        SD["Spatial Data Store & Index"]:::internal
        PM["Persistence & Metrics"]:::persistence
    end

    %% Comprehensive Test Suite
    TestSuite["Test Suite"]:::external

    %% Connections from External Clients to Server
    CLI -->|"HTTP/RESP/WebSockets"| NL
    Benchmark -->|"HTTP/RESP/WebSockets"| NL
    LuaMemTest -->|"HTTP/RESP/WebSockets"| NL

    %% Server Main dispatches to Internal Modules
    ServerMain --> NL

    %% Internal Modules Flow
    NL -->|"parses requests"| CP
    CP -->|"executes spatial queries"| SD
    SD -- "query results" --> CP
    CP -->|"updates state & metrics"| PM

    %% Test Suite verifies server behavior
    TestSuite -->|"runs integration tests"| ServerMain

    %% Click Events
    click ServerMain "https://github.com/tidwall/tile38/blob/master/cmd/tile38-server/main.go"
    click CLI "https://github.com/tidwall/tile38/blob/master/cmd/tile38-cli/main.go"
    click Benchmark "https://github.com/tidwall/tile38/blob/master/cmd/tile38-benchmark/main.go"
    click LuaMemTest "https://github.com/tidwall/tile38/blob/master/cmd/tile38-luamemtest/main.go"
    click CP "https://github.com/tidwall/tile38/blob/master/core/commands.go"
    click NL "https://github.com/tidwall/tile38/tree/master/internal/endpoint"
    click SD "https://github.com/tidwall/tile38/blob/master/internal/collection/collection.go"
    click PM "https://github.com/tidwall/tile38/blob/master/internal/server/aof.go"
    click TestSuite "https://github.com/tidwall/tile38/tree/master/tests"

    %% Styles
    classDef external fill:#A0D468,stroke:#333,stroke-width:2px;
    classDef internal fill:#4A89DC,stroke:#333,stroke-width:2px;
    classDef persistence fill:#ED5565,stroke:#333,stroke-width:2px;
```
