🌿 GreenQuest: 스마트폰에서 벗어나게 하는 AI 아웃도어 어드벤처 플래너

🌱 서론

우리는 화면을 응시하며 시간을 보냅니다.

끝없는 슬랙(Slack) 알림, 부정적인 소식을 찾아보는 소셜 피드 스크롤링, 심지어 새로운 대화형 AI 챗봇의 물결 속에서, 현대 디지털 경제는 단 하나의 지표에 끊임없이 최적화되어 있습니다: 스크린 시간 극대화.

그래서 저는 Hacktoberfest 2026 Week 1 "풀잎 밟기(Touch Grass)" DEV 챌린지를 위해 정반대의 AI를 만들기로 결정했습니다.

당신에게 또다시 빛나는 유리 직사각형에 붙어있을 이유를 주기보다는, GreenQuest는 당신이 기기를 치우고 물리적인 세상으로 나설 구조화된 이유를 제공합니다.

GreenQuest는 Google의 오픈 웨이트(open-weight) 모델인 Gemma를 기반으로 구축된 오픈 소스 AI 기반 아웃도어 활동 플래너입니다. 사용자가 현재 위치와 가용 시간을 알려주면, 이 앱은 시간 제한이 있는, 감각적으로 풍부한 마이크로 어드벤처를 합성해줍니다.

계획이 준비되면, 이 앱은 급진적인 행동을 합니다: 사용자에게 휴대폰을 주머니에 넣고, 화면을 닫고, 밖에 나가라고 알려줍니다.

🎯 문제점

결정 마비(Decision paralysis)가 우리를 실내에 머물게 합니다.

공부 시간이나 회의 사이에 여유로운 30분 또는 45분이 생겼을 때, 기본 행동은 거의 항상 수동적입니다: 브라우저 탭 열기, 피드 스크롤링, 또는 AI 챗봇에게 사소한 질문하기.

심지어 우리가 밖에 나가고 싶을 때도, 일반적인 질문들은 마찰을 일으킵니다:

"어디를 걸어야 할까요?"
"의미 있는 무언가를 하기에 30분으로 충분할까요?"
"무엇에 주의를 기울여야 하나요?"

전통적인 피트니스 및 트레일 앱들은 종종 문제를 더 악화시킵니다. 이 앱들은 방향별 지도 보기, 실시간 소셜 공유, 알림 배지 등 지속적인 화면 상호작용을 요구하기 때문입니다.

도전 과제는 단순히 아웃도어 아이디어를 생성하는 것이 아니었습니다. 도전 과제는 오픈 웨이트 AI를 완전히 방해 요소가 아닌 신속한 촉매제로 사용하는 것이었습니다.

💡 아이디어

GreenQuest는 "반(Anti)-스크린 AI" 철학을 중심으로 설계되었습니다:

60초 이내 디지털 발자국: 계획 수립 시간이 1분도 걸리지 않습니다. 사용자가 매개변수를 입력하고, 계획을 얻고, 나갑니다.
픽셀 피드보다 감각적 마음챙김(Sensory mindfulness): 모든 계획 단계는 신체 활동과 특정 감각 프롬프트(예: 새소리 듣기, 나무껍질 만져보기, 바람 패턴 관찰하기)를 결합합니다.
어드벤처 모드의 의도적인 미니멀리즘: 퀘스트를 시작하면 UI가 모든 잡다한 요소를 제거하고 현재 작업과 깔끔한 타이머만 표시합니다.
"폰은 내려놓고, 어드벤처에 집중.": 전용 알림 및 활성화된 **포켓 모드(Pocket Mode)**는 돌아올 때까지 휴대폰을 치워두도록 장려합니다.

🌿 GreenQuest 작동 방식

화면에서 땅으로 이어지는 정확한 여정은 다음과 같습니다:

[사용자 입력]
  위치 + 시간 (10-180m) + 활동 + 체력 수준 + 감각 초점
          │
...

입력: 사용자는 설정(예: Bhimavaram 자연 트레일, 도시 공원, 또는 지역 동네), 이용 가능한 시간(15분, 30분, 45분, 60분 이상), 활동(걷기, 달리기, 정원 가꾸기, 조류 관찰, 자연 탐험, 자전거 타기), 그리고 자연 초점(토착 식물, 음향 노래, 흙 접지)을 선택합니다.
Gemma 합성: Gemma는 감각 워밍업, 지형 탐험, 마음챙김 관찰 단서 및 쿨다운을 포함하는 균형 잡힌 다단계 야외 계획을 수립합니다.
구조화된 계획: 사용자는 일정을 검토하고, **짐 목록(Pack Checklist)**의 항목을 체크하거나, **오프라인 시트 인쇄(Print Offline Sheet)**를 눌러 실제로 종이를 가져가 휴대폰을 뒤에 남겨둘 수 있습니다.
어드벤처 모드: 시작하면 앱은 높은 대비의 카운트다운 타이머를 표시하고 다음과 같이 상기시킵니다: > “계획이 준비되었습니다. 이제 앱을 닫고 밖에 나가세요. 완료되면 다시 확인하세요.”
포켓 모드 및 웹 오디오 차임: **포켓 모드(Pocket Mode)**를 탭하여 화면을 완전히 검은색으로 어둡게 만들어 배터리를 절약하고 화면 유혹을 제거합니다. 단계 시간이 끝날 때마다, 사용자가 화면을 내려다볼 필요가 없도록 Web Audio API를 통해 주변 브라우저 음이 울립니다.

