AI Maps is a chat-first personal map copilot. You describe what you want in natural language on the left, and the map workspace on the right updates with curated political overlays, open-data layers, zoom actions, and a visible layer stack.

• Adds curated political overlays like EU, NATO, Eurozone, and Schengen.
• Adds open-data overlays like airports, hospitals, farmland, parks, museums, roads, and tourist attractions in a place.
• Lets you hide, remove, clear, save, favorite, and export layers.
• Preserves conversation and workspace state during the session.
• Works without AI credentials by using a deterministic parser for the common flows.
• Supports a provider hub with OpenAI subscription bridge, Google Gemini subscription bridge, OpenAI API key, Google API key, and deterministic mode.

1. Use Node 20: nvm use
2. Install dependencies: yarn install
3. Copy env template if needed: cp .env.example .env
4. Start the app: yarn dev
5. Open http://localhost:5173

• yarn dev: run frontend and backend together
• yarn lint: run ESLint
• yarn test: run Vitest
• yarn typecheck: run TypeScript project checks
• yarn build: build client and server
• yarn start: run the production server

• PORT: backend port, default 8787
• OPENAI_API_KEY: optional OpenAI API key backup mode
• OPENAI_MODEL: optional model name for OpenAI API mode
• GOOGLE_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY: optional Google Gemini API key backup mode
• GOOGLE_MODEL: optional model name for Google API mode
• GOOGLE_CLIENT_ID: optional Google sign-in client id
• GOOGLE_CLIENT_SECRET: optional Google sign-in client secret
• GOOGLE_REDIRECT_URI: optional Google OAuth callback URL, default http://localhost:8787/api/auth/google/callback
• APP_BASE_URL: frontend base URL used after Google auth callbacks
• OPENAI_SUBSCRIPTION_BRIDGE_URL: optional default OpenAI subscription bridge base URL
• OPENAI_SUBSCRIPTION_BRIDGE_TOKEN: optional OpenAI subscription bridge bearer token
• OPENAI_SUBSCRIPTION_BRIDGE_HEALTH_PATH: optional OpenAI bridge health path
• OPENAI_SUBSCRIPTION_BRIDGE_INTERPRET_PATH: optional OpenAI bridge interpret path
• GOOGLE_SUBSCRIPTION_BRIDGE_URL: optional default Google Gemini subscription bridge base URL
• GOOGLE_SUBSCRIPTION_BRIDGE_TOKEN: optional Google bridge bearer token
• GOOGLE_SUBSCRIPTION_BRIDGE_HEALTH_PATH: optional Google bridge health path
• GOOGLE_SUBSCRIPTION_BRIDGE_INTERPRET_PATH: optional Google bridge interpret path
• AI_BRIDGE_TIMEOUT_MS: optional subscription bridge timeout in milliseconds
• PROVIDER_VERIFY_TIMEOUT_MS: optional bridge verification timeout in milliseconds
• GEOCODER_USER_AGENT: user agent string for Nominatim

• Guest-first workspace with real backend Google sign-in support when configured
• Full-height Material-inspired split layout with drawer-based secondary workflows
• Example prompts for first-run success
• Provider hub for deterministic, OpenAI subscription, Google Gemini subscription, OpenAI API, and Google API modes
• Saved views, recent sessions, GeoJSON export, and map image export

• Frontend: React + Vite + Tailwind + React Leaflet
• Backend: Express + TypeScript + zod
• Curated overlays: local ISO country sets resolved against packaged world geometry
• Generic overlays: Nominatim for place lookup, Overpass for OSM features
• AI: deterministic parser first, optional subscription bridge or API enhancement second

• Show EU countries works on first run
• Show NATO members, Show Eurozone, and Show Schengen Area work
• Show airports in Croatia and Highlight farmland in Poland work
• Zoom to Paris and show tourist attractions works
• Remove airports removes only airport layers
• Clear all layers removes all map overlays
• Build, lint, typecheck, and tests pass

• Google sign-in requires GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET on the server; without them the UI falls back gracefully and explains that sign-in is unavailable.
• Subscription connector cards are real server-managed bridge settings, but actual bridge compatibility depends on the local companion endpoint you connect to.
• Nominatim and Overpass are external public services, so generic live-data requests depend on network availability and provider health.

• Durable server-backed storage for signed-in workspaces
• More categories and richer place disambiguation
• Better clustering and high-volume feature rendering
• Packaged local companion for personal subscription modes