LingYan MVP

LingYan is a mobile-first AI oracle for intent, place, and native navigation handoff.

It turns a short human intention into a safe, reachable city coordinate, then hands the destination to Amap for the real navigation experience. LingYan is designed to run as a mobile PWA: open it in a phone browser, add it to the Home Screen, and use it like a lightweight app without App Store distribution.

Why It Exists

Most navigation apps start with a destination. LingYan starts with a thought.

"I need inspiration."
"I want a quiet place."
"Take me somewhere that fits this moment."

LingYan interprets the intent, picks a public and approachable location nearby, creates a short "micro-action" prompt, and opens Amap for native navigation. LingYan does not try to clone a full navigation app in the browser.

Core Experience

flowchart TD
    A["User enters an intention"] --> B["Browser location"]
    B --> C["Intent classification"]
    C --> D["Safe coordinate generation"]
    D --> E["Oracle result card"]
    E --> F["Amap route preview"]
    E --> G["Start navigation"]
    G --> H{"Amap app opens?"}
    H -->|Yes| I["Native Amap navigation"]
    H -->|No| J["Install Amap / copy coordinate"]

Loading

Features

Area	Status	Notes
Intent input	✅	Short intention-based interaction
Location access	✅	Browser geolocation with demo fallback
Coordinate generation	✅	Deterministic safe-public-location style MVP
Map display	✅	Leaflet fallback and Amap route view
Amap route planning	✅	Walking and driving previews, transit handed to Amap App
Native Amap handoff	✅	iOS and Android/Huawei deeplink attempts
Amap install fallback	✅	Device-aware install and copy-coordinate fallback
PWA install support	✅	Manifest, icon, iOS meta tags, service worker
Background navigation	❌	Not promised in PWA mode
App Store distribution	❌	Intentionally not required for MVP

Architecture

flowchart LR
    UI["React UI"] --> App["App state"]
    App --> Intent["Intent logic"]
    App --> Oracle["Oracle generation"]
    App --> Map["Map components"]
    Map --> Amap["Amap JS API"]
    App --> Nav["Navigation launcher"]
    Nav --> Native["Amap iOS / Android deeplink"]
    Nav --> Fallback["Install/copy fallback"]

Loading

Tech Stack

Layer	Choice
Language	TypeScript
UI	React 18
Build	Vite
Map fallback	Leaflet
Route provider	Amap JS API
PWA	Web App Manifest + Service Worker
Native navigation	Amap app deeplink on iOS and Android/Huawei

Local Development

npm install
npm run dev

Build production assets:

npm run build

Preview the production build:

npm run preview

Cloudflare Pages Deployment

LingYan can be deployed to Cloudflare Pages without owning or maintaining a server.

Setting	Value
Project name	lingyan-mvp
Production branch	main
Framework preset	Vite
Build command	npm run build
Build output directory	dist
Root directory	/

Deployment steps:

1. Open Cloudflare Dashboard.
2. Go to Workers & Pages.
3. Create a Pages project from Git.
4. Connect qinheming/lingyan-mvp.
5. Use the build settings above.
6. Add the Amap environment variables if route preview is needed.
7. Deploy.

Cloudflare will provide a URL like:

https://lingyan-mvp.pages.dev/

Manual CLI deploy is also available:

npm run deploy:cloudflare

Amap Configuration

Create .env.local from .env.example:

cp .env.example .env.local

Then configure:

VITE_AMAP_JS_KEY=
VITE_AMAP_SECURITY_JSCODE=

Without an Amap key, LingYan still runs with its built-in map fallback, but Amap route preview is disabled. The primary navigation action still attempts to open the Amap app.

Mobile PWA Usage

iPhone

1. Open the deployed LingYan URL in Safari.
2. Tap the Share button.
3. Choose Add to Home Screen.
4. Launch LingYan from the Home Screen.

Android / Huawei

1. Open the deployed LingYan URL in Chrome, Huawei Browser, Edge, or another modern browser.
2. Open the browser menu.
3. Choose Add to Home screen or Add to desktop.
4. Launch LingYan from the Home Screen.

For the full navigation experience, install Amap on the phone. LingYan is responsible for intent and destination handoff; Amap is responsible for voice navigation, background navigation, lock-screen behavior, rerouting, and traffic-aware guidance.

Product Boundaries

LingYan is an MVP. It does not replace professional navigation apps.

Boundary	Reason
No guaranteed background GPS	iOS PWA background execution is limited
No lock-screen voice navigation promise	Native apps are better suited for that
No safety-critical routing promise	Users must follow real-world traffic and safety conditions
No private-area guidance	Generated points should remain public and approachable
No browser-based Amap clone	Full navigation UX is delegated to the Amap app

Roadmap

Priority	Item
P0	Test Amap app handoff on real iPhone Safari and Android/Huawei browsers
P0	Move production hosting away from GitHub Pages to an owned domain/server
P1	Add clearer Add-to-Home-Screen onboarding
P1	Add location candidate confirmation
P1	Add Amap install detection guidance
P2	Add account/history support
P2	Add backend AI intent resolver
P3	Native iOS shell with Amap Navigation SDK if App Store/TestFlight becomes acceptable

Repository

This repository is the LingYan MVP frontend:

qinheming/lingyan-mvp

It is currently optimized for fast iteration by an independent builder: small surface area, mobile-first UI, and no App Store dependency. For production use without GitHub dependency, deploy the same build to an owned domain, VPS, Cloudflare Pages, or another controlled hosting target.