team-reflect/reflect-open 딥다이브
— 노트 앱을 "마크다운 파일 + Tauri + 로컬 우선"으로 다시 짠 오픈소스

1프로젝트 한 줄 요약

team-reflect/reflect-open(제품명 Reflect V2)은 유료 노트 앱 Reflect(reflect.app)를 오픈소스로 다시 만든 재작성판이다. 저장소의 AGENTS.md가 못 박는다 — "이 저장소는 Reflect V2이며, 원래의 Reflect 코드베이스를 오프라인 우선·마크다운 기반·오픈소스로 다시 쓴 것이다." 원래 Reflect는 데일리 노트와 백링크로 생각을 잇는 그래프형 노트 앱으로 유명했는데, 그 핵심 아이디어를 "열린 파일 위에서 돌아가게" 옮겨 놓은 게 이 저장소다.

가장 큰 오해를 먼저 풀자. 이름만 보면 흔한 웹 앱 같지만, 실제 정체는 Tauri 2로 만든 macOS·iOS 네이티브 앱이다. 겉껍데기(창·파일 접근·동기화·암호 저장)는 Rust가 맡고, 화면(에디터·목록·설정)은 그 안에 얹힌 React 19 웹뷰가 그린다. 그리고 노트의 원본은 데이터베이스가 아니라 평범한 마크다운 파일이다 — daily/2026-07-17.md, notes/무엇무엇.md처럼. 이걸 빠르게 검색·백링크하려고 SQLite 색인을 만들지만, 그 SQLite는 지워도 파일에서 다시 만들어지는 사본일 뿐이다.

2왜 지금 주목받는가

reflect-open이 트렌딩에 오른 이유는 단순한 "또 하나의 노트 앱"이어서가 아니다. 돈 받고 팔던 완성형 상용 앱을 통째로 MIT로 열었고, 그 과정에서 요즘 로컬 우선 앱들이 당연시하던 CRDT를 일부러 버리고 다른 길을 택했기 때문이다. 노트 앱을 만들거나 로컬 우선 동기화를 고민해 본 개발자에게 이 저장소는 "실제로 출시된 제품의 내부"를 통째로 뜯어볼 수 있는 흔치 않은 표본이다.

주목 포인트 1 — 상용 앱을 통째로, 그것도 "다시 써서" 열었다

보통 상용 서비스가 오픈소스를 낼 때는 SDK나 일부 모듈만 공개한다. reflect-open은 다르다. macOS 앱 + iOS 앱(같은 코드베이스) + 크롬 확장 + 네이티브 메시징 호스트 + CLI까지, 제품을 이루는 거의 전부가 들어 있다. 게다가 기존 코드를 그대로 던진 게 아니라 철학을 바꿔 다시 썼다 — 파이어베이스(클라우드 DB) 기반이던 것을 "파일이 원본"으로, Electron/Next.js를 Tauri로, Yjs를 결정론적 병합으로. "제품을 리라이트하며 아키텍처를 갈아엎는" 실제 사례를 통째로 관찰할 수 있다.

주목 포인트 2 — "로컬 우선인데 CRDT를 안 쓴다"는 기술적 도발

2020년대 로컬 우선 앱의 정석은 Yjs·Automerge 같은 CRDT(충돌 없이 자동 병합되는 자료구조)다. 그런데 reflect-open V2는 이걸 의도적으로 걷어냈다. 대신 conflict/ladder.rs의 결정론적 충돌 해소 사다리로, 같은 충돌은 어느 기기에서 풀든 똑같은 결과 바이트가 나오게 만든다. 그래서 두 기기가 같은 충돌을 동시에 풀어도 결과가 수렴한다(핑퐁이 안 생긴다). "CRDT 없이도 수렴을 만들 수 있다"는 걸 실제 코드로 보여 주는, 학습 가치가 아주 높은 대목이다.

주목 포인트 3 — Tauri 2로 mac·iOS를 한 코드베이스로

