EcoQuest | 해크토버페스트 주차 프로젝트

이것은 [Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass]에 제출하는 작품입니다.

제가 구축한 것

사람들은 매일 동네, 지역 공원, 야외 산책로를 거닐며 생활합니다. 그들은 넘쳐나는 쓰레기통, 무단 투기가 된 녹지 공간, 불법 폐기물 투기 현장, 또는 오염된 수로 등을 목격하지만, 보통은 스크롤을 지나치거나 해결할 방법이 없어 무력감을 느낍니다.

EcoQuest는 Hacktoberfest 2026 Week 1 "Touch Grass" 챌린지를 위해 구축된 모바일 우선(mobile-first), 커뮤니티 주도형 환경 활동 웹 애플리케이션입니다. 이 앱의 목표는 간단합니다. 사람들이 야외에서 관찰한 내용을 30초 이내에 구체적이고 실행 가능한 지역사회 보고서로 전환하도록 돕는 것입니다.

환경 관리 책임을 관료적인 지연이나 수동적인 소셜 미디어 불만 제기에 맡기는 대신, EcoQuest는 문제 발견과 안전하게 조치를 취하는 것 사이에 즉각적인 연결 고리를 제공합니다.

주요 기능

• 📱 모바일 우선 야외 사용자 경험(Mobile-First Outdoor UX): 빠른 카메라 캡처, 드래그 앤 드롭 파일 업로드, 반응형 카드 레이아웃, 터치 친화적 컨트롤을 갖추어 실제 야외 사용에 최적화되었습니다.

• 🌿 스마트 분류(Smart Categorisation): 보고서를 다음 5가지 주요 야외 카테고리로 분류합니다.

  • 쓰레기 및 잔해물 (Litter & Debris)
  • 넘쳐나는 공공 쓰레기통 (Overflowing Public Bins)
  • 방치된 녹지 공간 (Neglected Green Spaces)
  • 수질 오염 (Water Pollution)
  • 불법 투기 (Illegal Dumping)

• 🛡️ 신뢰도 및 정직한 불확실성 고지(Confidence & Honest Uncertainty Disclaimers): AI가 생성한 결과는 결코 절대적인 진실로 간주되지 않습니다. 모든 보고서에는 명시적인 신뢰 점수와, 그 결과가 독립적으로 검증된 것이 아닌 자동화된 제안임을 알리는 불확실성 고지가 표시됩니다.

• 👷 안전한 다음 행동 지침(Safe Next-Action Guidance): 즉각적이고 안전을 최우선으로 하는 권장 사항을 제공합니다 (예: "찢어짐 방지 장갑 착용," "유해 대량 품목은 시청에 신고," "작은 동네 청소 활동 조직").

• 🔄 커뮤니티 액션 워크플로우 (Community Action Workflow): 명확한 라이프사이클 상태(Open ➔ In Progress ➔ Resolved)를 추적하는 실시간 커뮤니티 피드를 제공하여, 이웃들이 문제 해결에 주도적으로 참여하고 완료된 청소 활동을 기념할 수 있도록 합니다.

• 🔒 개인정보 보호 아키텍처 (Privacy-Preserving Architecture): HTML5 Canvas를 통해 엄격하게 클라이언트 측 EXIF 정보를 제거함으로써, 가정 좌표나 카메라 메타데이터가 실수로 유출되는 것을 방지합니다. 위치 정보는 일반적이며 사용자 설명에 의존하며(침해적인 GPS 추적 없음), 개인정보 보호에 중점을 둡니다.

• ⚡ 제로 장벽 샘플 데이터 모드 (Zero-Barrier Sample Data Mode): 외부 API 키가 전혀 필요하지 않아, 별도의 설정 없이 오프라인 상태에서도 즉시 작동합니다. 따라서 어디서든 앱을 100% 테스트하고 시연할 수 있습니다.

데모 (Demo)

• 로컬 실행 앱 (Local Running App): http://localhost:5173에서 접근 가능
• 커버 아트 및 비주얼 (Cover Art & Visuals): public/cover.jpg (저장소에 포함됨)

로컬에서 실시간 인터랙티브 데모를 실행하려면:

git clone <YOUR-GITHUB-REPO-URL>
cd Hacktoberfest-Week1
npm install
...

http://localhost:5173에 접속하여 **"샘플 로드 (Load samples)"**를 클릭하면, 인터랙티브 피드가 즉시 채워지고, 새로운 카메라 보고서를 제출하며, 상태 전환을 테스트할 수 있습니다.

코드 (Code)

• 저장소 (Repository): https://github.com/balabhadra3141/Hacktoberfest-Week1
• 라이선스 (License): MIT License

제작 과정 (How I Built It)

EcoQuest는 현대적이고, 성능이 뛰어나며, 개인정보 보호를 최우선으로 하는 웹 도구들로 설계되었습니다:

