LeafPace 🍃

이것은 Hacktoberfest Open-Source AI Challenge Week 1: 풀밭을 만지기에 대한 제출물입니다.

화면은 경험의 가장 짧은 부분이어야 한다. 휴대폰에서 30초 → 트레일에서는 45분.

제가 만든 것 (What I Built)

LeafPace는 러너, 워커, 하이커를 화면에서 벗어나 야외로 이끄는 제로 백엔드(zero-backend) 프로그레시브 웹 앱입니다. 30초 만에 다음과 같은 기능을 제공합니다:

1. 자연 친화적 루프 합성 (Nature-biased loop synthesis) — 달리기(🏃 Run) / 걷기(🚶 Walk) / 하이킹(🥾 Hike) 중 하나, 거리(1–15 km), 그리고 녹지 편향성(Dense Canopy / Park Hopper / Dirt Trail)을 선택합니다. LeafPace는 주변의 실제 공원, 숲, 자연 보호 구역에 대해 OpenStreetMap에서 질의하여 그 사이를 순환하는 루프를 투영하고, 이를 실제 보행자 네트워크(OSRM foot, Valhalla 오픈 엔진이 폴백으로 사용됨)에 맞춥니다. 일반적인 내비게이션 앱은 가장 시끄러운 아스팔트를 따라 경로를 안내하지만, LeafPace는 나무 아래로 경로를 안내합니다.
2. 태양 및 그늘 자문 (Solar & shade advisory) — 정확한 좌표와 시간에 맞춰 태양의 방위각/고도를 계산하고, 눈부신 낮은 햇빛에 노출될지 아니면 시원한 캐노피 아래에 있을지를 알려줍니다.
3. GPX 핸드오프 (GPX hand-off) — 한 번의 탭으로 Garmin, Apple Watch, Strava, Organic Maps용 GPX 1.1 파일(200–300 트랙포인트)을 내보내거나 시계로 바로 공유할 수 있습니다.
4. 화면 종료. 풀밭 만지기 (Screen off. Touch grass.) — 내보내기가 완료되면 화면이 어두워지고 단순히 '휴대폰을 주머니에 넣으세요'라고 표시합니다.

누구를 위한 것인가: 알고리즘 밖에서 달리기나 하이킹을 하고 싶고, 그를 위해 집 주소를 피트니스 소셜 네트워크에 업로드하고 싶지 않은 모든 사람입니다.

아키텍처 기반의 프라이버시 (Privacy by architecture): 백엔드가 없습니다. 사용자의 GPS 좌표는 기기를 벗어나지 않습니다. LeafPace가 수행하는 모든 네트워크 호출(OSM Overpass, Nominatim, OSRM/Valhalla)은 위치 독립적인 공개 API 쿼리이며, AI는 100% 온디바이스(on-device)에서 실행됩니다.

데모 (Demo)

🔗 실제 앱: https://big0boy.github.io/LeafPace/ (GitHub Pages, 호스팅 비용 없음)

휴대폰에서 사용해 보기: 링크를 열고 🍃 Synthesize Trail을 탭한 다음, 📱 Lock Phone & Touch Grass를 탭하세요.

코드

📦 리포지토리(Repo): https://github.com/Big0boy/LeafPace — 모든 의존성은 오픈 소스이며, 모든 데이터 소스는 공공의 공유 자원입니다.

스택: React 18 + TypeScript + Vite + Tailwind, Leaflet, @mlc-ai/web-llm (지연 로딩), SunCalc, Vitest, 그리고 헤드리스 Chromium에서 실제 앱을 구동하는 의존성 없는 CDP 스모크 테스트 하네스(scripts/smoke.mjs)가 포함되어 있습니다 — 가짜 GPS 잠금, 경로 합성, GPX 다운로드 및 XML 유효성 검사가 포함됩니다.

제가 가장 자랑스러운 부분은 녹지 공간 검색 기능인데, 공공 오픈 인프라가 불안정할 수 있기 때문에 앱이 절대 실패해서는 안 됩니다 — 이 기능은 세 개의 Overpass 미러를 병렬로 실행하고, 2.5초 내에 응답하는 곳이 없으면 Nominatim(완전히 별개의 OSM 서비스)으로 전환하며, 재시도한 후 비로소 합성 공원으로 대체합니다:

