Glorion

Map the journey. Shape it with AI.

A map-first, AI-assisted travel planner for turning real places into trips you can actually take.

Quick start · What it does · Architecture

Glorion keeps the map, itinerary, and travel context in one workspace. Pin real places, arrange them into days, connect the route, and ask an AI planning partner to find or refine the next stop.

• Map-first planning — search real places, add pins, build day-by-day itineraries, and connect stops into routes.
• AI travel partner — stream Markdown responses, suggest candidate places, and help shape a plan without silently changing it.
• Travel context — POI details, photos, map overlays, and weather at the point of planning.
• Shared plans — invite members and control plan visibility and access.
• Bring your own model — configure multiple providers or store a personal API key encrypted at rest.
• Operations console — bootstrap an administrator, manage users, inspect configuration, and enforce per-user AI quotas.

• A polished public Explore experience.
• Authenticated real-time co-editing and presence.

The Docker Compose bundle is the shortest path to a complete local stack.

cd deploy/docker
cp .env.example .env

Open .env and set at least:

For place search and AI planning, also configure AMAP_WEB_SERVICE_KEY, LLM_BASE_URL, and LLM_API_KEY as required by your providers.

docker compose up -d --build

Open http://localhost. The API runs behind the bundled Nginx proxy, and database migrations run automatically when the backend starts.

To use the optional Agent Gateway profile:

docker compose --profile agentgateway up -d

The mirrored Agent Gateway image is pinned to the v1.3.1 linux/amd64 digest; production hosts for this bundle must use amd64.

To expose Glorion with automatically managed HTTPS, point a domain's DNS A record at the server (and add AAAA only when IPv6 is publicly reachable), then set these values in deploy/docker/.env:

CADDY_DOMAIN=glorion.example.com
FRONTEND_URL=https://glorion.example.com
FRONTEND_PORT=127.0.0.1:8080

Start the optional Caddy profile:

docker compose --profile caddy up -d

Caddy owns public ports 80/443, obtains and renews the certificate, redirects HTTP to HTTPS, and proxies API, upload, SSE, and WebSocket traffic. Keep ports 80 and 443 reachable from the internet for certificate issuance. To combine both optional services, enable both profiles:

docker compose --profile caddy --profile agentgateway up -d

• Rust 1.88+
• Node.js 22+
• PostgreSQL 16+
• AMap JavaScript and Web Service credentials
• An LLM provider when testing AI features

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env.local

cd frontend
npm install
cd ..

Before starting the backend, set API_KEY_SECRET in backend/.env to the 64-character hex output of openssl rand -hex 32, and replace the example ADMIN_PASSWORD.

Then start both services:

make start       # backend :3000, frontend :5173
make status      # processes and health checks
make logs        # follow both logs
make stop

Or work on each service directly:

# Frontend
cd frontend
npm run dev
npm run test
npm run lint
npm run build

# Backend
cd ../backend
cargo run -p api-server
cargo test --workspace

The internal AI agent and the MCP server share the same canonical 18-tool runtime. The MCP process is a thin stdio protocol adapter; it does not contain a second implementation of plan or map operations.

Launch it with a short-lived user access token:

cd backend
MCP_ACCESS_TOKEN='<access-token>' \
MCP_SCOPES='maps:read,weather:read,plans:read' \
cargo run -p mcp-server

MCP_SCOPES defaults to the read-only value shown above. Write capabilities must be explicitly enabled with plans:write; destructive point deletion also requires plans:delete. Every write or destructive call uses MCP elicitation to obtain explicit user approval; clients without elicitation support cannot perform mutations. The access token and current account status are revalidated for every call.

The MCP binary intentionally does not load backend/.env. Supply only the required variables from a trusted local MCP host, use a dedicated least- privilege database role, and never commit credentials to an environment file.

For network clients, run the same tool server with the modern Streamable HTTP transport. Its single MCP endpoint supports POST requests, GET SSE streams, and session deletion:

