Show HN: 드래그 가능한 커스텀 기능이 있는 코드 기반 다이어그램 도구

개요 (Overview)

oxdraw의 목표는 선언적(declarative)이고 재현 가능한(reproducible) 구문을 사용하여 고품질의 다이어그램을 쉽게 생성하고 유지 관리하는 것입니다.
차트는 Mermaid 구문으로 작성되며, 웹 인터페이스를 통해 사용자가 위치, 커넥터 경로(connector paths), 색상 및 기타 스타일링 구성 요소를 미세 조정할 수 있습니다. 다이어그램을 시각적으로 수정할 때마다, 구조적 변경 사항은 선언적 코드로서 소스 파일에 다시 저장되므로 모든 것이 결정론적(deterministic)이고 버전 관리가 가능한 상태로 유지됩니다.
일반적인 다이어그램 외에도, oxdraw는 이미지를 다이어그램에 직접 삽입할 수 있으며, 노드가 코드 세그먼트(code segments)에 연결된 코드베이스의 코드맵(codemaps)을 볼 수 있습니다.
변경 사항은 mermaid 파일 내의 주석으로 저장되므로 다른 Mermaid 도구들과 호환성을 유지합니다.
이 저장소(repo)는 .mmd 파일을 이미지로 컴파일하는 Rust CLI, 파일을 편집하기 위한 React 기반 웹 인터페이스, 그리고 코드맵의 자동 생성을 위한 몇 가지 AI 및 정적 분석(static analysis) 알고리즘 옵션으로 구성되어 있습니다.

여기에서 자유롭게 체험해 보세요. Rust로 작성된 알고리즘은 wasm으로 컴파일되므로 정적 사이트(static site)로 쉽게 배포할 수 있습니다.

비전 (Vision)

이 프로젝트를 시작한 이유는 과거에 아키텍처 다이어그램을 그리거나, AI 도구가 생성한 .mmd 파일을 시각화하여 대규모 코드베이스 (codebases)를 이해하려고 할 때 Mermaid를 많이 사용했기 때문입니다. 하지만 일반적으로 발생하는 문제는, 이러한 다이어그램들이 연결 지점 (joints) 정리나 차트 구성과 같이 세밀하게 편집될 수 없었기 때문에, 결국 작성하던 다이어그램을 Lucidchart와 같은 도구로 옮겨야만 했다는 점입니다. 따라서 이 프로젝트의 큰 목표는 Mermaid와 같은 코드 생성 기반 다이어그램 (code generated diagramming)의 장점과 Lucidchart와 같은 다이어그램 소프트웨어의 커스터마이징 (customizability) 가능성을 결합하는 것입니다.

사용법 (Usage)

Cargo를 통한 설치

cargo install oxdraw

파일로부터 다이어그램 렌더링

oxdraw --input flow.mmd

대화형 에디터 (Interactive Editor) 실행

oxdraw --input flow.mmd --edit

다이어그램을 공유하기 위한 현재 두 가지 옵션이 있습니다:

이미지 (png 또는 svg)로 내보내기.
정적 사이트의 공유 버튼 사용. 이 기능은 다이어그램을 URL의 해시 프래그먼트 (hash fragment)에 저장하여, 동료들이 당신이 만든 다이어그램을 확인하고 편집할 수도 있게 합니다.

간트 차트 (Gantt) 구문

기본적인 플로우차트 (flowcharts) 외에도, CLI를 사용하여 Mermaid 구문의 간트 차트 (Gantt charts)를 렌더링할 수 있습니다.

또한 --edit 플래그를 사용하여 웹 에디터에서 쉽게 수정할 수 있으며, 변경 사항은 파일에 동기화됩니다.

AI를 이용한 코드맵 (Codemap) 생성

이 명령은 노드 (nodes)를 저장소 (repo)의 파일과 매핑하는 대화형 뷰어를 실행합니다. AI 액세스 설정을 위한 무료 리소스는 ai.md를 참조하세요.

oxdraw --code-map ./ --gemini YOUR_API_KEY
# 또는 AI 액세스가 설정되어 있지 않다면, 이 간단한 정적 분석 (static analysis) 기반 코드맵 생성기를 사용하여 기능을 살펴볼 수 있습니다:
oxdraw --code-map ./src/diagram.rs --no-ai --output test.png

AI를 이용한 Codedown (Markdown + Code Mappings) 생성

"Codedowns"는 임베디드 매핑 메타데이터 (embedded mapping metadata)를 포함하는 Markdown 문서로, 이를 통해 에디터가 제목/단락/인라인 코드 (inline code)를 클릭 가능하게 만들고 코드베이스 (codebase)로 바로 이동할 수 있게 합니다.
명시적인 매핑 외에도, oxdraw는 인라인 코드 블록 (inline codeblocks)을 코드베이스 내의 정의 (definitions)로, 파일명 (filenames)을 관련 파일로 자동 매핑합니다.

--codedown-style은 내장된 프롬프트 프리셋 (prompt preset) (architecture/tutorial/api)을 선택합니다. --prompt를 통해 추가 지침을 덧붙여 출력을 더욱 세밀하게 조정할 수 있습니다.

