fredy 딥다이브
— 독일에서 집 구하기를 "봇"에게 맡기는 셀프호스팅 부동산 매물 추적기

"파일 하나 = 기능 하나"로 확장 쉬운 구조 짜기

Fredy는 Provider도 Adapter도 폴더에 파일을 하나 더 넣으면 끝나도록 설계됐습니다. 핵심 파이프라인은 "어떤 Provider인지" 신경 쓰지 않고 정해진 인터페이스(normalize·filter·crawlFields 등)만 호출하죠. 새 포털·새 알림 채널을 추가할 때 기존 코드를 안 건드린다는 게 핵심입니다. 이게 "개방-폐쇄 원칙(OCP)"의 실전 예시입니다.

📖 한 줄 풀이: lib/provider/immowelt.js 하나를 열어보면, 한 포털을 Fredy에 가르치는 데 필요한 최소 규칙이 무엇인지 한눈에 보입니다.

복잡한 다단계 처리를 .then()으로 줄세우기

13단계나 되는 처리를 거대한 함수 하나에 욱여넣으면 읽을 수 없습니다. Fredy는 각 단계를 작은 메서드로 쪼개고 .then()으로 연결해, 코드만 봐도 처리 순서가 그대로 읽히게 했습니다.

// 💡 하는 일: 매물을 13단계 컨베이어에 한 번 태운다
return Promise.resolve(urlModifier(url, sortByDate))
  .then(this._getListings)        // ② 추출
  .then(this._normalize)          // ③ 정규화
  .then(this._filter)             // ④ 1차 필터
  .then(this._findNew)            // ⑤ 새것만
  .then(this._filterBySimilarListings)  // ⑩ 중복 제거
  .then(this._notify)             // ⑬ 알림
  .catch(this._handleError);      // 에러는 한 곳에서

안심하세요 — 각 _단계는 입력을 받아 다음으로 넘길 값을 돌려주는 작은 함수일 뿐입니다. "데이터가 파이프를 따라 흐른다"는 그림이 코드에 그대로 박혀 있습니다.

왜 단순 스크래핑은 막히고, 어떻게 우회하나

실전 스크래핑의 8할은 "안 막히기"입니다. Fredy는 세 가지 무기를 씁니다 — ① CloakBrowser로 브라우저 지문을 진짜 크롬처럼 위장, ② ImmoScout24는 웹 대신 모바일 앱 API를 역설계해 우회, ③ 서버에서 막힐 땐 주거용 프록시로 가정집 IP인 척. "기술적으로 가능한가"와 "현실에서 안 막히나"는 다른 문제임을 배우는 좋은 교재입니다.

📖 한 줄 풀이: reverse-engineered-immoscout.md 문서가 "공식 API가 없을 때 모바일 앱 트래픽을 분석해 비공식 통로를 찾는" 과정을 보여줍니다.

주소를 좌표로, 좌표를 "이 동네 안인가"로

Fredy는 매물 주소를 지오코딩으로 좌표화하고, 웹 UI에서 지도에 직접 그린 다각형(polygon) 안에 그 좌표가 들어오는지 @turf/boolean-point-in-polygon으로 판정합니다. "점이 다각형 내부인가"는 게임·지도·물류 어디서나 쓰이는 고전 알고리즘이라, 한 번 익혀두면 두고두고 씁니다.

내 데이터를 Claude가 "도구"로 조회하게 만들기

V20+의 MCP 서버는 Fredy가 모은 매물 데이터를 LLM이 자연어로 질의할 수 있게 엽니다. "이번 주 새로 뜬 방 3개짜리 중 역세권인 거 추려줘" 같은 요청을 Claude·ChatGPT가 처리하죠. 자기 앱에 LLM 인터페이스를 붙이는 요즘 표준(MCP)을 실제 프로젝트에서 어떻게 쓰는지 볼 수 있습니다.

Docker로 1분 만에 띄우고 데모 둘러보기 난이도 ★☆☆ 입문

아래 한 줄로 Fredy를 띄우고 http://localhost:9998에 접속해보세요(기본 로그인 admin/admin). 먼저 공개 데모로 UI를 둘러본 뒤 내 것으로 옮기면 길을 잃지 않습니다.

# 💡 하는 일: Fredy 컨테이너를 띄우고 설정·DB 볼륨을 붙인다
docker run -d --name fredy \
  -v fredy_conf:/conf \
  -v fredy_db:/db \
  -p 9998:9998 \
  ghcr.io/orangecoding/fredy:master

안심하세요 — 위 명령은 복사만 하면 동작합니다. docker logs fredy -f로 무슨 일이 벌어지는지 실시간으로 볼 수 있습니다.

검색 Job 하나를 끝까지 만들어 알림 받기 난이도 ★☆☆ 입문

포털(예: WG-Gesucht)에서 원하는 조건으로 검색하고 "날짜순 정렬"로 맞춘 뒤 그 URL을 복사하세요. Fredy 웹 UI에서 Provider로 붙여넣고, Adapter로 Telegram이나 ntfy(가장 설정이 쉬움)를 골라 Job을 만들면, 다음 실행 때 새 매물이 알림으로 옵니다. "정렬을 날짜순으로" 안 하면 최신 매물을 놓치니 꼭 확인하세요.

지도 다각형으로 "이 동네만" 필터 걸기 난이도 ★★☆ 중급

웹 UI의 지도에서 원하는 동네를 다각형으로 그려 지역 필터를 걸어보세요. 그런 다음 코드에서 lib/FredyPipelineExecutioner.js의 _filterByArea를 읽어, 매물 좌표가 그 다각형 안인지 @turf로 어떻게 판정하는지 따라가 보면 "UI 조작 → 코드 동작"의 연결이 보입니다.

나만의 알림 어댑터 추가하기 난이도 ★★☆ 중급

lib/notification/adapter/ntfy.js 같은 기존 어댑터 하나를 본보기로, 새 채널(예: 카카오워크·자체 웹훅)을 보내는 어댑터 파일을 하나 만들어 등록해보세요. 플러그인 구조 덕에 핵심 코드를 안 건드리고도 기능이 늘어나는 경험을 직접 할 수 있습니다.

오프라인 테스트와 픽스처 갱신 돌려보기 난이도 ★★★ 고급

yarn run test:offline은 실제 포털 대신 저장된 픽스처(과거 응답 스냅샷)로 핵심 로직을 빠르게 검증합니다. 포털이 HTML 구조를 바꾸면 스크래퍼가 깨지는데, yarn run test:download-fixtures로 새 픽스처를 받아 테스트를 갱신하는 흐름을 따라가 보면 "스크래퍼 유지보수"의 현실을 배웁니다.