Skip to content

CLAUDE.md

Latest commit

 

History

History
209 lines (161 loc) · 9.68 KB

CLAUDE.md

File metadata and controls

209 lines (161 loc) · 9.68 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MandalGraph = 만다라트(Mandalart) + Graph Database + Radial Visualization

핵심 컨셉: 중심 목표에서 방사형으로 뻗어나가는 목표 관리 시스템

핵심 특징

특징 설명
Multi-Topology 사용자당 최대 5개의 독립 토폴로지(계획 그래프) 관리
방사형 레이아웃 9-Grid 셀이 아닌 중심에서 퍼지는 방사형
Depth 기반 구조 Root(0) → Level 1 → Level 2 → ...
강한 선 / 약한 선 직접 연결(Strong) vs 추론 연결(Weak)
Neo4j 그래프 DB 관계 중심 데이터 저장
인라인 편집 클릭하여 바로 수정 가능

Tech Stack

Backend: Spring Boot 3.2+, Java 17+, Spring Data Neo4j 7.x, Maven 3.9+, SpringDoc OpenAPI 2.x

Frontend: React 18.x, TypeScript 5.x, D3.js 7.x (radial visualization), Zustand 4.x, Axios 1.x, Tailwind CSS 3.x

Database: Neo4j 5.x (Docker container)

Common Commands

# Start Neo4j database
docker-compose up -d

# Backend (from project root)
cd backend && mvn spring-boot:run    # Run development server (port 8080)

# Frontend (from project root)
cd frontend && npm run dev           # Start Vite dev server (port 5173)

Access Points:

User Flow (PRD v3)

1. 로그인 (JWT 인증)
   └─→ 이메일/비밀번호 입력
   └─→ 회원가입 가능

2. 토폴로지 선택
   └─→ 사용자의 토폴로지 목록 (최대 5개)
   └─→ 토폴로지 생성/삭제
   
3. 노드/엣지 구조 관리
   └─→ 방사형 그래프 뷰
   └─→ 노드 생성: 테두리 드래그 / 캔버스 더블클릭
   └─→ 엣지 생성: 노드 테두리 → 다른 노드 드래그
   
4. 노드/엣지 세부 설정
   └─→ 인라인 편집: 제목, 설명, 상태, 우선순위
   └─→ 엣지 속성 편집

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Frontend (React)                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │ Radial View │  │ Detail Panel│  │ Navigation/Breadcrumb   │ │
│  │ (D3.js)     │  │ (InlineEdit)│  │                         │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
└────────────────────────────┬────────────────────────────────────┘
                             │ REST API
┌────────────────────────────▼────────────────────────────────────┐
│                    Backend (Spring Boot)                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │GoalController│ │RelationCtrl │  │ GraphController         │ │
│  └──────┬──────┘  └──────┬──────┘  └───────────┬─────────────┘ │
│         └────────────────┼─────────────────────┘               │
│                          │                                      │
│  ┌───────────────────────▼──────────────────────────────────┐  │
│  │                    Service Layer                          │  │
│  │  (GoalService, GraphService with APOC Subgraph Query)    │  │
│  └───────────────────────┬──────────────────────────────────┘  │
│                          │                                      │
│  ┌───────────────────────▼──────────────────────────────────┐  │
│  │              Neo4j Repository (Spring Data Neo4j)         │  │
│  └───────────────────────┬──────────────────────────────────┘  │
└──────────────────────────┼──────────────────────────────────────┘
                           │ Bolt Protocol
┌──────────────────────────▼──────────────────────────────────────┐
│                         Neo4j Database                          │
│                    (Docker Container)                           │
└─────────────────────────────────────────────────────────────────┘

Backend Structure (backend/src/main/java/com/mandalgraph/)

  • models/ - Neo4j entities: Goal, GoalStatus, GoalRelation
  • repositories/ - Spring Data Neo4j repositories with Cypher queries
  • services/ - GoalService, GraphService (APOC Subgraph Query)
  • dtos/ - CreateGoalRequest, UpdateGoalRequest, GraphData, GraphNode, GraphEdge, StatusSummary
  • controllers/ - GoalController, GraphController

