▲

oxdraw - 코드 기반 다이어그램 도구

 (github.com/RohanAdwankar)
22P by GN⁺ 9일전 | ★ favorite | 댓글 1개
  • oxdraw는 Rust로 작성된 ‘Diagram as Code’ 도구로, 코드 기반 다이어그램을 시각적으로 편집하고 재현 가능한 형태로 유지하도록 설계됨
  • 다이어그램은 Mermaid 문법으로 작성되며, 웹 인터페이스를 통해 노드 위치, 색상, 연결선 등을 드래그로 조정 가능
  • 시각적 수정 내용은 Mermaid 파일 내 주석 형태로 저장되어 다른 Mermaid 도구와의 호환성을 유지함
  • CLI와 React 기반 웹 편집기로 구성되어 있으며, 명령줄 렌더링과 실시간 편집 모드 모두 지원
  • 코드 생성형 다이어그램의 생산성과 시각적 편집의 자유도를 결합해, Lucidchart와 같은 GUI 도구의 대안으로 주목받음

프로젝트 개요

  • oxdraw의 목표는 선언적이고 재현 가능한 문법을 통해 고품질 다이어그램을 쉽게 생성·유지하는 것임
    • 다이어그램은 Mermaid 문법으로 작성되며, 시각적 조정은 웹 인터페이스에서 수행
    • 사용자가 시각적으로 수정한 내용은 원본 코드에 반영되어 버전 관리와 자동화가 가능
  • 수정 내용은 Mermaid 파일 내 주석(comment) 형태로 기록되어, Mermaid 생태계의 다른 도구와 완전한 호환성 유지
  • 저장소는 Rust 기반 CLI와 React 기반 웹 인터페이스로 구성되어 있으며, CLI는 .mmd 파일을 이미지로 컴파일함

프로젝트 비전

  • 개발자는 과거 Mermaid를 활용해 아키텍처 다이어그램이나 코드베이스 시각화를 수행했으나, 세밀한 편집 한계로 인해 Lucidchart 등으로 옮겨야 했음
  • oxdraw는 Mermaid의 코드 기반 자동화와 Lucidchart의 시각적 자유도를 결합하는 것을 목표로 함
  • 이를 통해 코드 생성형 다이어그램의 재현성, 협업성, 자동화 가능성을 유지하면서도, 시각적 완성도를 높이는 방향을 지향

사용 방법

  • Cargo를 통해 설치 가능: cargo install oxdraw
  • 다이어그램 렌더링: oxdraw --input flow.mmd
  • 인터랙티브 편집기 실행: oxdraw --input flow.mmd --edit
  • CLI는 Mermaid 파일을 입력받아 SVG 또는 PNG 출력을 생성하며, --edit 옵션으로 로컬 웹 편집기를 실행

CLI 플래그 설명

  • -i, --input : Mermaid 소스 파일 입력
  • -o, --output : 렌더링 결과물 저장 경로 지정
  • --png: PNG 형식으로 출력
  • --scale : PNG 렌더링 배율 조정 (기본값 10.0)
  • --edit: 시각적 편집기 실행
  • --serve-host / --serve-port : 편집기 서버의 주소 및 포트 지정 (기본 127.0.0.1:5151)
  • -b, --background-color : 배경색 지정 (SVG 전용)
  • -q, --quiet: 렌더링 완료 메시지 등 출력 억제

프런트엔드 기능

  • 노드 및 엣지 조작
    • 선택된 노드나 엣지 삭제 (Delete/Backspace 키 지원)
    • 노드 색상, 테두리, 텍스트 색상 개별 지정 및 초기화
    • 엣지 색상, 선 스타일(실선/점선), 화살표 방향 설정
    • 엣지 경로에 드래그 가능한 제어점(control point) 추가 및 제거
  • 캔버스 및 편집기 상호작용
    • 노드 드래그 시 격자 스냅 및 정렬 가이드 표시
    • Shift+화살표로 노드 이동
    • 엣지 핸들을 드래그해 경로 수정, 더블클릭으로 핸들 추가/삭제
    • 서브그래프 단위 이동 지원 — 그룹 내 노드 및 엣지 함께 이동
    • 소스 패널은 Mermaid 파일을 실시간 반영하며, 자동 저장 및 상태 표시(저장 중/오류 등) 제공
    • 상단 툴바에는 현재 파일 경로 및 저장 상태 표시

기술 구성 및 라이선스

  • Rust 55.7% , TypeScript 40.0% , CSS 3.4% , 기타 0.9%로 구성
  • MIT 라이선스로 공개되어 자유로운 사용 및 수정 가능
  • 현재 506개의 Star, 10개의 Fork를 보유하며, 활발한 커뮤니티 관심을 받고 있음

종합 평가

  • oxdraw는 코드 기반 다이어그램 관리의 자동화와 시각적 편집의 직관성을 결합한 새로운 접근
  • Mermaid 생태계와의 완전한 호환성을 유지하면서, Rust의 성능과 React의 인터랙티브 UI를 활용
  • 개발자와 디자이너 모두에게 협업 가능한 다이어그램 워크플로우를 제공하는 도구로 주목받는 중
