Craftscape HK

AI-powered platform preserving Hong Kong's disappearing traditional crafts through AR experiences, and AI-assisted custom design creation with real-world artisans to bring ideas to life.

Comment

Craftscape HK (藝守) – Project Story

Live Demo

Public Repository

Inspiration

Hong Kong’s traditional crafts—such as hand-carved mahjong tiles, painted porcelain, cheongsam, and neon sign—are fading due to shrinking markets and an aging artisan community.

More than 70% of craft shops have shut in recent years as demand wanes and rents spike, typical revenues have fallen 30–50% amid mass-produced competition, and 80% of artisans say their children won’t continue the trade because of long hours, low pay, and little recognition.

We wanted to build a bridge between the past and the future, enabling young people and global visitors to not only appreciate but also interact with these disappearing arts, and translating the appreciation into tangible support. Because the most meaningful way to preserve a craft is to create a thriving economy around it.

Introduction

Craftscape HK is an AI + AR e-commerce platform where users can:

  • Explore craft stories through a swipe-card interface (like Tinder).
  • Use the AI Creation Studio to design their own craft pieces and directly commission artisans to bring them to life.
  • Experience AR interactive virtual exhibitions with 360° product views, real-world photo integration, and immersive storytelling.
  • Access a city-wide cultural events calendar for exhibitions, workshops, and community activities.
  • Support artisans by purchasing products, attending workshops, and visiting virtual/AR exhibitions.

Architecture Overview

Craftscape HK follows a cloud-native microservices architecture deployed on Google Cloud Platform, via Cloud Run for serverless container orchestration.

Architecture Diagram

Link to Architecture Diagram

Google Cloud Ecosystem

  • ✅ Gemini 2.5 Flash Image (Nano Banana): AI-powered image generation for custom craft designs
  • ✅ Gemini 2.0 Flash: Text-based design generation (mahjong translation and letterpress composition)
  • ✅ Cloud Run: Serverless container orchestration for both frontend and backend services (0-10 auto-scaling)
  • ✅ Container Registry (GCR): Stores Docker images for both services with automatic versioning and rollback support
  • ✅ Cloud Build: CI/CD pipeline triggered on GitHub pushes, builds and deploys both services automatically
  • ✅ Cloud Scheduler: Triggers monthly container image cleanup job (1st of month @ 2 AM)
  • ✅ Cloud Storage: Hosts USDZ AR assets and static files
  • ✅ Cloud Logging: Centralized logs for monitoring
  • ✅ Secret Manager: Gemini API key storage
  • ✅ Google AI Studio: Initial codebase and inspiration
  • Future: Cloud SQL/Firestore (future user data)

Frontend

  • Technology Stack: React 19, TypeScript, Vite, Tailwind CSS, Framer Motion
  • Container: Multi-stage Docker build using Node.js (builder) + Nginx (production)
  • Web Server: Nginx on port 8080 with:
    • Client-side routing support (React Router)
    • API proxy to backend service (/api/* routes)
    • Static asset caching and gzip compression
    • Security headers (X-Frame-Options, CSP, etc.)
  • Resource Allocation: 256Mi RAM, 1 CPU, 60s timeout
  • Scaling: Auto-scales 0-10 instances based on traffic

Backend

  • Technology Stack: NestJS, TypeORM, SQLite, Google GenAI SDK
  • Container: Single-stage Docker build with Node.js 20 (includes build dependencies for canvas)
  • API Modules:
    • Crafts: Traditional craft catalog and stories
    • Products: E-commerce product listings
    • Events: Cultural events and workshops calendar
    • Orders: Purchase and commission management
    • Messages: Artisan-customer communication
    • AI: Multimodal prompt to image generation via Nano Banana (gemini-2.5-flash-image) + Text generation via gemini-2.0-flash-exp
    • Admin: Database seeding and management endpoints for demo
  • Database: SQLite bundled within container (seeded on deployment)
  • Resource Allocation: 512Mi RAM, 1 CPU, 300s timeout
  • Scaling: Auto-scales 0-10 instances based on traffic
  • CORS: Configured for frontend, localhost, and development origins

CI/CD Pipeline

  • Source: GitHub Repository
  • Build: Google Cloud Build (Docker-based build automation)
  • Deploy: Google Cloud Run (container orchestration)
  • Image Management: Google Container Registry
  • Security & Monitoring:
    • IAM (Identity and Access Management)
    • Secret Manager (API keys and credentials)
    • Cloud Logging (for observability and debugging
  • Cost Optimization: Cloud Scheduler triggers monthly cleanup job to only keep the last 5 versions of each container image in GCR

Data Flow

  1. User Request → Frontend Cloud Run service (Nginx)
  2. Static Content → Served directly from Nginx
  3. API Request (/api/*) → Proxied to Backend Cloud Run service
  4. Backend Processing → NestJS handles request, queries SQLite
  5. AI Generation → Backend calls Gemini API
  6. Response → Data flows back through proxy to frontend
  7. AR Content → USDZ files served as static assets

Key Features

1. AI Creation Studio (Gemini Integration)

Users can describe their desired craft design in natural language, and our AI generates custom designs: Model: Gemini 2.5 Flash Image & Gemini 2.0 Flash Input: Text prompts describing craft style, elements, colors Output: AI generated custom design images Use Case: Users design custom mahjong tiles, cheongsam patterns, neon signs, and letterpress design

2. AR Virtual Exhibitions

  • View 3D craft models in your physical space
  • 360° product rotation
  • USDZ format for iOS Quick Look

3. E-Commerce Platform

  • Direct commission system connecting users to artisans
  • Product marketplace with authentic craft pieces
  • Order management system

4. Cultural Events Calendar

  • City-wide exhibitions and workshops
  • Community engagement features
  • Artisan-led experiences

Challenges we ran into

  • Limited digital archives for crafts like hand-carved mahjong required manual data collection.
  • Many artisans are elderly and unfamiliar with digital tools, so onboarding needed special care and training.
  • Balancing AI-generated creativity with respect for authentic craft aesthetics was challenging.
  • Ensuring sustainability by making the platform engaging for users while providing artisans with fair income.

Accomplishments that we're proud of

  • Built a comprehensive prototype of the AI Creation Studio that generates unique personalized craft designs for different kinds of crafts.
  • Successfully piloted a working AR exhibition demo with 360° artifact viewing and real-world photo integration.
  • Engaged real artisans in co-design workshops to validate cultural and practical feasibility.
  • Developed a model for integrating cultural heritage into everyday digital life.

What we learned

  • Technology must act as a bridge, not a replacement, for traditional knowledge.
  • AR is powerful for creating immersive cultural experiences that attract young users.
  • The sustainability of cultural projects depends on building both emotional connection and economic value for artisans.
  • Community collaboration is as important as technical innovation.

What's next for Craftscape HK

  • Expand our dataset of traditional crafts by partnering with museums, NGOs, and cultural heritage groups.
  • Refine the AI Creation Studio to support more customization and multi-modal input (sketch + text).
  • Launch pilot AR exhibitions in collaboration with local cultural centers and schools.
  • Explore monetization pathways to ensure artisans benefit directly from sales and commissions.
  • Scale Craftscape HK into a global platform for cultural heritage preservation, starting with Hong Kong but extending to other endangered crafts worldwide.

Built With

Share this project:

Updates