OPEN GRID는 의존성 없는 오픈소스 데이터 그리드입니다. 그동안 코드와 데모, 개발자 가이드를 공개해 왔는데, 이번에는 조금 다른 걸 올렸습니다. 내부 구조를 설명하는 설계도(UML) 8종입니다. 함께 문서 표현을 다듬는 작업도 계속하고 있어, 그 이야기를 정리해 둡니다.
왜 설계도를 공개하나
npm으로 패키지 하나를 받으면, 안에 무엇이 어떻게 얽혀 있는지는 결국 코드를 열어 봐야 알 수 있습니다. 규모가 커질수록 이 과정이 부담스럽습니다. 사람이든, 요즘은 코드를 읽어 주는 AI든, 매번 처음부터 전체 구조를 되짚는 건 비효율적입니다.
그래서 구조를 먼저 보여 주는 그림을 함께 두기로 했습니다. 어떤 부품이 있고, 데이터가 어디서 들어와 어떻게 화면까지 가는지, 그리드와 차트가 어떻게 맞물리는지를 한눈에 훑을 수 있으면, 코드를 읽기 전에 지형을 파악하고 시작할 수 있습니다.
공개 형식도 그 목적에 맞췄습니다. 그림 이미지만이 아니라 소스인 .puml 파일과 렌더 이미지(SVG/PNG)를 같이 올렸습니다. PlantUML로 작성했기 때문에, 다른 도구나 AI가 .puml을 그대로 열어 읽거나 고칠 수 있고, 이미지는 바로 보기만 하면 됩니다. 텍스트로 된 설계도라 검색·비교·수정이 편합니다.
공개한 UML 8종
버전 1.3 아키텍처 기준입니다. 코어 아키텍처 3종과 ECharts 통합 5종으로 나뉩니다. 각 다이어그램을 짧게 풀어 설명합니다.
코어 아키텍처
컴포넌트 아키텍처. 그리드를 이루는 부품 전체를 한 장에 담은 지도입니다. 가운데에 창구 역할을 하는 OpenGrid(파사드)가 있고, 그 둘레로 데이터·렌더링·정렬/필터·편집·범위 선택·수식·크로스그리드·마스터/디테일·통합 차트·조건부 서식·실시간·외관/스킨·다국어·내보내기·오버라이드 같은 하위 기능들이 붙습니다. 코어는 외부 라이브러리에 의존하지 않는다는 점(제로 의존성)도 이 그림에서 드러납니다.
파사드 클래스 구조. 앞의 OpenGrid가 실제로 각 기능 매니저들을 어떻게 거느리는지를 보여 줍니다. 상속으로 쌓아 올리는 대신, 필요한 매니저들을 안에 두고(합성) 필요한 것을 주입해서 씁니다. 자주 쓰는 공개 메서드도 함께 표시해, “어디에 대고 무엇을 호출하면 되는지”를 가늠할 수 있습니다.
렌더 시퀀스. 데이터를 넣었을 때 화면에 셀이 그려지기까지의 순서를 시간 흐름으로 따라갑니다. setData로 데이터가 들어오면 변경 사항이 정리되고, 스크롤 위치에 맞춰 화면에 지금 보이는 부분만 DOM으로 만듭니다. 수십만 행이어도 보이는 만큼만 그리기 때문에 무겁지 않은데, 그 원리가 이 그림에 담겨 있습니다.
ECharts 통합
그리드를 Apache ECharts와 이어 붙여 표와 차트를 함께 쓰는 통합 방식입니다. 중요한 전제는 그리드 코어를 고치지 않는다는 점입니다. 통합은 어댑터(연동 코드)가 맡고, 그리드는 공개된 데이터·이벤트만 내어 줍니다.
비침습 통합 구조. 그리드 코어(무수정), 둘을 잇는 어댑터, 외부 차트 라이브러리(ECharts)가 각각 어떤 자리에 놓이는지 보여 줍니다. 코어를 손대지 않고도 차트를 얹을 수 있도록, 경계와 역할을 나눈 그림입니다.
그리드에서 차트로. 표에서 일어난 일(정렬·필터·데이터 변경 등)이 차트에 반영되는 흐름입니다. 어댑터가 그리드의 공개 이벤트를 구독하고, 공개 API로 현재 데이터를 읽어 차트를 갱신합니다.
차트에서 그리드로. 반대 방향입니다. 차트에서 특정 지점을 클릭하는 등의 조작을, 그리드의 공개 API를 통해 표 쪽으로 되돌립니다. 이때 어느 행에 대응하는지를 알려 주는 표식(__ri)을 이용해 정확한 행을 짚습니다.
데이터 파이프라인. 데이터가 어디서 출발해 어떤 손질을 거쳐 차트로 가는지를 한 줄기로 정리했습니다. 그리드가 원본(단일 기준점) 역할을 하고, 어댑터가 표준 차트 설정으로 바꿔 렌더합니다. 이 데이터가 어디서 왔는지 알려 주는 표시(프로비넌스 배지)와, 차트를 텍스트로도 읽을 수 있게 하는 등가 정보까지 포함합니다.
차트 생명주기. 차트 인스턴스가 만들어져(로드) 쓰이다가(활성) 정리되기까지의 상태 변화를 담았습니다. 화면을 오가며 차트를 켜고 끌 때 자원이 새지 않도록, 언제 만들고 언제 치우는지를 정해 둔 그림입니다.
가이드와 JSDoc도 계속 다듬는 중
설계도와는 별개로, 글로 된 문서도 손보고 있습니다. 개발자 가이드와 코드 안의 JSDoc 주석을 더 읽기 쉬운 표현으로 다시 쓰는 작업입니다.
기술 문서는 시간이 지나면 내부에서만 통하는 약칭, 번역투 문장, 맥락 없이는 뜻을 알기 어려운 표현이 쌓이기 쉽습니다. 그런 것들을 걷어내고, 실제 쓰임과 문맥에 맞는 자연스러운 한국어로 바꾸고 있습니다. 기준은 하나입니다. 매뉴얼은 연설문이 아닙니다. 보고 그대로 따라 하면 되도록.
이 작업은 한 번에 끝나는 종류가 아니라, 눈에 띄는 대로 계속 다듬어 가는 중입니다. 아직 손이 덜 간 부분도 있습니다. 그 점은 솔직히 말씀드립니다.
어디서 볼 수 있나
공개 위치는 GitHub 저장소 github.com/farmerkweon/OpenGrid의 docs/design/uml/ 폴더입니다. 소스(.puml)와 렌더 이미지가 함께 들어 있습니다. 그림을 그대로 보셔도 되고, .puml을 열어 각자 도구로 다시 렌더하거나 수정하셔도 됩니다.
코드를 처음 여는 분이든, 구조만 빠르게 확인하려는 분이든, 이 그림들이 출발점을 조금 앞당겨 주면 좋겠습니다.