Electron이 무겁다는 불만 속에 Tauri(Rust 껍데기 + 시스템 웹뷰)가 대안으로 떠올랐고, reflect-open은 Tauri 2의 실전 레퍼런스다. 특히 데스크톱뿐 아니라 iOS 타깃까지 같은 React 코드로 굴리고, EventKit(캘린더)·CNContacts(연락처) 같은 애플 네이티브 API를 objc2로 브리지하는 실제 코드가 들어 있다. "Rust + 웹뷰로 크로스플랫폼 앱을 어떻게 짜는가"의 살아 있는 교재다.

3기술 스택 전체 지도

reflect-open은 pnpm/Turborepo 모노레포(JS/TS 6개 패키지) + Cargo 워크스페이스(Rust 크레이트 6개)가 한 저장소에 얽혀 있는 하이브리드 구조다. 크게 ① Rust 네이티브 층, ② React 프론트엔드 층, ③ 모두가 공유하는 SQLite 데이터 층으로 나눠 지도를 그려 보자.

① 프론트엔드 — React 19 + Vite 8 + Tailwind 4 (상태 관리는 "가볍게")

② 에디터 — Meowdown (ProseMirror 기반, 단 외부 저장소)

노트를 실제로 타이핑하는 리치 텍스트 에디터는 Meowdown(@meowdown/core·@meowdown/react 0.55.0)이다. 이건 Reflect 팀이 만든 라이브 프리뷰형 마크다운 에디터로, 내부는 ProseMirror(를 감싼 ProseKit) 위에 얹혀 있다. 중요한 함정: Meowdown은 이 저장소 안에 없고 별도 저장소에 산다. 그래서 에디터 자체의 버그나 내부 동작은 이 코드만 봐서는 안 나온다.

③ 네이티브(Rust) — 파일·git·암호·임베딩을 전부 Rust가

④ 데이터 층 — "SQLite 하나"에 세 가지 검색을 얹다

가장 흥미로운 설계다. 저장소 전체가 단 하나의 SQLite 스키마를 공유하는데, 접근하는 쪽에 따라 도구가 다르다.

⑤ AI · CLI · 확장

AI는 Vercel AI SDK(ai 6.0.211) + @ai-sdk/openai·@ai-sdk/anthropic·@ai-sdk/google, OpenRouter는 OpenAI 호환 프로바이더로. CLI(reflect)는 Rust clap + pulldown-cmark(마크다운) + saphyr(YAML 프런트매터)로 today·search·show 명령을 제공한다. 크롬 확장은 WXT 0.20(MV3) + defuddle(본문 추출)로 웹페이지를 캡처한다. 빌드는 pnpm 11.9.0 + Turborepo, 린트는 oxlint.

4아키텍처 심화 분석

reflect-open의 데이터 흐름은 한 방향의 강물처럼 흐른다. 원본(마크다운)에서 시작해 색인(SQLite)으로, 다시 화면(React)으로. 쓰기는 이 강을 거슬러 오르지 않고 별도의 수문(Rust 명령)으로만 들어간다.

핵심 설계 1 — 읽기 전용 IPC SQLite 다리

프론트엔드는 SQLite에 직접 붙지 못한다(웹뷰니까). 그래서 재치 있는 다리를 놓았다(packages/db/src/dialect.ts + src-tauri/src/db/query.rs). 프론트엔드가 Kysely로 쿼리를 만들면 그게 {sql, parameters} 형태로 컴파일되고, Tauri의 db_query 명령을 타고 Rust로 건너간다. Rust가 색인에 실행해 결과 행을 돌려준다. 결정적 안전장치 — Rust 쪽은 rusqlite의 authorizer(권한 심사) API로 이 통로를 순수 읽기로 못 박아, ATTACH·DETACH·PRAGMA 같은 위험한 구문을 거부한다.

// packages/db/src/dialect.ts (주석 요지)
// 쓰기는 이 다리를 타지 않는다 — 쓰기는 index_* 명령이
// 자기 Rust 트랜잭션으로 처리한다. 그래서 이건 읽기 전용
// 다리이고, 트랜잭션은 지원하지 않는다.

핵심 설계 2 — CRDT 없는 "결정론적 충돌 사다리"

