================================================================================
                    GEOMATCH :: GEOSPATIAL SEARCH ENGINE
================================================================================

      ___
     /   \       EVENT-DRIVEN GEOSPATIAL MATCHING
  __/ H3  \__    INDEX:        Uber H3 (DGGS)
 /   \   /   \   TOPOLOGY:     Hexagonal
 \___/ \___/     LATENCY:      < 10ms (end-to-end target)
     \   /
      \___/


─────────────────────────────[ RUNTIME CORE ]──────────────────────────────────

KERNEL = Java Services (Spring Boot)
BUS    = Apache Kafka
STATE  = Redis (Primary In-Memory State)
INDEX  = Uber H3 (Java bindings)
JVM    = Java 21 (low-latency tuning)


───────────────────────────[ DATA PLANE ROUTE ]─────────────────────────────────

producer → kafka → spatial indexer → redis state → match publisher


───────────────────────────[ TOPOLOGY GRAPH ]───────────────────────────────────

graph LR
    A[GPS_UPDATE] -->|H3 Quantize| B(H3_CELL_ID)
    B -->|State Update| C{REDIS_CELL_SET}
    C -->|TTL / Expiry| D[ACTIVE_ENTITIES]
    E[Search_Request] -->|k-Ring| B


───────────────────────────[ WRITE PATH : INGEST ]──────────────────────────────

continuous geodetic coordinates
↓
discrete spatial identity (cell-based)

intent:
eliminate O(N) spatial scans
reduce distance computation
optimize for adjacency checks

// H3 resolution is configurable (latency vs precision tradeoff)
long h3Index = h3Core.geoToH3(lat, lng, resolution);
redis.sadd("cell:" + h3Index, entityId);
redis.expire("cell:" + h3Index, ttlSeconds);


───────────────────────────[ READ PATH : SEARCH ]───────────────────────────────

search is cell-driven, not entity-driven

ring_0 traversal
origin cell lookup

cost: O(1)
op:   SMEMBERS cell:{origin_h3}


───────────────────────────[ RING EXPANSION ]───────────────────────────────────

progressive neighbor expansion using k-ring

ring_1, ring_2, ...
until:
- sufficient candidates found
- max search radius reached

cost: O(k × 6)
topology: static hex adjacency
distance math: deferred


───────────────────────────[ MATCH RESOLUTION ]─────────────────────────────────

matching follows event order
no global locks
no central coordinator

optional atomic acquisition (use-case dependent)

SPOP cell:89283082803ffff 1
"entity_uuid_550e8400"

nil => no available match in current ring


───────────────────────────[ FAILURE MODEL ]────────────────────────────────────

duplicate events tolerated
bounded out-of-order handling via partitioning
redis loss recoverable via replay
backpressure affects latency, not correctness

exactly-once is not assumed
replayability is required


───────────────────────────[ OBSERVABILITY ]────────────────────────────────────

metrics-first approach

GET /actuator/metrics
latency percentiles
consumer lag
throughput

application-level logging
event timing at stage boundaries


───────────────────────────[ EXECUTION ENV ]────────────────────────────────────

Java 21
Docker
Apache Kafka
Redis


───────────────────────────[ BOOT SEQUENCE ]────────────────────────────────────

./mvnw clean package -DskipTests
docker-compose up -d
java -jar target/geomatch-core.jar


───────────────────────────[ DESIGN CONSTRAINTS ]───────────────────────────────

latency prioritized over abstraction
events over requests
state close to compute
space discretized early
distance calculated late


───────────────────────────[ FORWARD POINTERS ]─────────────────────────────────

[SCALING]
Partition Kafka topics by spatial locality (H3 parent cells)

[OPTIMIZATION]
Binary serialization for internal Kafka payloads

[EXTENSION]
Polygon-based geofencing via H3 polyfill


───────────────────────────[ END OF MAP ]───────────────────────────────────────

      ___
     /   \
  __/ EOF \__
 /   \   /   \
 \___/ \___/

================================================================================