기록 (Grounding Log): 돌아온 후에는 연결이 끊어졌을 때의 느낌을 기록하고, 성찰 내용을 작성하며, **화면 없는 시간 증가량(Screen-Free Hours Gained)**과 **잔디 접촉 점수(Grass Touched Score)**를 추적합니다.

🤖 왜 Gemma인가?

이 과제는 오픈 웨이트(open-weight), 오픈 소스 AI 모델을 사용하여 구축해야 했습니다. Google Gemma는 몇 가지 핵심적인 이유로 이상적인 선택이었습니다:

오픈 웨이트 및 로컬 배포: Gemma 모델(gemma-2-2b-it 및 gemma-2-9b-it)은 Ollama 또는 서버리스 오픈 소스 제공업체를 통해 소비자 하드웨어에서 로컬로 실행할 수 있으며, 이 과정에서 개인 위치 데이터를 독점 기업에 전송하지 않습니다.
엄격한 지침 준수: 명령어 튜닝된 Gemma 2를 사용함으로써, 대화식 채우기나 서론 없이 우리의 Pydantic 데이터 계약과 일치하는 엄격하게 검증된 JSON을 출력하도록 모델을 유도할 수 있습니다.
경량 및 빠름: Gemma 2 2B는 거의 즉각적인 추론 지연 시간(inference latency)을 제공하여, 사용자가 긴 생성 지연 시간을 기다릴 필요 없이 몇 초 만에 어드벤처 계획을 생성할 수 있게 합니다.
폐쇄형 소스 AI 없음: 애플리케이션 어디에도 OpenAI 의존성이 없습니다.

🏗️ 기술 아키텍처

코드베이스는 모듈식 프론트엔드와 백엔드로 깔끔하게 분할되어 있습니다:

├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI 엔드포인트 및 CORS
...

모듈식 AI 레이어

백엔드는 추상적인 제공자 인터페이스(BaseGemmaProvider)를 구현합니다:

HuggingFaceGemmaProvider: 서버리스 엔드포인트를 통해 google/gemma-2-2b-it을 호출하기 위해 huggingface_hub.InferenceClient를 사용합니다.
OllamaGemmaProvider: 100% 오프라인, 로컬 GPU/CPU 실행(gemma2:2b)을 위해 http://localhost:11434에 연결합니다.
MockGemmaProvider: API 키나 GPU 하드웨어 없이도 빠른 UI 반복(iteration), 테스트 및 평가를 가능하게 하는 오프라인 결정론적 대체 엔진입니다.

🛠️ 기술 스택

프론트엔드 (Frontend): React 19, TypeScript, Vite, Tailwind CSS v4, Lucide Icons, Canvas-Confetti
백엔드 (Backend): Python 3.11, FastAPI, Pydantic v2, Uvicorn
데이터베이스 (Database): SQLite (내장형, 영속성, 외부 의존성 없음)
AI 모델: Google Gemma 2 Open-Weight (google/gemma-2-2b-it / gemma2:2b)
테스트 및 품질 관리 (Testing & Quality): Pytest, Oxlint (경고 0개, 오류 0개)

🚀 데모 및 코드 저장소 (Demo & Code Repository)

GitHub 저장소: https://github.com/anuuu2507/GreenQuest
로컬 실행 (Local Run):
- 프론트엔드: http://localhost:5173
- 백엔드 API 및 Swagger: http://127.0.0.1:8000/docs

📸 워크스루 (Walkthrough)

1. 랜딩 페이지 — "풀잎을 만지다" 선언문 (The "Touch Grass" Manifesto)

미션 설명, 활성화된 Gemma 모델 상태 표시, 그리고 원클릭 시작 영감(30분 자연 리셋, 60분 캐노피 조류 관찰, 45분 트레일 러닝)을 제공합니다.

Landing Page — The

2. 플래너 — 매개변수 설정 (Setting Parameters)

위치를 선택하고, 지속 시간 슬라이더(10분~180분), 활동 카드, 그리고 감각 집중 태그를 설정합니다. AI 생성 중에는 회전하는 마음챙김 로더가 표시됩니다.

The Planner — Setting Parameters

3. 계획 개요 및 오프라인 인쇄 시트 (Plan Overview & Offline Print Sheet)

AI가 생성한 일정, 준비물 체크리스트, 안전 알림과 함께, 휴대폰을 집에 두고 갈 수 있도록 브라우저 최적화 오프라인 인쇄 시트 버튼을 제공합니다.

Plan Overview & Offline Print Sheet

4. 어드벤처 모드 및 포켓 모드 (Adventure Mode & Pocket Mode)

