프라이버시 중심의 독립형 스마트 태스크 & 마크다운 워크스페이스
A modern, self-hosted, privacy-first task management & note workspace built for focus, speed, and open-standard freedom.

✨ 핵심 기능 • 🚀 빠른 시작 (Docker) • 📱 CalDAV 모바일 연동 • 📦 데이터 호환성 • 🧪 Labs 커스터마이징 • 🛠️ 개발 환경

💡 프로젝트 소개 & 디자인 철학

CheckFlow는 상용 클라우드 서비스(TickTick, Notion, Todoist 등)의 복잡성과 구독 모델, 데이터 종속에서 벗어나 사용자 개인의 완벽한 데이터 주권과 군더더기 없는 미니멀리즘 작업 경험을 제공하기 위해 설계된 독립형 웹 애플리케이션입니다.

🎯 순수한 몰입감: 산만한 툴바와 불필요한 장식을 배제하고, 에디터 본연의 텍스트 타이핑과 정갈한 마크다운 렌더링에 집중합니다.
🌲 자유로운 계층화: N단계 재귀적 하위 태스크 트리와 직관적인 인라인 수정을 통해 생각의 흐름을 그대로 구조화합니다.
🌐 열린 표준: 폐쇄적인 API 대신 RFC 4791 CalDAV, RFC 5545 iCalendar (.ics), RFC 4180 CSV 표준을 준수하여 어떤 플랫폼에서든 자유롭게 동기화하고 백업할 수 있습니다.

✨ 핵심 기능 & 디자인 철학

1. 🌲 N-Depth 재귀 하위 태스크 & 인라인 편집

무제한 계층 구조: 단순 1단계 하위 작업을 넘어 원하는 만큼 서브태스크를 트리 형태로 중첩 확장할 수 있습니다.
실시간 양방향 동기화: 중앙 체크리스트와 우측 상세 패널 간의 상태가 지연 없이 1:1로 실시간 동기화됩니다.
인라인 즉시 수정: 목록 제목 및 태스크 제목을 더블클릭/클릭하여 즉시 인라인 수정할 수 있습니다 (Enter 저장, ESC 취소).

2. 📝 적응형(Adaptive) 와이드 마크다운 노트

넓은 캔버스 레이아웃: 우측 상세 패널의 대부분을 시원한 노트 공간으로 활용할 수 있습니다.
뷰 & 에디트 듀얼 모드: ✏️ 작성 중에는 부드러운 텍스트 에디터로, 👁️ 뷰 모드에서는 웹 문서 수준의 미려한 마크다운 GUI 뷰어로 렌더링됩니다.
보안 렌더링: DOMPurify 기반의 철저한 XSS 방어 및 안전한 외부 링크(rel="noopener noreferrer")를 지원합니다.

3. 🧪 CheckFlow Labs & 유연한 커스터마이징

📋 리스트 뷰 ↔ 📊 3컬럼 칸반 보드 원클릭 전환: To Do, In Progress, Done 컬럼으로 할 일 상태를 시각적으로 관리합니다.
모듈형 블록 스왑 & 스플릿 리사이저: 서브태스크 목록과 마크다운 메모장의 상하 위치를 원하는 대로 맞바꾸고(⇄), 마우스 드래그로 높이 비율(15%~85%)을 자유롭게 조절할 수 있습니다.
개인화 환경설정: UI 밀도(Compact/Default/Comfortable), 글꼴 크기, 테두리 라운드, 반응형 애니메이션 속도, 액센트 색조(Hue) & 채도(Saturation)를 슬라이더로 조절할 수 있으며, 언제든 초기 순정 상태로 되돌릴 수 있습니다.

4. 🎨 VSCode 무채색 다크 테마 & 파스텔 매트 라이트

