혹시 밖에 나가서 자연과 연결하고, 익숙한 영역을 벗어나 탐험해 보고 싶다고 생각해 본 적 있나요?

저도 그랬습니다. 그리고 단순히 생각에 그치지 않고, 실제로 그것을 실현하기 위해 무언가를 만들기로 결심했습니다.

이것은 제가 NaturalDex를 구축한 이야기입니다. 제가 해결하고 싶었던 문제, 접근했던 아키텍처 방식, 선택한 기술 스택, 과정에서 마주쳤던 기술적 난관들, 그리고 이 과정을 통해 배운 것들에 대한 내용입니다.

이 프로젝트는 Hacktoberfest 2026을 거치며 진행된 저의 여정의 일부로, 야외 탐험이라는 개념을 완전히 기능하는, 프라이버시 우선 애플리케이션으로 구현하는 방법을 탐구했습니다.

문제점 (The Problem)

현대의 스크린 중독과 끊임없는 부정적인 정보(doomscrolling) 소비는 집중력을 저하시키고 사람들을 실내에 머물게 합니다. '풀밭 밟기(Touch Grass)'라는 마인드를 염두에 두고, 저는 화면 사용 시간을 최소화하면서 자연 세계에 대한 진정한 호기심을 키워주는 애플리케이션을 만들고 싶었습니다.

목표는 사용자들에게 편안한 영역을 벗어나 지역 환경을 탐험하고, 실제 종(species)을 식별하며, 보람 있는 방식으로 현장 지식을 얻도록 장려함으로써 야외 탐험을 흥미롭게 만드는 것이었습니다.

이것이 NaturalDex의 설립 비전이 되었습니다.

작동 모습 (Here It Is in Action) 🎬

🎥 위의 미리보기를 클릭하여 YouTube에서 프로젝트 시연 영상을 시청하세요.

• 코드 살펴보기:

GitHub logo KevinForsgren / NaturalDex

종(species) 식별 및 수집을 통해 자연 탐험을 장려하는 현장 일지이자 야외 수집 게임입니다. 개인 정보 보호를 최우선으로 하며 오프라인 사용이 가능한 아키텍처로 구축되었습니다.

NaturalDex

종(species) 식별 및 수집을 통해 자연 탐험을 장려하는 현장 일지이자 야외 수집 게임입니다. 개인 정보 보호를 최우선으로 하며 오프라인 사용이 가능한 아키텍처로 구축되었습니다.

개요 (Overview)

NaturalDex는 야외 관찰 활동을 수집 게임으로 바꿉니다. 사용자는 현장에서 식물, 동물 또는 균류의 사진 3장을 촬영하고, 연결된 홈 베이스(Ollama가 실행되는 노트북)를 통해 로컬 AI로 제출하여 식별하며, 발견한 종 카드로 개인 현장 일지를 구축합니다.

아키텍처 (Architecture)

• 백엔드 (Backend): FastAPI + SQLAlchemy 2.0 + Pydantic v2 (Python 3.14+)
• 프론트엔드 (Frontend): React 18 + Vite 6 + TailwindCSS v4 + React Router 6
• 데이터베이스 (Database): SQLite (로컬 파일)
• AI: 연결된 홈 베이스에서 Ollama를 통한 로컬 추론(Local inference) (클라우드 의존성 없음)
• 인증 (Auth): HttpOnly 쿠키의 JWT + Argon2 비밀번호 해싱

기능 (Features)

• 일일 현장 과제 (Daily field tasks) — 하루에 개인화된 3가지 과제 (식물/동물/균류 카테고리)
• 사진 3장 발견 흐름 (Three-photo discovery flow) — 정확한 ID를 위해 여러 각도의 사진 촬영
• 로컬 AI 식별 (Local AI identification) —...

GitHub에서 보기

모바일 UI