cd backend
MCP_TRANSPORT=http \
MCP_HTTP_BIND=127.0.0.1:8000 \
MCP_HTTP_PATH=/mcp \
MCP_HTTP_ALLOWED_HOSTS=localhost,127.0.0.1 \
MCP_HTTP_ALLOWED_ORIGINS=http://localhost:5173 \
MCP_SCOPES='maps:read,weather:read,plans:read' \
cargo run -p mcp-server

HTTP mode only accepts five-minute glorion-mcp audience tokens. Exchange a normal authenticated web session for a least-privilege MCP token:

curl -X POST http://localhost:3000/api/v1/auth/mcp-token \
  -H "Authorization: Bearer $GLORION_WEB_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"scopes":["maps:read","weather:read","plans:read"]}'

The granted token scopes are intersected with the server's MCP_SCOPES maximum. Every HTTP request must send this token as Authorization: Bearer <token>; ordinary glorion-web tokens are rejected. MCP_ACCESS_TOKEN is only used by stdio mode. To register the HTTP endpoint in Codex without putting the token in its config file:

export GLORION_MCP_TOKEN='<short-lived-access-token>'
codex mcp add glorion-http \
  --url http://127.0.0.1:8000/mcp \
  --bearer-token-env-var GLORION_MCP_TOKEN

GET /health is an unauthenticated liveness check. Streamable HTTP includes SSE and replaces the deprecated legacy /sse plus /message transport; those legacy endpoints are intentionally not enabled. Bind public deployments behind TLS, configure exact hosts and origins, and use a least-privilege database role. Non-loopback binds fail at startup unless MCP_HTTP_BEHIND_TLS_PROXY=true is set explicitly.

React SPA
   │
   ▼
Axum API ───────────────► AMap / Weather / LLM providers
   │
   ├──── Rig adapter ───► Tool Kernel ◄─── MCP adapter
   │                         │
   ▼                         ▼
Application services ◄───────┘
   │
   ▼
Domain model ◄──────────► PostgreSQL

The backend is a Rust workspace organized around clean architecture boundaries:

together/
├── frontend/                  React 19 + TypeScript 6 + Vite 8
│   └── src/
│       ├── pages/             Route-level screens
│       ├── components/        Shared product UI
│       ├── api/               HTTP and streaming clients
│       ├── hooks/             Data and interaction logic
│       └── stores/            Zustand state
├── backend/
│   └── crates/
│       ├── domain/            Entities and value objects
│       ├── application/       Use cases and service interfaces
│       ├── infrastructure/    Persistence and external providers
│       ├── api-server/        Axum handlers and middleware
│       ├── mcp-server/        Model Context Protocol server
│       └── migration/         Database migrations
├── deploy/docker/             Compose, optional Caddy, Nginx, and gateway config
└── Makefile                   Local service orchestration

Runtime configuration follows this precedence:

built-in defaults < config.toml < environment variables

Non-secret behavior lives in backend/config.toml or deploy/docker/config.toml. Keep credentials such as JWT_SECRET, API_KEY_SECRET, DATABASE_URL, LLM_*, and AMAP_* in the environment.

• Terminate TLS upstream. Enable the optional Compose caddy profile, or put a trusted load balancer/CDN/reverse proxy in front of the stack.
• Restrict browser map keys. VITE_AMAP_JS_KEY and VITE_AMAP_SECURITY_JSCODE are compiled into the frontend and are public by design; apply an AMap domain whitelist.
• Trust proxies deliberately. Only accept X-Forwarded-For from load balancer CIDRs you control.
• Never commit secrets. Keep production credentials outside TOML files and rotate any credential that is exposed.

Dependabot checks frontend npm packages, backend Cargo crates, GitHub Actions, and both application Dockerfiles each week. On pull requests, repository owners, members, and collaborators can comment /help or /retest; the latter reruns only failed jobs from the latest completed Test workflow for the PR's current commit. Deployment is intentionally not exposed as a comment command.

set_real_ip_from <trusted-LB-CIDR>;
real_ip_header X-Forwarded-For;
real_ip_recursive on;

docker run --rm -v <project>_backend_data:/data alpine chown -R 1000:1000 /data