// 첫 번째 성공적인 답변을 채택; 고장 난 미러가 경로 생성을 지연시킬 수 없습니다.
const winner = await firstSuccess<GreenSpaceLookup>([overpassWave, nominatimWave]);
if (winner) {
...

구축 방법

AI 코어는 휴대폰의 GPU에서 네이티브로 실행되는 오픈 웨이트 모델이며 WebLLM (WebGPU)을 통해 구현되었습니다:

• 모델: SmolLM2-360M-Instruct (양자화됨, 브라우저에 약 250 MB 캐시) — src/services/webgpu-llm.ts의 상수 하나를 변경하여 Qwen2.5-0.5B/1.5B-Instruct로 교체 가능합니다.
• 프롬프트 아키텍처: 앱은 구조화된 JSON 다이제스트(활동, 거리, 통과한 녹지 공간, 지표면 혼합, 태양 각도, 시간대)를 생성하고, 온디바이스 모델이 이를 3부분의 자연가이드 브리핑으로 변환합니다: 식생 하이라이트, 지표면 및 발걸음 조언, 마인드셋 큐 ("이어버드는 두고 오세요...").
• 블로킹 없음: WebGPU를 사용할 수 없거나 모델이 아직 다운로드되지 않은 경우에도, 결정론적(deterministic) 템플릿 생성기가 즉시 브리핑을 생성합니다 — 30초 예산은 절대적입니다. 가중치(weights)가 IndexedDB에 캐시되면, 트레일에서 완전히 오프라인으로 브리핑이 작동합니다.

모델 주변에는 개방형 지리공간 파이프라인(open geospatial pipeline)이 자리하고 있습니다: Overpass API + Nominatim (녹지 공간 탐색), OSRM foot + Valhalla (보행자 스내핑), SunCalc (태양 기하학), 그리고 직접 구현한 **GPX 1.1 직렬화기(serializer)**입니다. 이 모든 것은 서비스 워커를 갖춘 정적 PWA이며 — 어디든 배포 가능하고 영원히 무료입니다.

테스트: 29개의 vitest 단위 테스트(루프 기하학, 폴리라인 디코딩, GPX, 미러 레이스 폴백 등)와 헤드리스 브라우저 스모크 테스트가 있으며, 이 두 가지 모두 푸시할 때마다 CI에서 실행됩니다.

개방형 혁신은 왜 중요할까요?

LeafPace의 양쪽 절반 모두가 개방형 인프라 덕분에 존재할 수 있었기 때문이며, 각 부분은 사용자에게 더 나쁠 폐쇄형 API 버전이 있습니다:

• 오픈 지리 공간 공공재 (Open geospatial commons): 독점 지도 API는 요청 건당 비용을 청구하며 차량에 최적화되어 있습니다. OpenStreetMap에는 Google이 절대 순위를 매기지 않은 숲 속의 비포장 길이 존재합니다. 메인 Overpass 미러가 빌드 도중 저에게 속도 제한(rate-limited)을 걸었을 때, 저는 신용카드 청구서를 읽는 대신 두 개의 커뮤니티 미러와 두 번째 오픈 서비스(Nominatim)를 이용해 빠르게 진행할 수 있었습니다. 이는 공공재에 의해 구축되고, 공공재로부터 나오는 회복력입니다.
• 오픈 가중치 모델 (Open-weight models): 당신의 달리기 경로는 현관문에서 시작합니다. 그 프롬프트를 폐쇄된 LLM API로 보내는 것은 정밀한 집 좌표 지문을 함께 업로드하는 것을 의미합니다. WebGPU와 오픈 가중치는 전체 추론 과정—그리고 전체 위치 기록—을 물리적으로 휴대폰에 유지하며, 셀 범위 밖에 있을 때도 작동하게 합니다.
• 서버 제로, 비용 제로 (Zero server, zero cost): 유출할 사용자 트랙 데이터베이스가 없고, 종료할 청구서도 없습니다. 무료 정적 호스팅의 오픈 소스 PWA는 완벽한 제품입니다.

수상 부문 (Prize Categories)

이것에 관련된 모든 부문에 출품합니다—최종 카테고리 이름은 챌린지 페이지에서 확인해 주세요:

• 오픈 가중치 AI (Open-Weight AI) — SmolLM2 / Qwen2.5를 WebLLM을 통해, 완전한 온디바이스(on-device)로 구동
• 엣지/로컬 추론 (Edge / Local Inference) — 모바일 브라우저의 WebGPU, 첫 모델 다운로드 후 오프라인 사용 가능
• 개인 정보 보호 및 데이터 주권 (Privacy & Data Sovereignty) — 백엔드 제로; 위치는 절대 기기를 벗어나지 않음
• 오픈 지리 공간 공공재 (Open Geospatial Commons) — OpenStreetMap Overpass/Nominatim + OSRM/Valhalla

AI 사용 여부 (Use of AI)

이 프로젝트를 만드는 데 AI가 사용되었습니다. 온디바이스 브리핑 모델(SmolLM2-360M-Instruct)은 제작자에 의해 배포되는 오픈 가중치 모델이며—앱의 전제 자체가 위치 데이터는 절대 기기를 벗어나지 않아야 하므로, 어느 시점에서도 폐쇄적이거나 독점적인 LLM API는 사용되지 않았습니다.