# 리포지토리 (repo)로부터 codedown을 생성하고 뷰어 (viewer)를 실행합니다
oxdraw --codedown ./ --gemini YOUR_API_KEY

...

기존 Markdown 파일에 코드 매핑 추가하기

이미 Markdown 문서 (예: docs/notes.md)가 있고, 뷰어에서 클릭 가능하도록 매핑을 추가하고 싶은 경우:

# 기본적으로 docs/notes-mapped.md를 생성합니다
oxdraw --augment-markdown docs/notes.md --repo-path . --gemini YOUR_API_KEY

...

Codedown 보기

--input을 통해 .md 파일을 전달하고 해당 파일에 codedown 매핑이 포함되어 있다면, oxdraw는 이를 codedown 뷰어에서 엽니다.

oxdraw --input docs/architecture.md

기능 (Features)

CLI 플래그 (CLI Flags)

플래그 (Flag)	설명 (Description)
`-i, --input <PATH>`	Mermaid 소스 파일을 읽습니다. 대신 stdin을 사용하려면 `-`를 전달하세요.
...

프론트엔드 기능 (Frontend Features)

컨트롤 (Control)	기능 (What it does)
`Delete selected`	현재 선택된 노드 (node) 또는 엣지 (edge)를 제거합니다. Delete/Backspace 키로도 사용할 수 있습니다.
...

캔버스 및 에디터 상호작용 (Canvas and editor interactions)

노드를 드래그하여 그리드 스냅 (grid snapping) 및 실시간 정렬 가이드 (live alignment guides)와 함께 저장된 위치를 업데이트할 수 있습니다. Shift+방향키를 사용하면 선택된 요소를 그리드 크기 단위로 미세하게 이동(nudge)할 수 있습니다.
에지 핸들(edge handles) 또는 레이블 핸들(label handle)을 드래그하여 경로(routes)의 모양을 변경할 수 있습니다. 에지를 더블 클릭하면 핸들을 삽입할 수 있고, 핸들을 더블 클릭하면 오버라이드(overrides)를 제거할 수 있습니다.
서브그래프 컨테이너(subgraph container) 전체를 드래그하면 형제 그룹(sibling groups)과의 분리 상태를 유지하면서 해당 컨테이너에 속한 모든 멤버 노드(및 모든 에지 오버라이드)를 함께 이동할 수 있습니다.
소스 패널(source panel)은 Mermaid 파일을 미러링하며, 짧은 유휴 시간(idle periods) 후에 자동 저장됩니다. 또한 현재 선택 사항과 함께 대기 중/저장 중/오류 상태를 표시합니다.
상단 툴바의 상태 텍스트는 로딩, 저장 및 현재 편집 중인 파일 경로를 알려줍니다.

다이어그램 알고리즘 (The Diagram Algorithm)

경로 그리기 알고리즘은 최적의 동작이 무엇인지에 대해 많은 모호함이 존재하기 때문에 매우 흥미롭습니다.
어떤 이들은 전체 선의 길이를 줄이기 위해 부드러운 선(smooth lines)을 선호하지만, 저는 다이어그램을 조금 더 명확하게 만들기 위해 강한 에지(strong edges)를 선호합니다.
어떤 이들은 선이 겹치지 않는 것을 선호하지만, 저는 선이 너무 길어져서 다이어그램 밖으로 멀리 뻗어 나가는 것보다는 때때로 겹치는 것을 선호합니다.
어떤 이들은 전체적인 조인트(joints)가 적은 것을 선호하는데, 이는 직교 선(orthogonal lines)을 선호하는 사람들의 취향과는 정반대되는 것입니다.
다음은 Delete 키를 사용하여 하나의 관계를 제거한 다음, 방향키를 사용하여 노드를 이동시키며 알고리즘이 위치를 어떻게 재계산(recomputes)하는지 확인하는 예시입니다.
이 알고리즘에는 분명 개선할 점이 있으며, 따라서 앞으로 계속 좋아질 것이고 결국 다양한 선호도에 따른 변형(variants)들도 추가될 것이라고 상상합니다 :)

커뮤니티 (Community)

만약 oxdraw를 사용하게 되거나 oxdraw에 기여하는 것에 관심이 있다면, 저의 Discord의 oxdraw 채널로 메시지를 보내주시거나, Github Issue를 오픈하거나, PR(Pull Request)을 제출해 주세요. 여러분이 어떻게 사용하고 계시는지, 어떤 피드백이 있는지 듣고 싶으며, 여러분의 프로젝트를 이 섹션에 추가하는 것도 환영합니다!

oxdraw를 활용한 다음 프로젝트들을 확인해 보세요:

Typst-Oxdraw는 oxdraw 다이어그램을 Typst 문서에 통합하는 저장소 (repo)입니다.
Asciidoctor는 oxdraw 지원 기능을 갖추고 있습니다.
oxmap은 .mmd 파일 플로우차트 (flowchart)를 생성하는 TUI이며, 경로 그리기 알고리즘 (path drawing algorithm)을 위한 라이브러리 (library)로 Oxdraw를 사용합니다.