Navigation_ms

A distributed conversational navigation system powered by AI, built with Java 17 and Spring Cloud. Users interact with an AI assistant in natural language to search for places, get driving routes, and navigate — all streamed token-by-token in real time.

---

Architecture

┌─────────────────────────────────────────────────────┐
│                   NVG_gateway                        │
│              (Spring Cloud Gateway)                  │
│          port 8080 · Nacos discovery                │
└──────┬─────────────────┬─────────────────┬──────────┘
       │                 │                 │
  /locations/**     /character/**    /chatflux/**
       │                 │                 │
┌──────▼──────┐  ┌────────▼──────┐  ┌─────▼──────────┐
│  location-  │  │   character- │  │    AI-         │
│  service    │  │   service     │  │    service     │
│  port 8081  │  │   port 8084   │  │    port 8082   │
└─────────────┘  └──────┬────────┘  └──────┬─────────┘
                        │                  │
              ┌─────────▼──────┐   ┌───────▼─────────┐
              │  Google Maps    │   │  LangChain4j   │
              │  MCP Server     │   │  (OpenAI GPT-4o)│
              └─────────────────┘   └─────────────────┘

Microservices

Service	Port	Responsibility
NVG_gateway	8080	Route requests · Nacos service discovery
location-service	8081	POI lookup · grid index · driving routes · RabbitMQ events
character-service	8084	Chinese-character place search · Redis caching
AI-service	8082	Streaming AI chat · MCP tool orchestration

---

Tech Stack

Area	Technology
Language / JVM	Java 17
Framework	Spring Boot 3 · Spring Cloud Gateway
AI	LangChain4j · OpenAI GPT-4o (streaming)
Tool protocol	MCP (Model Context Protocol) — Google Maps server
Service disc.	Alibaba Nacos
Caching	Spring Data Redis
Messaging	Spring AMQP (RabbitMQ)
Serialization	Protobuf
Resiliency	Alibaba Sentinel
API docs	OpenAPI / Swagger

---

Features

Data Pipeline

• Offline indexing of 160K+ POIs: spatial grid index (~500 m cells) for coordinate-based lookup and character inverted index for Chinese name search.
• Binary search on a sorted index reduces term lookup to O(log n) — ~18 comparisons vs ~80K for linear scan on 160K terms (~99% fewer operations).
• Protobuf for compact, fast binary serialization.

Location & Routing

• Integrated Google Maps API for POI search and step-by-step driving directions.
• Spring AMQP (RabbitMQ) for event-driven location flows.

Search

• Chinese-character place search using the Protobuf index and character inverted index.
• Spring Data Redis caching for repeated character queries.

AI Assistant

• Streaming chat endpoint (/chatflux) returning Flux<String> — token-by-token SSE-style output.
• MCP (Model Context Protocol) exposes Google Maps tools directly to the LLM so it can look up places and routes autonomously.
• Conversation memory (last 10 messages per session).

---

API Endpoints

Location Service (localhost:8081)

Method	Path	Description
GET	/locations/nearby	POIs within radius of coordinates
GET	/locations/search	Full-text location search
GET	/route/steps	Driving route between two points

Character Service (localhost:8084)

Method	Path	Description
GET	/character/search?query=&limit=	Single-character search
GET	/character/multi?query=&limit=	Multi-character AND search
GET	/character/search?query=&mode=&limit=	AND / OR / prefix mode
GET	/characterRedis/search?query=&limit=	Redis-cached search

AI Service (localhost:8082)

Method	Path	Description
GET	/chatflux?sessionId=&message=	Streaming AI chat (token-by-token)

---

Getting Started

Prerequisites

• Java 17+
• Maven 3.8+
• Docker (for Redis, RabbitMQ, Nacos)

1. Start infrastructure

# Redis, RabbitMQ, Nacos — replace with your own instances or docker-compose
docker run -d --name redis -p 6379:6379 -e REDIS_PASSWORD=***REMOVED*** redis
docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3
docker run -d --name ***REMOVED*** -p 8848:8848 ***REMOVED***/***REMOVED***-server:v2.2.3

2. Configure environment variables

# AI-service
export OPENAI_API_KEY=sk-...
export GOOGLE_MAPS_API_KEY=...

# Nacos (set in each application.yml if not using defaults)
# server-addr: ***REMOVED***:8848
# username: ***REMOVED***
# password: ***REMOVED***

3. Build & run

# Root module
mvn clean install -DskipTests

# Each service (separate terminals)
cd NVG_gateway        && mvn spring-boot:run
cd location-service   && mvn spring-boot:run
cd character-service  && mvn spring-boot:run
cd AI-service         && mvn spring-boot:run

Gateway is reachable at http://localhost:8080.

4. Test the AI streaming chat

curl -N "http://localhost:8082/chatflux?sessionId=session1&message=nearby%20coffee"

---

Project Structure

Navigation_ms/
├── pom.xml                      # Multi-module Maven parent
├── NVG_gateway/                 # Spring Cloud Gateway + Nacos
├── location-service/            # POI lookup, grid index, routing
│   ├── data/                    # ip_name_data_gidx.csv (160K POIs)
│   └── src/main/java/...
├── character-service/            # Character search, Redis cache
│   ├── data/                    # places.pb, index_by_offset.csv
│   └── src/main/java/...
└── AI-service/                  # LangChain4j streaming AI + MCP
    └── src/main/java/...

---

Notes

• Do not commit secrets. Copy application.yml → application-secrets.yml and add application-secrets.yml to .gitignore. Use environment variables or a secrets manager for API keys in production.
• Sentinel dashboard (sentinel-dashboard.jar) is included for rate limiting / circuit breaking UI.
• The MCP Google Maps server requires Node.js (npx @modelcontextprotocol/server-google-maps) and the GOOGLE_MAPS_API_KEY environment variable.