MarkFlow KMS

소개

Claude Code Expert는 『클로드 코드 마스터 — 기획 · 개발 · 운영이 한 번에 끝나는 AI 에이전틱 코딩 워크 플로』의 공식 GitHub 조직입니다. 이 책은 단순한 도구 사용법 튜토리얼이 아닙니다. AI 코딩 에이전트와 체계적으로 협업하는 방법론을 제시합니다 — 명세 주도 개발(SDD), 테스트 주도 개발(TDD), 그리고 어떤 AI 도구를 사용하든 변하지 않는 체계적인 리뷰 프로세스까지 다룹니다. Markflow는 Markdown Knowledge Management System으로 손쉽게 마크다운 문서를 생성하여 폴더 단위로 문서들간의 연관 관계를 관리하는 지식 관리 SaaS 혹은 온프레미스로 사용할 수 있는 오픈소스입니다. 책 관련 문의 사항이나 프로젝트 관련 문의사항은 brewnet.dev@gmail.com으로 연락주시기 바랍니다.

---

한국어 | English

마크다운 기반 팀 지식 관리 플랫폼 (Knowledge Management System).

화면 미리보기

1. 로그인

2. 워크스페이스

3. 문서 목록

4. 상세 보기

5. 문서 작성하기

구조

markflow/
├── packages/
│   ├── editor/          @markflow/editor — 독립 에디터 컴포넌트 (npm 배포 가능)
│   └── db/              @markflow/db — Drizzle ORM 스키마 + 마이그레이션 + SCHEMA.sql
├── apps/
│   ├── web/             @markflow/web — Next.js 16.2.1 프론트엔드 (App Router + API Routes)
│   └── worker/          Cloudflare R2 이미지 업로드 Worker (선택)
└── docs/                설계 문서, 프로토타입, ERD

v0.4.0부터 Fastify(apps/api)를 제거하고 Next.js App Router API Routes로 통합했습니다. 단일 Vercel 프로젝트로 배포됩니다.

로컬 에디터 기능 테스트

./scripts/item-test.sh all        # 전체 28개
./scripts/item-test.sh bold       # Bold만
./scripts/item-test.sh strike     # Strikethrough만
./scripts/item-test.sh list       # UL+OL+Task 전체
./scripts/item-test.sh int        # 통합 테스트 (22개 한 문서)
./scripts/item-test.sh help       # 전체 명령어 목록

사전 준비

• Node.js 20+
• pnpm 10+ (npm install -g pnpm)
• PostgreSQL 16+

1. PostgreSQL 설정 (최초 1회)

psql -h localhost -p 5432 -U postgres

CREATE USER markflow WITH PASSWORD 'markflow';
CREATE DATABASE markflow OWNER markflow;
GRANT ALL PRIVILEGES ON DATABASE markflow TO markflow;
\q

2. 환경 변수

apps/web/.env.local 파일을 생성하고 본인 환경에 맞게 설정하세요:

DATABASE_URL=postgresql://markflow:markflow@localhost:5432/markflow
JWT_SECRET=dev-jwt-secret-change-in-production
JWT_REFRESH_SECRET=dev-jwt-refresh-secret-change-in-production
NEXT_PUBLIC_SITE_URL=http://localhost:3002

3. 설치 및 실행

pnpm install
pnpm --filter @markflow/db build       # DB 패키지 빌드 (최초 1회)
pnpm --filter @markflow/editor build   # 에디터 빌드 (최초 1회)

# DB 부트스트랩 — 둘 중 하나 선택
psql "$DATABASE_URL" -f packages/db/SCHEMA.sql      # (a) 빈 DB에 한 번에 생성
cd packages/db && pnpm drizzle-kit push && cd ../.. # (b) Drizzle로 점진 적용

pnpm dev                                # Web 서버 실행

http://localhost:3002 에서 접속.

4. 계정 생성