Frontend Structure (frontend/src/)

  • components/graph/ - RadialGraph.tsx (D3.js), GraphControls.tsx, GraphLegend.tsx
  • components/panel/ - GoalDetailPanel.tsx (인라인 편집), GoalForm.tsx, StatusBadge.tsx
  • components/navigation/ - Breadcrumb.tsx, Header.tsx
  • components/sidebar/ - NodeList.tsx
  • stores/ - Zustand state: goalStore.ts, graphStore.ts
  • api/ - Axios clients: client.ts, goalApi.ts, relationApi.ts, graphApi.ts
  • types/ - TypeScript interfaces

Current Implementation Status (2026-01-26)

✅ Completed Features

Backend:

  • Spring Boot 3.2 + Maven project
  • Neo4j Docker container
  • Goal CRUD API
  • Relation API
  • Graph API (radial data with APOC)
  • JWT 인증 (Spring Security + JJWT)
  • AuthController (로그인/회원가입/me)
  • BCrypt 비밀번호 해싱

Frontend:

  • Vite + React + TypeScript + Tailwind
  • 방사형 그래프 렌더링 (D3.js)
  • 노드 드래그로 이동
  • 노드 테두리 드래그로 새 노드 + 엣지 생성
  • 캔버스 더블클릭으로 루트 노드 생성
  • 노드 더블클릭 → 해당 노드를 중심으로 이동
  • 인라인 편집 (제목, 설명, 상태, 우선순위 클릭하여 수정)
  • 노드 위치 캐싱 (새 노드 추가 시 기존 노드 위치 유지)
  • 노션 스타일 자동저장 (디바운스)
  • 우클릭 컨텍스트 메뉴
  • Weak Edge 토글
  • 엣지 클릭 → 편집 모달
  • 왼쪽 노드 목록 패널
  • JWT 토큰 관리 (Axios 인터셉터, Zustand persist)
  • 로그인/회원가입 페이지
  • Multi-Topology 지원

❌ Pending

  • 로딩 스피너 UX 개선
  • 에러 토스트 메시지
  • 노드 위치 DB 저장
  • 배포 설정

Node Interaction (Orange 3 Style)

노드 생성

방법 동작 결과
테두리 드래그 → 빈 공간 노드 테두리에서 드래그 시작 새 노드 + 엣지 생성
테두리 드래그 → 다른 노드 노드 테두리에서 드래그 시작 엣지만 생성
캔버스 더블클릭 빈 캔버스 영역 더블클릭 해당 위치에 새 노드
목록 드래그 앤 드롭 왼쪽 노드 목록 → 캔버스 노드 배치

노드/캔버스 이동 구분

  • 노드 중앙 드래그: 노드만 이동 (위치 캐시됨)
  • 노드 더블클릭: 해당 노드를 중심으로 그래프 재조정
  • 배경 드래그: 캔버스 패닝 (슬라이딩)
  • 마우스 휠: 줌 인/아웃

인라인 편집 (GoalDetailPanel)

필드 편집 방식
제목 클릭 → 인풋 필드 → Enter/blur로 저장
설명 클릭 → 텍스트에어리아 → Enter/blur로 저장
상태 버튼 3개 (대기/진행중/완료) 클릭 → 즉시 변경
우선순위 별 5개 클릭 → 즉시 변경

Visual Design Rules

Radial graph edge styling:

Element Strong Edge Weak Edge
stroke-width 3px 1.5px
stroke #3b82f6 #9ca3af
dasharray none 5,5
opacity 0.9 strength value

Radial layout: Nodes positioned in concentric circles based on distanceFromCenter, with RADIUS_PER_LEVEL = 150px.

Related Documents

  • INSTALL.md - 설치 가이드
  • MandalGraph_PRD_v3.md - 최신 PRD (Multi-Topology)
  • MandalGraph_PRD_v2.md - 이전 PRD (참조용)
  • PROGRESS.md - 상세 진행 상황
  • COLLAB.md - AI 협업 프로토콜