눈의 피로를 최소화하는 VSCode 스타일 무채색 다크 팔레트 (#181818, #1e1e1e, #252526)와 매트 파스텔 라이트 테마, 시스템 동기화 모드를 지원합니다.
사이드바 및 우측 패널의 너비를 마우스 드래그로 실시간 리사이징할 수 있습니다.

5. 📱 모바일 바텀시트 드로어 & PWA

스마트폰 화면에서는 우측 상세 패널이 부드러운 **바텀시트(Bottom Sheet)**로 전환됩니다.
화면 아래로 스와이프하거나 백드롭 오버레이를 터치하여 자연스럽게 패널을 닫을 수 있습니다.
PWA 매니페스트(manifest.json)와 서비스워커(sw.js)를 통해 앱처럼 홈 화면에 추가하고 오프라인 캐시를 활용할 수 있습니다.

6. 🌐 3개국어 다국어(i18n) 지원

영어(English), 한국어(Korean), 일본어(Japanese) 3개 언어를 완벽하게 지원하며 브라우저 또는 설정에서 즉시 변경할 수 있습니다.

🚀 빠른 시작 (Docker 배포)

CheckFlow는 사전 빌드된 컨테이너 레지스트리 이미지와 자동 DB 마이그레이션 진입점(docker-entrypoint.sh)을 제공하므로, Git 소스 코드 복제(clone) 없이 docker-compose.yml과 .env 파일 단 2개만으로 즉시 배포할 수 있습니다.

1. 배포 디렉터리 준비 및 설정 파일 다운로드

서버의 원하는 디렉터리에서 설정 파일 2개를 내려받습니다:

mkdir checkflow && cd checkflow

# docker-compose.yml 다운로드
curl -O https://git.nrh.kr/Neru_Han/checkflow/raw/branch/master/docker-compose.yml

# .env.example 다운로드 후 .env 생성
curl -O https://git.nrh.kr/Neru_Han/checkflow/raw/branch/master/.env.example
cp .env.example .env

2. 환경 변수(`.env`) 설정

.env 파일을 열어 사용자 환경에 맞게 수정합니다:

# [필수] 데이터베이스 비밀번호 (안전한 난수로 지정)
POSTGRES_PASSWORD=your_secure_password

# [필수] 서비스 접속 URL (리버스 프록시 도메인 또는 IP)
NEXTAUTH_URL=https://todo.yourdomain.com

# [필수] NextAuth 세션 암호화 키 (openssl rand -base64 32 등으로 생성)
NEXTAUTH_SECRET=your_generated_random_secret_string

# [선택] 외부 노출 포트 (기본값: 3000)
PORT=3000

# [선택] Gitea / Docker 컨테이너 레지스트리 이미지 주소
CHECKFLOW_IMAGE=git.nrh.kr/neru_han/checkflow:latest

3. 컨테이너 이미지 풀(Pull) 및 실행

Gitea 패키지 레지스트리가 비공개인 경우 먼저 도커 로그인을 수행합니다 (공개 레지스트리인 경우 생략 가능):

# (비공개 레지스트리인 경우 1회 로그인)
docker login git.nrh.kr

# 최신 배포 이미지 다운로드
docker compose pull

# 백그라운드 서비스 시작
docker compose up -d

💡 자동 DB 마이그레이션: 컨테이너가 시작될 때 PostgreSQL 데이터베이스 준비 상태를 확인한 후 prisma migrate deploy를 자동 수행하므로 별도의 수동 DB 설정이 전혀 필요하지 않습니다.

🔄 Watchtower 기반 무중단 자동 갱신

docker-compose.yml에는 com.centurylinklabs.watchtower.enable=true 라벨이 기본 적용되어 있습니다.
Gitea Actions CI 파이프라인을 통해 새 이미지가 레지스트리에 푸시되면, Watchtower가 이를 감지하여 컨테이너를 자동으로 최신 상태로 갱신합니다:

# Watchtower가 실행 중인 경우 CheckFlow 컨테이너 자동 감지 & 갱신
docker run -d \
  --name watchtower \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower --interval 300 --cleanup --label-enable

브라우저에서 설정한 도메인(https://todo.yourdomain.com 또는 http://서버IP:3000)에 접속하여 첫 관리자 계정을 생성하고 바로 사용을 시작하세요.

📱 CalDAV 모바일 및 외부 앱 동기화

CheckFlow는 RFC 4791 CalDAV 표준 프로토콜을 완벽하게 지원하여, 모바일 및 데스크톱 기본 캘린더/할 일 앱과 양방향으로 동기화됩니다.

CalDAV 기본 엔드포인트 URL: https://your-domain.com/api/dav
사용자 이름: CheckFlow 계정 이메일
비밀번호: CheckFlow 계정 비밀번호

🤖 Android (DAVx⁵ + Tasks.org / OpenTasks)

F-Droid 또는 Google Play에서 DAVx⁵ 앱을 설치합니다.
DAVx⁵ → 계정 추가(+) → URL 및 사용자 이름으로 로그인 선택.
기본 URL(https://your-domain.com/api/dav), 이메일, 비밀번호 입력.
VTODO (할 일) 컬렉션을 활성화하면 Tasks.org 또는 OpenTasks 앱에서 실시간 양방향 동기화가 이루어집니다.

🍎 Apple Reminders (iOS / iPadOS / macOS)

기기 설정 → 미리알림(Reminders) → 계정 → 계정 추가.
기타 → CalDAV 계정 추가 선택.
서버 주소, 이메일, 비밀번호 입력 후 미리알림 활성화.

💻 Mozilla Thunderbird (Windows / Linux / macOS)

Thunderbird 실행 → 캘린더 탭 → 새 캘린더 생성.
네트워크에 저장 → 형식: CalDAV 선택.
위치에 기본 URL 입력 및 이메일/비밀번호 인증.

📦 데이터 가져오기 & 내보내기

언제든 외부 서비스와 자유롭게 데이터를 주고받거나 로컬 백업을 생성할 수 있습니다.

📥 TickTick 데이터 가져오기 (Import)

TickTick 설정 → 데이터 내보내기에서 생성된 CSV 또는 iCalendar (.ics) 파일을 사이드바의 가져오기 메뉴에서 업로드하여 기존 할 일, 하위 태스크, 마감일, 우선순위를 그대로 복원합니다.
Formula Injection 및 XSS 공격을 방어하는 보안 검증 모듈이 내장되어 있습니다.

📤 표준 포맷 데이터 내보내기 (Export)

사이드바 사용자 메뉴 → 내보내기 선택.
TickTick 호환 RFC 4180 CSV (Excel 호환 UTF-8 BOM 포함) 또는 RFC 5545 iCalendar (.ics VTODO) 형식 지원.
전체 할 일 또는 특정 목록 필터링, 완료 항목 포함 여부를 자유롭게 선택하여 즉시 다운로드할 수 있습니다.

🛠️ 로컬 개발 환경

필수 요구사항

Node.js 20+
npm 또는 pnpm
PostgreSQL (또는 개발용 SQLite)

# 1. 저장소 클론 및 패키지 설치
git clone https://git.nrh.kr/Neru_Han/checkflow.git
cd checkflow
npm install

# 2. 환경 변수 설정
cp .env.example .env.local

# 3. Prisma DB 스키마 생성 및 클라이언트 빌드
npx prisma db push
# 또는 SQLite 개발 모드: npm run dev:sqlite

# 4. 로컬 개발 서버 시작 (Turbopack)
npm run dev

브라우저에서 http://localhost:3000 (체험 모드는 http://localhost:3000/demo)으로 접속합니다.

🏗️ 시스템 아키텍처 & 기술 스택

src/
├── app/
│   ├── page.tsx                       ← 메인 앱 진입점 (NextAuth 세션 기반)
│   ├── demo/page.tsx                  ← DB 연결 없이 LocalStorage 기반 완전 구동 데모
│   ├── admin/page.tsx                 ← 멀티유저 관리 및 시스템 대시보드 (ADMIN 전용)
│   ├── api/
│   │   ├── auth/                      ← NextAuth 및 회원가입 엔드포인트
│   │   ├── lists/ & tasks/            ← 계층형 태스크 & 리스트 REST API (IDOR 소유권 검증)
│   │   ├── import/ & export/          ← RFC 4180 CSV / RFC 5545 ICS 파서 및 익스포터
│   │   └── dav/[...path]/             ← RFC 4791 CalDAV 프로토콜 엔드포인트
├── components/
│   ├── layout/
│   │   ├── AppShell.tsx               ← 3-Panel 메인 컨테이너, 반응형 리사이저, 모바일 오버레이
│   │   └── Sidebar.tsx                ← 프로젝트 트리, 언어/테마 선택, 프로필 & Import/Export 팝오버
│   ├── tasks/
│   │   ├── TaskList.tsx               ← N-depth 재귀 체크리스트 트리, 스마트 퀵애드, 인라인 수정
│   │   ├── TaskDetail.tsx             ← 상세 패널, 블록 스왑, 마우스 스플릿 리사이저, 바텀시트
│   │   ├── MarkdownNoteEditor.tsx     ← 미니멀 마크다운 에디터 & DOMPurify 보안 프리뷰
│   │   └── KanbanView.tsx             ← CheckFlow Labs 3컬럼 칸반 보드
│   └── settings/
│       └── SettingsModal.tsx          ← Profile / Preferences / Labs / CalDAV / Admin 5탭 모달
└── lib/
    ├── userPrefs.ts                   ← 반응형 개인화 설정 스토어 (CSS 변수 인젝터)
    ├── i18n/                          ← EN/KO/JA 다국어 사전 및 useI18n 훅
    ├── auth.ts & prisma.ts            ← NextAuth 구성 및 Prisma DB 커넥터
    └── mockData.ts                    ← 데모 모드 전용 LocalStorage 스토리지 레이어

🔒 보안 및 개인정보 원칙

엄격한 데이터 격리: 모든 API 요청은 세션 소유권(userId === session.user.id)을 검증하며 리스트/태스크 간 IDOR(비인가 접근)를 원천 차단합니다.
XSS 및 수식 주입 방어: 모든 사용자 입력과 마크다운 렌더링은 DOMPurify를 거치며, CSV 가져오기 시 Formula Injection 방어(sanitizeFormula)가 적용됩니다.
독립 멀티유저 & 관리자 통제: 일반 사용자와 관리자(ADMIN) 권한이 분리되어 안전하게 셀프호스팅 환경을 운영할 수 있습니다.

📄 라이선스 (License)

This project is licensed under the MIT License — see the LICENSE file for details.

README.md

⚡ CheckFlow