1. http://localhost:3002/register 에서 회원가입
2. 이메일 인증 우회:

   psql -h localhost -p 5432 -U markflow -d markflow \
     -c "UPDATE users SET email_verified = true;"

3. http://localhost:3002/login 에서 로그인

프로덕션 환경 변수

웹앱 (apps/web)

v0.4.0부터 API는 Next.js API Routes로 통합되었습니다. 환경 변수는 apps/web에만 설정합니다.

변수	설명	생성 방법
DATABASE_URL	PostgreSQL 연결 URL	DB 호스팅 서비스에서 제공 (Supabase, Neon, RDS 등)
JWT_SECRET	Access Token 서명 키	openssl rand -hex 32
JWT_REFRESH_SECRET	Refresh Token 서명 키	openssl rand -hex 32 (JWT_SECRET과 다른 값)
NEXT_PUBLIC_SITE_URL	사이트 도메인 (sitemap/SEO)	https://markflow.vercel.app
NEXT_PUBLIC_R2_WORKER_URL	(선택) 이미지 업로드 Worker	https://r2-uploader.<id>.workers.dev

pnpm start(프로덕션)는 .env.local을 읽지 않고 시스템 환경 변수만 사용합니다.

배포 아키텍처

v0.4.0부터 API가 Next.js API Routes로 통합되어 단일 Vercel 프로젝트로 배포됩니다.

컴포넌트	권장 호스팅
apps/web (Next.js + API Routes)	Vercel — Framework Preset: Next.js, Build Command: pnpm --filter @markflow/db build && pnpm --filter @markflow/editor build && cd apps/web && next build, Output Directory: apps/web/.next
PostgreSQL	Supabase / Neon / Vercel Postgres
apps/worker	Cloudflare Workers + R2 버킷

Vercel 배포 시 Root Directory는 비워두고 (프로젝트 루트), Framework Preset을 Next.js로 수동 지정해야 합니다. apps/web을 Root Directory로 설정하면 pnpm workspace 감지에 실패합니다.

명령어

pnpm dev                             # Web 서버 실행 (포트 3002)
pnpm build                           # 전체 빌드
pnpm test                            # 전체 테스트
pnpm --filter @markflow/web dev      # 웹앱만
pnpm --filter @markflow/editor build # 에디터 패키지 빌드
pnpm --filter @markflow/db build     # DB 패키지 빌드
pnpm --filter @markflow/web test:e2e # E2E 테스트 (Playwright)

패키지

@markflow/editor

독립형 React Markdown 에디터 컴포넌트. React 18+ 또는 19+ 프로젝트에 이식 가능.

• CodeMirror 6 (소스 편집기)
• remark + rehype (마크다운 파싱/렌더링)
• KaTeX (수식), rehype-highlight (코드 하이라이팅)
• rehype-sanitize (XSS 방어)

@markflow/db

Drizzle ORM 기반 DB 스키마. 15개 테이블 (users, workspaces, workspace_members, categories, category_closure, documents, document_versions, document_relations, tags, document_tags, comments, invitations, join_requests, embed_tokens, refresh_tokens). 신규 환경 부트스트랩은 SCHEMA.sql, 점진 마이그레이션은 src/migrations/*.sql 사용. ERD: docs/ERD.svg

@markflow/web

Next.js 16.2.1 프론트엔드 + API Routes. React 19.2.4, Zustand 5 (상태), TanStack Query 5 (서버 상태), Tailwind CSS 4. JWT 인증, RBAC (소유자/관리자/편집자/뷰어), 문서 CRUD + 버전 관리 API 50개 포함.

문서

문서	설명
packages/db/SCHEMA.sql	통합 DB 부트스트랩 SQL (15개 테이블 + FK + 인덱스)
docs/ERD.svg	데이터베이스 ER 다이어그램
docs/PROJECT-STRUCTURE.md	프로젝트 구조 상세
docs/markflow-prototype.html	UI 프로토타입