이 저장소에서 가장 배울 게 많은 대목이다(apps/desktop/src-tauri/src/conflict/ladder.rs). 두 기기가 같은 노트를 따로 고쳐 충돌이 났을 때, CRDT 대신 순수 함수 하나로 푼다: "충돌한 노트 쌍"이 들어가면 → 어느 기기에서 돌리든 똑같은 바이트가 나온다. 비결은 어느 쪽이 "내 것"인지로 우선순위를 두지 않고, 두 기기가 공유하는 정보 (수정시각, 내용)으로 순서를 정하는 것이다.

// conflict/mod.rs 주석 요지
// 모든 규칙은 두 쪽을 (modified_ms, content) 로 정렬한다 —
// 두 기기가 공유하는 데이터로. "어느 쪽이 로컬인가"로는 절대 정렬 안 함.

사다리는 8단이다: ① 완전히 같음 → ② 공백만 다름 → ③ 이미 충돌 마커가 있는 쪽 유지 → ④ 병합 루프 차단 → ⑤ 공통 조상(shadow base) 기준 3-way 병합 → ⑥ 프런트매터를 키 단위로 병합 → ⑦ 데일리 노트는 append-union(이어 붙이기) → ⑧ 그래도 안 되면 라벨 붙인 충돌 마커. 위 단계에서 못 풀면 아래로 내려간다.

핵심 설계 3 — 쿼리 시점에 백링크를 "계산"한다

백링크(어떤 노트를 가리키는 다른 노트들)를 미리 저장해 두지 않는다. 대신 링크는 해소되지 않은 target_key만 저장하고, 백링크는 읽는 순간 SQL 뷰가 조인해서 만든다(migrations/0001_initial.sql).

-- 노트의 "이름·별칭·날짜"를 모두 키로 모은 뷰
CREATE VIEW note_keys AS
  SELECT path, title_key AS key FROM notes
  UNION SELECT note_path, alias_key FROM aliases ...;
-- 백링크 = 링크의 target_key 를 note_keys 에 조인
CREATE VIEW backlinks AS
  SELECT k.note_path AS target_path, l.source_path
  FROM links l JOIN note_keys k ON k.key = l.target_key;

효과가 크다 — 새 노트를 하나 만들면, 그 노트를 가리키던 링크들이 재색인 없이 즉시 백링크로 연결된다. 이름만 맞으면 조인이 알아서 이어 주기 때문이다.

핵심 설계 4 — 동기화는 iCloud 또는 git, 둘 중 하나만

그래프(=노트 폴더) 하나는 iCloud Drive 또는 git 원격 중 하나로만 동기화한다(둘 다 동시에는 안 됨). git 경로는 커밋·브랜치 같은 git 용어를 사용자에게 숨기고 "백업됨/백업 중/오프라인/검토 필요/백업 실패"라는 제품 상태로만 보여 준다. iCloud 경로는 동시 편집을 NSFileVersion으로 감지해 앞서 본 결정론적 사다리로 기기 안에서 푼다. 서버가 개입하지 않는, 진짜 클라이언트 온리 구조다(이 저장소엔 백엔드 서버 코드가 없다).

5디렉토리 구조 해부

규모를 숫자로 보면 — 추적 파일 총 1,578개, TS/TSX 약 131,000줄(978파일), Rust 약 24,400줄(97파일), Swift 약 1,800줄(15파일), SQL 마이그레이션 18개. Rust↔JS를 잇는 #[tauri::command] 핸들러가 99개. 눈여겨볼 세 곳은 ① conflict/ladder.rs(충돌 해소), ② packages/db/src/dialect.ts(읽기 전용 다리), ③ crates/index-schema/migrations/0001_initial.sql(데이터 모델)이다.

6학습 포인트

배울 것 1 — CRDT 없이 "수렴"을 만드는 결정론적 병합

분산 시스템에서 두 복제본을 다투지 않게 합치는 정석은 CRDT다. 그런데 CRDT는 무겁고, 메타데이터가 계속 쌓이며, 마크다운 같은 "그냥 텍스트"에 얹기가 까다롭다. reflect-open은 순수 함수 + 결정론이라는 더 단순한 무기로 같은 목표(수렴)를 노린다. 핵심 통찰은 하나다 — "누가 로컬인가"라는, 기기마다 다른 정보로 판단하지 말 것. 대신 (수정시각, 내용)처럼 두 기기가 똑같이 아는 정보로만 순서를 정하면, 어느 기기가 먼저 병합해도 결과가 같아진다. 이 아이디어는 노트 앱을 넘어 어떤 "오프라인 편집 후 합치기" 문제에도 응용할 수 있다.

