VietStoryLens 🇻🇳

🏆 LotusHacks x HackHarvard x GenAI Fund Vietnam 2026

Snap a photo. Hear its story. Taste the culture.

---

🎯 What is VietStoryLens?

VietStoryLens turns any Vietnamese landmark into a living story. Snap a photo — AI instantly recognizes it, narrates its history, and recommends the best local food nearby.

You don't just see a place — you experience it.

✨ Features

• 📸 Landmark Recognition — CLIP ViT-L/14 + FAISS identifies 15 HCMC landmarks (~85-93% accuracy)
• 🎙️ AI Storytelling — DeepSeek V4 Flash generates cinematic Vietnamese narration from self-collected historical context
• 🍜 Food Nearby — Overpass API finds restaurants around the landmark, DeepSeek describes dishes, Unsplash provides real food photos
• 🗺️ Multi-Screen Flow — Camera → Recognition → Story → Food → Map
• 📱 Cross-Platform — Flutter (Android, iOS, Web) with Vietnamese-inspired theme
• 🐳 Docker-Ready — One-command deploy with docker-compose + nginx

🧠 Architecture

📐 Edit in draw.io | Download .drawio

🔌 API Endpoints

Method	Endpoint	Description
POST	/api/recognize	Upload image → landmark + AI story
POST	/api/food-nearby	lat/lng → nearby restaurants with descriptions + photos
GET	/api/landmarks	List all 15 supported landmarks
GET	/api/health	Health check

🏛️ Supported Landmarks (15 HCMC)

Landmark	Images	Accuracy
🏰 Independence Palace	137	~93%
⛪ Notre-Dame Cathedral	145	~77%
🐉 Dragon Wharf (Bến Nhà Rồng)	128	~85%
🛒 Ben Thanh Market	130	~85%
📮 Central Post Office	112	~83%
🏢 Bitexco Tower	134	—
🖼️ Fine Arts Museum	95	—
🚶 Nguyen Hue Walking Street	104	—
🕊️ Turtle Lake	116	—
🚩 Thu Ngu Flag Tower	117	—
🌳 Tao Dan Park	55	—
🦁 Saigon Zoo	49	—
🛕 Vinh Nghiem Pagoda	154	—
🌉 Starlight Bridge	96	—
🏛️ War Remnants Museum	98	—

💡 Dataset: 1,665 images with vision tags & historical context — self-collected from real landmarks across HCMC.

🚀 Quick Start

Docker

git clone https://github.com/jamesng16/VietStoryLens.git && cd VietStoryLens

# Set API keys
cat > .env << EOF
LLM_API_KEY=your-deepseek-key
LLM_BASE_URL=https://api.ai-box.vn/v1
LLM_MODEL=deepseek-v4-flash[1m]
UNSPLASH_ACCESS_KEY=your-unsplash-key
EOF

docker compose --env-file .env up -d
# → Frontend: http://localhost:3001
# → Backend:  http://localhost:8000/docs

Local Dev

# Backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python scripts/build_index.py
LLM_API_KEY=... python -m src.api.server

# Frontend
cd frontend && flutter pub get && flutter run

📊 Tech Stack

Layer	Technology
Vision	OpenAI CLIP ViT-L/14 (768-dim)
Vector Search	FAISS IndexFlatIP
LLM	DeepSeek V4 Flash (api.ai-box.vn)
Restaurant Data	OpenStreetMap Overpass API
Food Photos	Unsplash API
Backend	FastAPI + Uvicorn + httpx
Frontend	Flutter (Android/iOS/Web)
Infra	Docker + nginx proxy

📁 Project Structure

VietStoryLens/
├── src/
│   ├── api/server.py          # FastAPI routes
│   ├── agents/graph.py        # Landmark recognition pipeline
│   ├── services/food_nearby.py # Food Nearby service
│   ├── embeddings/            # CLIP encoder + FAISS index
│   ├── data_loader.py         # Dataset loader
│   └── config.py              # Settings
├── frontend/                  # Flutter app
│   └── lib/
│       ├── screens/           # Camera, Story, Food, Map
│       ├── services/          # API client
│       └── theme/             # Vietnamese color scheme
├── data/                      # 1,665 images + metadata JSON
├── scripts/build_index.py
├── docker-compose.yml
└── Dockerfile

🗺️ Roadmap

We welcome contributions! Here's what's planned:

• 🇻🇳 Expand beyond HCMC — Add Hanoi (Hoàn Kiếm, Văn Miếu, Lăng Bác...), Huế (Đại Nội, chùa Thiên Mụ...), Hội An, Đà Nẵng, Nha Trang, Hạ Long
• 🌐 Multilingual support — English, Chinese, Japanese, Korean for international tourists
• 🎯 Fine-tuned CLIP — Domain-adaptive training on Vietnamese architecture for higher accuracy
• 🗣️ Real TTS narration — ElevenLabs / Coqui AI voice instead of text-only stories
• 📡 AR overlay — Augmented reality to overlay historical photos onto live camera view
• ⚡ Performance optimization — GPU inference, response caching, smaller CLIP variant
• 📊 Admin dashboard — Manage landmarks, review AI-generated stories, track usage analytics
• 🧪 Automated testing — CI/CD pipeline, integration tests, visual regression tests

💡 Want to contribute? Pick an item above, open an issue, or submit a PR! See CONTRIBUTING.md for guidelines.

👥 Team

Built with ❤️ at LotusHacks 2026 by:

Role	Name	GitHub
🧠 AI Engineer	Nguyen Viet Hoang	@jamesng16
💻 Developer	Phap Duy	—
🎨 Designer	Ly Nguyen Hoang Anh	—
🔧 Developer	Melvin Lim	—

📄 License

MIT © 2026 VietStoryLens Team