▲
GN⁺ 9일전  [-]
Hacker News 의견

  • 정말 멋진 프로젝트임. Mermaid.js를 기반으로 한 선택이 현 시점에서 가장 인기 있는 선언적 다이어그램 라이브러리라 생각함
    더 복잡한 다이어그램 타입을 지원하려면 D2 Language도 살펴볼 만함. 훨씬 유연한 선언적 접근법을 제공함

  • 개인적으로 MacPorts 포트를 만들어서 사용 중임
    자주 쓰게 되면 공식 MacPorts 저장소에 기여할 생각임
    다만 Cargo 릴리스와 연동된 Git 태그나 GitHub 릴리스가 없어서 패키징이 불편함
    지금은 특정 커밋(9ccd9bf53f9a309ccda42b5c17e9c1056493fb90)을 0.1.0 릴리스로 가정해 임시로 해결 중임
    관련 포트는 여기에서 볼 수 있음

  • 이 프로젝트는 정말 내가 찾던 바로 그거임. 선언적 다이어그램 솔루션에서 꼭 보고 싶은 기능이 있음
    바로 마우스 오버 시 추가 정보나 중첩 다이어그램을 보여주는 팝업 기능임

    • 흥미로운 아이디어임. 혹시 그 팝업은 개인용인지, 아니면 팀원에게 공유하기 위한 용도인지 궁금함
      예를 들어 링크를 공유하면 팝업과 중첩이 포함된 다이어그램을 바로 볼 수 있게 하고 싶은 건지,
      아니면 .mmd 파일만 공유해서 CLI로 열면 되는 수준이면 충분한지 알고 싶음
      후자는 금방 구현 가능하지만, 전자는 ngrok 같은 셀프 호스팅이나 클라우드 배포가 필요할 수도 있음
      혹은 HTML 파일로 내보내기(export) 기능을 추가해 CLI 없이도 팝업이 작동하도록 할 수도 있음

  • 프로젝트 공개를 축하함. 선언적 문법으로 관계를 정의하고, 기존 자동 레이아웃이 못 하는 세밀한 커스터마이징을 가능하게 한 점이 인상적임
    다만 Cargo.toml에는 MIT 라이선스로 표시되어 있지만, 저장소에 라이선스 파일이 없음
    GitHub에서 바로 확인할 수 있도록 추가해주면 좋겠음

    • 도구의 채택률을 높이려면 호스팅을 고려해보길 권함. 서버 사이드 코드 의존도가 높아 무료 정적 호스팅은 어려워 보임
    • 라이선스 파일 추가 완료함. 알려줘서 고마움

  • 정말 필요한 프로젝트임. 나는 주로 PlantUML을 쓰는데, 컴포넌트가 5개만 넘어도 레이아웃 조정에 20~30%의 시간을 씀
    주석을 활용해 레이아웃 엔진에 반영하는 접근이 흥미로움. 특정 컴포넌트의 좌표를 고정된 제약조건으로 두고 나머지를 자동 배치하는 방식이 유용할 듯함
    코드 변경과 함께 다이어그램도 버전 관리에 포함되면 코드 리뷰와 아키텍처 관리가 훨씬 자연스러워짐

    • 나도 GitLab에서는 PlantUML을 쓰지만, GitHub에서는 Mermaid를 써야 해서 번거로움
      Mermaid의 레이아웃 품질이 낮고, GitHub가 PlantUML 지원 요청을 무시하는 게 아쉬움
      주요 플랫폼이 지원하는 포맷에 따라 ‘diagrams as code’의 채택률이 결정되는 듯함
      새로운 표준을 만드는 것보다는, 요소 가중치 기반 렌더링 같은 개선이 더 현실적이라 생각함
      관련 논의는 GitHub 커뮤니티 토론에서도 다뤄지고 있음

  • PlantUML이 이런 문제를 해결해줬으면 좋겠다는 바람이 큼

  • 이건 마치 Graphviz의 dot 언어를 강화한 버전 같음
    변수와 더 깔끔한 문법을 제공하지만 기본 개념은 유사함
    Graphviz 문서 참고

  • Mermaid.js에는 레이아웃 엔진 개념이 있음
    @mermaid-js/layout-elk처럼
    혹시 네 알고리즘을 Mermaid용 자동 레이아웃 엔진으로 구현할 생각은 없는지 궁금함

  • 멋진 프로젝트임. 모바일에서 봤는데 노드 추가 버튼이 안 보임
    또 하나 바라는 기능은 하위 노드 접기(collapse downstream nodes) 기능임. 범위를 벗어날 수도 있지만 있으면 좋겠음

    • 현재는 .mmd 텍스트를 직접 수정해야 함. 하지만 좋은 제안이라 생각함
      하위 노드 접기 기능은 다른 사용자가 요청한 애니메이션 기능과도 잘 맞을 듯
답변달기