mauriceboe/TREK 딥다이브
— 셀프호스팅 실시간 협업 여행 플래너의 풀스택 설계

1프로젝트 한줄 요약

TREK이 무엇을 하는 물건인가.

2왜 주목받는가

트렌딩 이유와 기존 솔루션 대비 차별점.

TREK이 TrendShift 상위권을 차지한 배경에는 세 가지 흐름이 맞물려 있다. 첫째, 데이터 주권 의식 — 구글·노션에 여행 데이터를 맡기기 싫다는 사람이 늘었다. 둘째, AI 여행 플래너 수요 — ChatGPT/Claude로 일정을 짜는 흐름이 커지면서, AI가 직접 앱 데이터를 읽고 쓸 수 있는 MCP 연동이 매력적이다. 셋째, Docker 셀프호스팅 생태계 — Unraid, TrueNAS, Proxmox 사용자들이 찾는 '올인원 여행 앱' 공백이 있었다.

3기술 스택 전체 지도

프론트엔드 / 백엔드 / DB / 인프라 각각 상세.

프론트엔드

백엔드

DB / 인프라 / 공유

4아키텍처 심화 분석

시스템 구조도와 핵심 설계 패턴 3가지.

전체 시스템 구조

핵심 설계 패턴 1 — 실시간 협업 (WebSocket)

TREK의 실시간 협업은 ws 라이브러리 기반 단순 WebSocket으로 구현된다. OT(Operational Transformation)나 CRDT 같은 복잡한 알고리즘 없이, 이벤트 브로드캐스트 방식을 사용한다.

핵심 설계 패턴 2 — 지도 이중화 전략

TREK은 두 가지 지도 엔진을 병렬로 지원한다. API 키 없이 쓸 수 있는 Leaflet(OSM)과, 3D 빌딩/지형이 필요할 때 쓰는 Mapbox GL이다. 사용자가 관리자 패널에서 선택하며, 지도 타일 소스도 직접 설정 가능하다.

핵심 설계 패턴 3 — 인증 레이어 (OIDC + 2FA + 패스키)

5디렉토리 구조 해부

npm workspace 모노레포 구조와 각 폴더의 역할.

6학습 포인트 (기술별)

TREK 코드베이스에서 배울 수 있는 기술과 실습 아이디어.

1. NestJS + Express 아키텍처

NestJS는 Angular에서 영감받은 DI(의존성 주입) 프레임워크다. TREK의 server/src/nest/를 보면 모듈-컨트롤러-서비스 삼층 구조를 실전에서 어떻게 쓰는지 배울 수 있다. 특히 미들웨어 체인(middleware/auth.ts → middleware/tripAccess.ts)이 HTTP 요청을 단계적으로 검증하는 패턴이 교과서적이다.

2. WebSocket 실시간 동기화

server/src/websocket.ts와 client/src/sync/가 쌍을 이룬다. "REST로 먼저 저장 → WS로 이벤트 브로드캐스트"라는 낙관적 업데이트 패턴을 배울 수 있다. React Suspense나 SWR 없이 Zustand 스토어를 WebSocket 이벤트로 직접 갱신하는 패턴도 흥미롭다.

3. PWA + 오프라인 전략

Vite에서 Service Worker를 Workbox로 생성하는 설정, Dexie(IndexedDB)로 오프라인 데이터를 캐시하는 패턴, 그리고 오프라인 중 쌓인 쓰기 작업을 온라인 복귀 시 동기화하는 흐름 — 이 세 가지를 TREK 코드에서 통째로 학습할 수 있다.

4. SQLite WAL 모드 + 마이그레이션

server/src/db/에는 SQLite을 WAL(Write-Ahead Logging) 모드로 열어 읽기 성능을 높이는 설정과, 마이그레이션 파일들이 있다. ORM 없이 better-sqlite3로 SQL을 직접 쓰면서도 타입 안전성을 유지하는 방법을 볼 수 있다.

5. MCP 서버 구현

server/src/mcp/는 AI MCP 서버를 직접 구현하는 실전 사례다. @modelcontextprotocol/sdk로 150개 이상의 도구를 정의하고, OAuth 2.1로 보호하는 전체 흐름을 배울 수 있다. MCP를 배우고 싶은 사람에게 최고의 실전 레퍼런스 중 하나다.

6. OIDC + WebAuthn 인증 스택

패스키(WebAuthn), TOTP 2FA, OIDC SSO를 한 앱에서 동시에 지원하는 코드는 드물다. server/src/services/oidcService.ts, passkeyService.ts, ephemeralTokens.ts를 보면 현대 인증 스택의 전체 그림이 나온다.

7시스템 요구사항 · 설치

자신의 서버에 TREK을 올리기 위한 최소 사양과 설치 명령.

시스템 요구사항

최소 설치 (Docker 1줄)

ENCRYPTION_KEY=$(openssl rand -hex 32) docker run -d \
  -p 3000:3000 \
  -e ENCRYPTION_KEY=$ENCRYPTION_KEY \
  -v ./data:/app/data \
  -v ./uploads:/app/uploads \
  --name trek \
  mauriceboe/trek

브라우저에서 http://localhost:3000 접속. 첫 부팅 시 관리자 계정이 ADMIN_EMAIL/ADMIN_PASSWORD 환경변수로 생성되며, 미설정 시 컨테이너 로그(docker logs trek)에 출력된다.

Docker Compose (프로덕션 권장)

version: "3.8"
services:
  app:
    image: mauriceboe/trek:latest
    container_name: trek
    read_only: true              # 보안: 컨테이너 파일시스템 읽기전용
    security_opt:
      - no-new-privileges:true   # 권한 상승 차단
    cap_drop:
      - ALL                      # 모든 Linux 능력 제거
    cap_add:
      - CHOWN                    # 파일 소유자 변경만 허용
      - SETUID
      - SETGID
    tmpfs:
      - /tmp:noexec,nosuid,size=128m
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
      - TZ=Asia/Seoul
      - ALLOWED_ORIGINS=https://trek.example.com
      # SSO 설정 (선택)
      # - OIDC_ISSUER=https://accounts.google.com
      # - OIDC_CLIENT_ID=your_client_id
      # - OIDC_CLIENT_SECRET=your_secret
    volumes:
      - ./data:/app/data
      - ./uploads:/app/uploads
    restart: unless-stopped

Kubernetes / Helm 설치

helm repo add trek https://mauriceboe.github.io/TREK/
helm install trek trek/trek \
  --set env.ENCRYPTION_KEY=$(openssl rand -hex 32) \
  --set env.TZ=Asia/Seoul

리버스 프록시 (Caddy 예시)

trek.example.com {
    reverse_proxy localhost:3000
    # Caddy가 자동으로 Let's Encrypt TLS 처리
}

8직접 해볼 수 있는 실습 과제

난이도별 5단계 과제. 개발 환경 없어도 LV.1~2는 바로 시작 가능.

9관련 기술 심화 학습 로드맵

TREK을 완전히 이해하고 기여하기까지 4주 계획.

10핵심 키워드 사전

TREK 코드베이스를 읽을 때 반드시 알아야 할 용어 모음.

11참고 링크

공식 문서와 관련 기술 학습 자료.