배울 것 2 — 신뢰 경계를 코드로 강제하기 (읽기 전용 IPC)

"프론트엔드는 읽기만, 쓰기는 백엔드만"이라는 규칙을 문서로만 정해 두면 언젠가 깨진다. reflect-open은 이걸 기계가 강제하게 만들었다 — Kysely로 만든 SQL은 db_query 통로로만 가고, 그 통로는 rusqlite authorizer가 SELECT 외 구문을 런타임에 거부한다. "설계 원칙을 주석이 아니라 실행 가능한 방어선으로 바꾸는" 좋은 예다. 웹뷰↔네이티브를 나누는 모든 앱(Electron·Tauri)에 그대로 옮길 만한 패턴이다.

배울 것 3 — 미리 만들지 말고 "읽을 때 계산"하기 (지연 백링크)

백링크를 저장해 두면, 노트 이름을 바꾸거나 새 노트를 만들 때마다 관련 링크를 전부 찾아 갱신해야 한다(비싸고 버그가 많다). reflect-open은 아예 저장을 안 한다. 링크는 "가리키려는 이름(target_key)"만 들고 있고, 백링크는 SQL 뷰가 읽는 순간 조인으로 계산한다. "미리 계산(eager) vs 필요할 때 계산(lazy)"의 트레이드오프를 실물로 배우는 대목이다 — 여기선 lazy가 훨씬 깔끔하다.

배울 것 4 — 프라이버시를 지키는 온디바이스 AI

의미 검색("비슷한 노트 찾기")을 하려면 노트를 임베딩(벡터)으로 바꿔야 하는데, 보통은 이걸 OpenAI 서버에 보낸다 — 프라이버시 문제가 생긴다. reflect-open은 embed.rs에서 fastembed로 MiniLM 모델을 기기에 내려받아 로컬에서 임베딩을 만든다(GPU 없이 CPU로). 벡터는 sqlite-vec의 vec0 테이블에 넣어 코사인 유사도로 검색한다. "AI 기능을 넣되 데이터는 기기 밖으로 안 내보내는" 실전 설계를 통째로 볼 수 있다. 게다가 private: true가 붙은 노트는 모든 외부 호출에서 아예 제외하는 게이트(ai/checkers.ts)까지 있다.

7시스템 · 실행 요구사항

실제 실행 명령

# 준비
corepack enable && pnpm install

# 전체 앱 실행 (CLI 사이드카를 먼저 스테이징)
pnpm tauri dev

# 화면(Vite)만 → http://localhost:1420  (?platform=ios 로 모바일 미리보기)
pnpm dev

# iOS 시뮬레이터
pnpm tauri:ios:dev "iPhone 17 Pro"

# 타입체크 + 린트
pnpm check

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

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

10핵심 키워드 사전

11참고 링크

저장소 · 제품
· GitHub: github.com/team-reflect/reflect-open (MIT © 2026 Reflect App, LLC · 앱 v0.7.0-beta.8)
· 상용 제품: reflect.app (이 저장소는 그 오픈소스 재작성판 V2)
· 최신 커밋: a30a8aa (2026-07-17, "chore: release 0.7.0-beta.8")

핵심 파일(클론 후)
· AGENTS.md — 저장소의 권위 있는 개요(V2 철학·규칙)
· apps/desktop/src-tauri/src/conflict/ladder.rs — 결정론적 충돌 사다리
· packages/db/src/dialect.ts + src-tauri/src/db/query.rs — 읽기 전용 IPC 다리
· crates/index-schema/migrations/0001_initial.sql — 데이터 모델(백링크 뷰)
· apps/desktop/src-tauri/src/embed.rs — 온디바이스 임베딩
· docs/plans/ — 00~23 기능별 구현 계획(지도)

배경 지식
· Tauri 2 문서 · Kysely · sqlite-vec
· Local-first software (Ink & Switch) — 로컬 우선 철학의 원전
· ProseMirror(Meowdown의 토대) · fastembed