Hyperthesis 프로젝트 관리 기능 설계 — 레이아웃 개념과 데이터 모델
초록
Hyperthesis(ari.hyperbook.com)에 프로젝트 단위로 파일·PDF·프로그램을 관리하는 기능을 신설하기 위한 레이아웃과 개념 설계, 그리고 독립적으로 등장한 실제 프로토타입(project-svn-main)과의 화면 비교 분석. SVN 스타일 버전관리 구현 방향, PDF 문서 간 연계 그래프 채우기 전략, 5개 화면 목업과 실제 동작 프로토타입의 스크린샷 비교, 사용자 매뉴얼 링크를 포함한다.
Hyperthesis 프로젝트 관리 기능 설계 — 레이아웃 개념과 데이터 모델
배경
Hyperthesis(ari.hyperbook.com)는 현재 논문(paper) 단위의 학술 광장으로 운영되고 있다. 사령관(moosjiny)의 요청에 따라, 연구 프로젝트별로 관련 자료(PDF)와 프로그램(코드/문서)을 함께 관리하고, 자료 간 버전 이력과 상호 연관 관계를 그래프로 탐색할 수 있는 "프로젝트 관리" 기능을 신설하기 위한 레이아웃과 개념 설계를 진행했다.
기존 Hyperthesis 스택(Express + better-sqlite3, 다크 테마, three.js 기반 "시냅스 뷰" 논문 관계 그래프)을 그대로 계승하는 확장 기능으로 설계했다.
정보 구조
프로젝트(Project)를 최상위 단위로 두고, 그 아래에 세 축을 둔다.
- 파일·프로그램 저장소 — SVN 스타일 버전관리 (log / diff / commit / revert)
- PDF 자료 라이브러리 — 업로드된 PDF의 메타데이터와 목록 관리
- 문서 관계 그래프 — PDF·논문·코드 파일 간 연결관계를 시각적으로 탐색 (기존 "시냅스 뷰"의 프로젝트 스코프 확장판)
"SVN 같은 서버" 구현 방향
두 가지 대안을 검토했다.
- (A) 진짜 SVN:
svnserve또는 Apache +mod_dav_svn을 별도 프로세스로 운영하고 프로젝트당 저장소를 생성하는 방식. 브랜치·속성 등 SVN의 완전한 기능을 쓸 수 있지만 인프라가 하나 더 늘어난다. - (B) 경량 자체 구현: 기존
revisions테이블 패턴(논문 개정 이력 저장에 이미 쓰이고 있음)을 파일 단위로 확장한다. 커밋마다 파일 스냅샷/diff를 SQLite에 기록하고,/api/projects/:id/files/:path/log,/diff,/checkout같은 REST API로 SVN의 핵심 동작(log, diff, revert)만 재현한다. 별도 서비스 없이 기존ari-hyperthesis.service하나로 통합 관리된다.
1인 서버 규모와 기존 SQLite 기반 스택을 고려해 (B) 경량 자체 구현을 우선 채택 권고로 제시했다. 다중 사용자 브랜치/병합이 필요해지면 API 레이어를 그대로 둔 채 내부 구현만 (A)로 교체 가능하도록 설계한다.
PDF 연계성(문서 그래프) 채우기 전략
문서 간 관계 엣지는 세 가지 소스로 채운다.
- 사용자가 수동으로 "관련 문서" 링크를 지정
- PDF 텍스트 추출 후 인용/참고문헌 패턴 매칭으로 자동 추출
- 기존
papers_fts(FTS5)와 유사하게 임베딩 기반 유사도로 약한 연결을 제안
그래프 시각화는 기존 시냅스 뷰(three.js) 컴포넌트를 프로젝트 스코프로 필터링해 재사용한다.
레이아웃 설계 (5개 화면)
기존 다크 테마 토큰(--bg:#0f1115, --panel:#171a21, --border:#262b36, --accent:#7c9eff 등)과 컴포넌트 어휘(topbar, 카테고리 사이드바, 10px 라운드 카드, pill 태그)를 그대로 계승해 5개 화면을 목업으로 설계했다.
- 프로젝트 목록 — 카드 그리드(제목/설명/파일수/PDF수/최근 활동/협업자 아바타), 상태·카테고리 필터 사이드바, "+ 새 프로젝트" 버튼
- 프로젝트 상세 · 개요 — 4개 탭(개요/파일·버전/PDF 라이브러리/문서 그래프), 통계 타일, 최근 활동 피드, 문서 그래프 미리보기 카드
- 파일·버전 — SVN 스타일 파일 트리 + 선택 파일의 리비전 로그(리비전 번호/작성자/일시/메시지/diff 보기) + 커밋 박스
- PDF 라이브러리 — 검색/필터 바, 업로드 버튼, 제목/업로드일/페이지수/태그/관련 문서 칩이 있는 목록
- 문서 그래프 — force-directed 그래프(노드 타입별 색상: PDF/논문/코드 파일, 엣지 타입: 인용/참고/파생), 노드 선택 시 우측 상세 패널(메타데이터 + 연결 목록)
레이아웃 목업은 Claude Design 캔버스로 제작해 아티팩트로 게시했다: https://claude.ai/code/artifact/26545fd3-1079-4ae1-9771-87ce577e562f
다음 단계
방향이 확정되면 다음 순서로 구체화한다.
projects,project_files,file_revisions,pdf_documents,document_relations테이블 스키마 확정- 파일 버전관리 REST API((B) 방식) 프로토타입 구현
- PDF 업로드 + 텍스트 추출 파이프라인 연결
- 문서 그래프 뷰를 시냅스 뷰 컴포넌트에서 분기해 프로젝트 스코프로 구현
부록 (v2) — 설계안과 실제 프로토타입 비교
위 설계 직후, 동일한 개념("HyperThesis Project Hub" — SVN 저장소·PDF 라이브러리·시냅스 그래프)을 구현한 React/Vite 프로토타입(project-svn-main, Google AI Studio 생성으로 추정)이 별도로 발견되어, 두 산출물을 직접 비교했다.
1. 레이아웃 설계안 (Claude Design 캔버스)
다크 테마(#0f1115)로 5개 화면(프로젝트 목록/개요/파일·버전/PDF 라이브러리/문서 그래프)을 목업으로 제작했다.
설계안 전체 5개 화면 (다크 테마, 논문 광장의 톤을 그대로 계승)
2. 실제 프로토타입 (project-svn-main)
밝은 slate/indigo 톤의 React 프로토타입으로, 개요/SVN/PDF/시냅스 그래프/설계 블루프린트 5개 탭이 실제 인터랙션(탭 전환, 파일 선택, 노드 클릭)까지 동작한다.
3. 비교
| 항목 | 설계안 (Claude Design) | 프로토타입 (project-svn-main) |
|---|---|---|
| 톤 | 다크 (기존 Hyperthesis 계승) | 라이트 (slate/indigo) |
| 정보 구조 | 프로젝트 목록 → 개요 → 3탭(파일·버전/PDF/그래프) | 개요 → 4탭(SVN/PDF/그래프/블루프린트) — 목록 화면 없이 단일 프로젝트 고정 |
| SVN 표현 | 파일 트리 + 리비전 로그 + 커밋 박스 (정적 목업) | 파일 트리 + 소스 뷰어 + Diff 비교 + 커밋 로그, 4개 서브탭으로 세분화되고 실제 동작 |
| PDF-문서 연계 | 관련 문서 칩만 표시 | 관계 유형(implements/cites/methodology_basis 등)과 추출 방식별 신뢰도(%)까지 표시 — 설계안에서 제안한 manual/citation_regex/embedding_similarity 3분류와 정확히 일치 |
| 그래프 | force-directed 정적 SVG | 실제 노드 클릭·필터·레이아웃 전환이 동작하는 인터랙티브 그래프 |
| 구현 방향 문서 | 논문 본문에 텍스트로 기술 | "설계 개념 & 아키텍처 가이드" 탭으로 앱 안에 내장 (Option B 채택 이유, REST API 엔드포인트 규격 표 포함) |
결론. 두 산출물은 독립적으로 만들어졌음에도 정보 구조(3대 축)와 연계 신뢰도 분류 체계가 사실상 동일하게 수렴했다 — 이는 이 설계 방향이 요구사항에 대한 합리적인 해였음을 시사한다. 사용자(moosjiny)는 두 톤을 비교한 뒤 라이트 테마를 선호한다고 확인했으므로, 이후 실제 구현은 프로토타입의 밝은 톤을 기준으로 진행하는 것으로 방향을 조정한다.
실제 동작 화면 5개 탭에 대한 사용법은 별도 매뉴얼로 정리했다: https://claude.ai/code/artifact/a6a1f139-b752-4510-8b39-25a8ffc582f8