기술 스택 (Tech Stack)

• 프론트엔드 (Frontend): React 19, TypeScript, Vite, Tailwind CSS v4, Lucide React, date-fns
• 백엔드 프록시 (Backend Proxy): 경량 Node.js 서버 (API 키를 완전히 서버 측에 유지)
• 저장소 (Storage): 영구적인 CRUD 상태 관리를 갖춘 브라우저 LocalStorage

교체 가능한 AI 아키텍처 (AIProvider 패턴)

EcoQuest의 핵심 설계 원칙은 UI가 AI 제공자(AI provider)로부터 완전히 분리되어 있다는 것입니다. src/lib/providers.ts에서 모든 모델 상호작용은 엄격한 계약을 따릅니다:

export interface AIProvider {
  name: string;
  isOpenWeight: boolean;
...

이 인터페이스는 두 가지 교체 가능한 운영 모드를 활성화합니다:

1. Sample Provider (기본값): API 키나 네트워크 지연 없이 현실적인 분석을 시뮬레이션하는 결정론적(deterministic), 제로-의존성 오프라인 엔진입니다.
2. Vision-Language Provider (프로토타입): 백엔드 서버를 통해 Google Gemini 1.5 Flash를 호출하는 경량 프록시입니다. API 키는 .env.local에 안전하게 저장되며 클라이언트에게 절대 노출되지 않습니다.
3. 플러그 가능한 오픈 가중치 모델 (Pluggable Open-Weight Models): LLaVA-1.6, InternVL2, 또는 CLIP과 같은 자체 호스팅(self-hosted) 오픈 가중치 비전 모델로 교체되도록 특별히 설계되었습니다.

오픈 혁신이 중요한 이유 (Why Does Open Innovation Matter?)

환경적 과제는 근본적으로 지역적이고, 공유되며, 커뮤니티가 소유합니다. 폐쇄적이고 독점적인 AI를 기반으로 환경 인프라를 구축하는 것은 심각한 위험을 초래합니다:

1. 커뮤니티 데이터 주권 (Community Data Sovereignty): 시민들이 공공 문제를 기록할 때, 그 데이터는 커뮤니티와 지역 당국에 속해야 하며 — 독점적인 학습 데이터셋으로 흘러 들어가거나 상업적 페이월 뒤에 인질로 잡혀서는 안 됩니다.
2. 감사 가능성 및 알고리즘 신뢰 (Auditability & Algorithmic Trust): AI 모델이 보고서를 우선순위화하거나 하향 조정할 경우, 시민들은 프롬프트와 가중치를 검사할 권리가 있습니다. 오픈 가중치 모델을 사용하면 커뮤니티 구성원이 시스템을 감사하여 소외된 지역에 편향되지 않도록 보장할 수 있습니다.
3. 지속 가능성 및 독립성 (Longevity & Independence): 상업적 API 엔드포인트는 언제든지 폐기(deprecated)되거나, 속도 제한이 걸리거나, 가격 인상이 발생할 수 있습니다. 오픈 가중치 모델은 커뮤니티 도구가 시간이 흘러서도 지역 하드웨어에서 계속 실행되도록 보장합니다.
4. 제로-텔레메트리 개인 정보 보호 (Zero-Telemetry Privacy): 환경 보고서에는 공공 도로 또는 공원의 배경 이미지가 자주 포함됩니다. 오픈 가중치 비전 모델을 로컬 또는 커뮤니티 서버에서 실행하면 민감한 공간 이미지(spatial imagery)가 지방 경계를 벗어나지 않습니다.

오픈 혁신은 기술이 사적인 게이트키핑(gatekeeping)이 아닌 공공 인프라 역할을 하도록 보장합니다.

나의 에이전트 세션 (My Agent Session)

이 프로젝트는 고급 에이전트식 코딩 페어 프로그래밍 워크플로우를 사용하여 반복적으로 구축되었습니다:

• 신속한 아키텍처 설계, 도메인 모델 초안 작성 및 스키마 정의.
• 강력한 유효성 검사(validation), 오류 상태 처리, 그리고 EXIF 제거를 통한 정제(sanitization) 개발.
• 프론트엔드 상태와 백엔드 프록시 추론(inference) 간의 엄격한 분리 구현.
• 전체 TypeScript 검사 및 경고 없음(zero warnings)으로 빌드를 테스트하고 검증.

수상 부문 (Prize Categories)

• 주요 부문(Primary): Hacktoberfest 오픈소스 AI 챌린지 1주차: "풀밭에 발을 디디다 (Touch Grass)"
• 개인 제출(Individual Submission): 개별적으로 생성 및 제출.

오픈소스 혁신을 장려하고 개발자들이 밖에 나가 풀밭에 발을 디디도록 영감을 준 Hacktoberfest 및 DEV 팀에게 감사드립니다!