매우 미니멀한 인터페이스에 큰 카운트다운 타이머, 현재 과제(current task), 진행률 표시줄(progress bar), 오디오 알림음(audio chime) 및 눈을 자연에 고정할 수 있도록 디스플레이를 검게 만드는 **포켓 모드(Pocket Mode)**가 특징입니다.

Adventure Mode & Pocket Mode

5. 어드벤처 및 임팩트 대시보드 (Adventures & Impact Dashboard)

총 야외 활동 시간, 화면 없는 시간 확보(Screen-Free Hours Gained), 완료한 퀘스트 수, 그리고 **풀 접촉 점수(Grass Touched Score)**를 추적합니다.

Adventures & Impact Dashboard

🌳 GreenQuest를 야외에서 사용해 보기 (I Took GreenQuest Outside)

실제 환경에서 프로젝트를 테스트하기 위해 Bhimavaram 자연 트레일을 위한 **45분 자연 탐험 퀘스트(Nature Exploration Quest)**를 생성했습니다:

1단계 (5분) — 감각적 도착(Sensory Arrival): 길에 발을 디디기 전, 호흡을 조절하고 주변 새소리를 들었습니다.
2단계 (17분) — 탐험(Exploration): 휴대폰을 주머니에 넣고 트레일을 걸었습니다.
3단계 (17분) — 식물학 및 토양 집중(Botanical & Soil Focus): 토종 나무 근처에서 멈춰서 나뭇잎 질감을 관찰하고 산들바람을 느꼈습니다.
4단계 (6분) — 냉각 및 성찰(Cooldown & Reflection): 벤치에 앉아 쉬면서 깊은 숨을 세 번 쉬었고, 알림을 확인하지 않고 마음을 가라앉혔습니다.

돌아와서 퀘스트 완료를 표시하는 것은 일반적인 앱 사용과는 확연히 달랐습니다. 평소의 화면 후 인지적 피로감(post-screen cognitive fatigue)을 느끼지 못했습니다. 대신, 화면 없는 시간 45분을 기록했고 진정으로 상쾌함을 느꼈습니다.

🔓 오픈 혁신이 중요한 이유 (Why Open Innovation Matters)

폐쇄적인 독점 API를 사용하는 것보다 Google Gemma와 같은 **오픈 가중치 모델(open-weight model)**을 선택한 것은 의도적인 설계 결정이었습니다:

진정한 프라이버시 (True Privacy): Ollama를 통해 Gemma를 로컬에서 실행할 때, 사용자의 위치, 일정 또는 습관과 같은 개인 데이터는 단 하나의 바이트도 기기를 벗어나지 않습니다.
API 종속성으로부터의 자유 (Freedom from API Lock-In): 독점적인 API는 이용 약관을 변경하거나, 가격을 인상하거나, 엔드포인트를 하룻밤 사이에 폐기할 수 있습니다. 오픈 웨이트 모델은 영원히 접근 가능하고 재현할 수 있습니다.
모듈식 확장성 (Modular Extensibility): BaseGemmaProvider 추상화는 개발자가 애플리케이션 코드를 변경하지 않고도 로컬 Ollama 추론, 양자화된 엣지 웨이트(quantized edge weights), 또는 호스팅 서버리스 엔드포인트 간에 쉽게 전환할 수 있도록 합니다.
커뮤니티의 신뢰 (Community Trust): 오픈 혁신은 오픈 소스 커뮤니티가 모델의 동작을 검사하고 애플리케이션이 정직하게 작동하는지 확인할 수 있게 합니다.

🧠 직면했던 과제 (Challenges I Faced)

오픈 웨이트 LLM으로부터 엄격한 JSON 강제하기: LLM은 자연스럽게 _"다음은 당신의 아웃도어 계획입니다:"_와 같은 대화형 서문(conversational preambles)으로 기본 설정됩니다. 저는 스키마 제약 조건이 포함된 시스템 프롬프트를 설계하고, 마크다운 울타리(markdown fences)를 정리하고 개별 단계 지속 시간을 정규화하여 사용자가 요청한 시간에 정확히 합산되도록 하는 강력한 파서를 결합했습니다.
스크린 사용을 저해하는 UI 디자인: 표준 웹 디자인 원칙은 사용자 유지 및 클릭에 최적화되어 있습니다. 사용자가 시선을 돌리도록 적극적으로 유도하는 인터페이스를 구축하려면 UX(사용자 경험) 재고가 필요했습니다. 포켓 모드(Pocket Mode) 추가, 핸즈프리 단계 알림을 위한 웹 오디오 톤(Web Audio tones) 통합, 그리고 원클릭 인쇄 시트를 제공하는 것이 포함됩니다.
SQLite에서의 테스트 격리 (Test Isolation): 백엔드 테스트 스위트 개발 중, SQLite의 인메모리 모드는 연결할 때마다 새로운 독립적인 데이터베이스를 생성했습니다. 저는 PlanStorage를 리팩토링하여 테스트 시에는 깨끗한 인메모리 연결 풀링(in-memory connection pooling)을 유지하고 프로덕션에서는 파일 기반 스토리지를 사용하도록 했습니다.