[

핵심 기능 및 경험 (Core Features & Experience)

목표는 간단했습니다. 클라우드 개인 정보 보호 문제나 지나치게 복잡한 설정에 의존하지 않으면서 게임화된 자연 발견을 시연하는 작동 가능한 프로토타입을 구축하는 것이었습니다.

현재 애플리케이션이 제공하는 기능은 다음과 같습니다:

• 일일 현장 과제 (Daily Field Tasks): 매일 세 가지 개인 맞춤형 과제를 받습니다(식물, 동물, 균류 범주 포함). 이는 사용자가 외출하여 지역 생물 다양성을 관찰하도록 장려합니다.
• 3-사진 발견 흐름 (3-Photo Discovery Flow): 사용자는 현장에서 식물, 동물 또는 균류의 세 가지 각도를 촬영하여 로컬 비전 AI에 입력하고 정확한 종을 식별합니다.
• 포켓몬 도감 스타일 현장 일지 및 XP: 발견된 종은 안정적인 URL을 가진 수집형 카드를 잠금 해제하며, 이는 레벨링과 XP 진행이 있는 개인 현장 일지에 새로운 항목을 추가합니다.
• 개인 정보 보호 우선 로컬 AI (Privacy-First Local AI): 외부 클라우드 의존 없이 오프라인으로 작동합니다. 이미지 분류는 Ollama를 사용하여 사용자의 홈 노트북에서 직접 실행됩니다.

제가 구축한 것 (What I Built)

핵심적으로 NaturalDex는 로컬 AI와 자체 호스팅 아키텍처(self-hosted architecture)로 구동되는 모바일 우선 웹 애플리케이션이며, 야외 산책을 개인적인 자연사 탐험으로 바꾸도록 설계되었습니다.

1. 자연 카드 수집 (Nature Card Collection)

사용자는 주변의 식물, 동물, 균류를 식별하여 종 카드를 수집합니다. 각 카드는 일반명과 학명을 표시하며, 기록된 위치, 종 요약 정보 및 흥미로운 생물학적 사실을 담고 있습니다.

2. 플레이어 XP 및 진행 시스템 (Player XP & Progression System)

장기적인 야외 습관을 장려하기 위해 NaturalDex는 플레이어 XP 메커니즘을 통합했습니다. 사용자는 일일 과제를 완료하고 새로운 종 관찰 기록을 남김으로써 XP를 얻고, 자연 산책을 보람 있는 진행 과정으로 바꿉니다.

3. 사려 깊은 사용자 경험 (Thoughtful User Experience)

훌륭한 콘셉트는 직관적인 인터페이스를 필요로 합니다. 주요 UX 디자인 선택 사항에는 다음이 포함됩니다:

• 반응형 모바일 우선 UI: 모바일 핸드헬드 카메라 촬영에 최적화되었으며 데스크톱에서도 접근 가능합니다.
• 원활한 홈 베이스 페어링: QR 코드 페어링을 통해 모바일 브라우저 클라이언트를 LAN 또는 ngrok 터널을 거쳐 홈 베이스 Ollama 인스턴스에 연결합니다.
• 명확한 피드백: 다중 사진 업로드, 비전 AI 추론(vision AI inference), 카드 생성 과정에서 정보 제공적인 상태를 보여줍니다.
• 통일된 미학: TailwindCSS v4로 디자인된 깨끗하고 자연스러운 시각적 언어입니다.

제작 방법 (How I Built It)

기술 스택 (The Tech Stack)

프론트엔드 구조 (The Frontend Structure)

프론트엔드는 발견(Discover), 수집(Collection), 일지(Journal), 프로필(Profile)과 같은 핵심 사용자 흐름을 중심으로 구성되어 관심사 분리(separation of concerns)를 명확히 합니다:

frontend/src/
├── App.jsx
├── components/
...

백엔드 및 발견 데이터 파이프라인 (Backend & Discovery Data Pipeline)

백엔드는 사진 제출, 비전 추론, 거부/정책 검증, 데이터베이스 업데이트, XP 지급을 조율합니다.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  폰 (Phone)  │────▶│  백엔드 (Backend) │────▶│  Ollama   │────▶│  백엔드 (Backend) │
│  (3 photos) │     │  (queue)    │     │  (vision)   │     │  (persist)  │
...

전용 API 클라이언트 패턴 (Dedicated API Client Pattern)

깨끗한 프론트엔드 아키텍처를 유지하기 위해, 백엔드 통신은 전용 API 유틸리티 모듈에 중앙 집중화되어 있습니다:

const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || "";

export async function getCollection() {
...

직면했던 과제 (Challenges I Faced)

1. 다중 사진 비전 AI 식별 (Multi-Photo Vision AI Identification)

Ollama 비전 모델을 통합하려면 공통 이름, 학명(scientific names), 신뢰도 수준(confidence levels), 품질 검사 등을 추출하기 위한 구조화된 JSON 출력이 필요했습니다. 사용자가 호환되지 않는 모델(예: 텍스트 전용 모델)을 실행했을 때의 비전 폴백 오류(non-vision fallback errors)를 처리하려면 services/vision.py에 엄격한 유효성 검사 정책이 요구되었습니다.

2. 네트워크 간 홈 베이스 QR 페어링 (Home Base QR Pairing Across Networks)

모바일 휴대폰 브라우저가 페어링된 노트북에서 실행되는 Ollama 인스턴스와 통신할 수 있도록 하려면 경량의 페어링 프로토콜이 필요했습니다. 저는 ngrok 터널링을 지원하는 도전-응답 QR 코드 페어링 흐름(/api/home-base/pairing-challenge)을 설계하여, 셀룰러 네트워크에 연결된 휴대폰이 로컬 Wi-Fi에 있는 노트북과 페어링할 수 있도록 했습니다.

3. Idempotency 및 XP 무결성

사진 업로드 시 중복 컬렉션 항목 생성을 방지하기 위해, 백엔드는 고유 관찰 연결(collection_card_observations)을 사용하여 카드 개수, XP 이벤트, 일일 과제 업데이트가 엄격하게 **멱등적(idempotent)**으로 유지되도록 합니다.

4. 범위 관리 (Managing Scope)

즉시 완전한 네이티브 모바일 앱을 출시하려 하기보다는, 핵심 식별 및 컬렉션 루프를 먼저 완벽하게 만들기 위해 오프라인 기능을 갖춘 반응형 웹 앱(PWA 아키텍처) 구축에 집중했습니다.

테스트 및 신뢰성 (Testing and Reliability)

백엔드 안정성과 신뢰성을 보장하기 위해, 주요 서비스 계층 전반에 걸쳐 Pytest를 사용하여 테스트가 구현되었습니다:

• API 엔드포인트 테스트: /api/auth, /api/discoveries, /api/collection, /api/daily-tasks, 그리고 /api/home-base에 대한 자동화된 라우트 유효성 검사.

• Vision 정책 확인: 저품질이거나 일치하지 않는 다중 사진 제출물에 대한 백엔드 거부 필터 검증.

• 데이터베이스 및 ORM 검증: SQLite를 사용하여 사용자, 카드, 종(species), XP 이벤트 테이블 간의 모델 관계 테스트.

• 수동 교차 장치 UX 확인: 휴대용 장치에서 카메라 피드, 모바일 뷰포트, QR 스캔 메커니즘을 검증했습니다.

로컬 실행 (Running It Locally)

필수 조건 (Prerequisites)

• Python 3.14+

• Node.js 18+

• Ollama (llava-phi3와 같은 Vision 모델 포함)

1. 리포지토리 클론 (Clone the Repository)

Bash

git clone https://github.com/KevinForsgren/NaturalDex.git
cd NaturalDex

2. 백엔드 설정 (Backend Setup)

Bash

cd backend
pip install -e

### 4. Ollama Vision AI 설정

Bash 

Ollama 설치 및 서비스 실행

ollama pull llava-phi3
ollama serve

루트 디렉터리에서 `.env.template`을 `.env`로 복사하세요:

Code snippet  

DATABASE_URL=./Database/naturedex.db
VISION_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
...

## 다음에 개선하고 싶은 부분 (What I Would Improve Next)

-   [ ] 프론트엔드를 네이티브 React Native / Expo 애플리케이션으로 변환하여 모바일 카메라 제어 기능을 개선합니다.
    
-   [ ] 깊은 야외 지역에서 셀룰러 수신 상태가 불안정할 때 사진 제출을 위한 오프라인 큐잉(offline queueing) 기능을 추가합니다.
    
-   [ ] 프론트엔드 훅 및 상태 컨텍스트 전반에 걸쳐 단위 테스트 커버리지(unit test coverage)를 확장합니다.
    
-   [ ] 사용자 위치 개인 정보 보호를 유지하면서 커뮤니티 카드 공유 기능을 추가합니다.
    

## 배운 점 (What I Learned)

NaturalDex를 구축하는 과정에서 AI 애플리케이션을 개발하는 것이 단순히 API 호출을 감싸는 것보다 훨씬 복잡하다는 것을 깨달았습니다. 여기에는 로컬 하드웨어 제약 조건, 강력한 데이터 유효성 검사(data validation), 사용자 개인 정보 보호, 그리고 효과적인 상태 관리(state management)를 오케스트레이션(orchestrating)하는 것이 필요합니다.

AI 코딩 에이전트와 작업하면서 또한 상세한 프롬프팅(prompting)의 중요성을 배웠습니다. 명시적인 상황적 제약 조건(explicit contextual constraints)을 가지고 모델을 엔지니어링 매니저처럼 안내하면 훨씬 우수한 아키텍처와 더 깔끔한 코드를 얻을 수 있습니다.

## 프로젝트 링크 (Project Links)

-   **GitHub 저장소**: [KevinForsgren/NaturalDex](https://www.google.com/url?sa=E&source=gmail&q=https://github.com/KevinForsgren/NaturalDex) 
    
-   **SNS / 연락처**: [X (@Kevin_Forsgren)](https://www.google.com/search?q=https://x.com/Kevin_Forsgren) | [GitHub 프로필](https://www.google.com/search?q=https://github.com/KevinForsgren)
    
-   **라이선스**: [GPL-3.0](https://github.com/KevinForsgren/NaturalDex?tab=GPL-3.0-1-ov-file) 
    

## 상금 부문 (Prize Categories)

-   General