다이어그램 문서 체계 재검토: dbdiagram.io + Mermaid 유지 여부와 대안 평가

[SolfE]

배경

현재 코드베이스 다이어그램 도구로 dbdiagram.io(DBML) 와 Mermaid 를 채택해 사용하고 있다.

• MongoDB 논리 ERD는 dbdiagram.io 에서 사용할 수 있는 DBML로 관리
• 구조/흐름/상태 전이는 Mermaid 문서로 관리

이 조합은 가볍고 저장소 친화적이지만, 앞으로 문서 유지비와 실효성을 기준으로 계속 유지할지 한 번 점검할 필요가 있다.

왜 지금 검토가 필요한가

• content/book 같은 DB 최적화 미션을 진행하면서 ERD와 흐름 문서의 역할이 더 분명해짐
• MongoDB 특성상 물리 스키마와 논리 관계를 어떻게 표현할지 기준이 필요함
• 도구를 늘리기보다, 현재 도구 조합이 실제 협업/리뷰/리팩터링에 충분한지 먼저 확인해야 함

현재 안의 장점

• 저장소 안에서 텍스트 기반으로 버전 관리 가능
• 리뷰 diff 확인이 쉬움
• 학습용/설계용 문서 작성 속도가 빠름
• 구조 다이어그램과 흐름 다이어그램의 역할 분리가 비교적 명확함

현재 안의 한계

• dbdiagram.io 는 MongoDB의 embedded document, polymorphic reference 표현이 제한적임
• Mermaid 는 복잡한 구조를 세밀하게 표현하기엔 금방 읽기 어려워짐
• 논리 ERD와 실제 코드/인덱스 상태가 쉽게 어긋날 수 있음
• 어떤 문서는 Mermaid, 어떤 문서는 DBML, 어떤 내용은 prose 로 남길지 기준이 아직 느슨함

검토할 옵션

1. 현행 유지

• ERD는 DBML, 구조/흐름은 Mermaid로 유지
• 대신 문서 작성 규칙만 더 명확히 함

2. 현행 유지 + 규칙 강화

• Mermaid / DBML / prose 의 역할을 명시적으로 구분
• 핵심 도메인만 축약 ERD를 두고, 전체 ERD는 보조 문서로 둠
• 인덱스/병목 포인트는 별도 문서 또는 note 규칙으로 관리

3. 구조 다이어그램 도구 재검토

• 예: Structurizr(C4), PlantUML, Excalidraw 계열 등
• 다만 저장소 친화성, diff 가독성, 도입 비용을 같이 평가해야 함

4. 생성 기반 접근 일부 도입

• 코드나 스키마에서 자동 생성 가능한 다이어그램이 있는지 검토
• 수동 문서 유지 비용을 줄일 수 있는지 평가

판단 기준

• 저장소 안에서 관리하기 쉬운가
• diff 리뷰가 쉬운가
• MongoDB 특성을 무리 없이 설명할 수 있는가
• 성능 최적화/리팩터링 논의에 실제로 도움이 되는가
• 신규 문서 추가 시 작성 부담이 과하지 않은가
• 특정 SaaS 또는 외부 편집기에 과도하게 종속되지 않는가

기대 결과

• 이 저장소에서 다이어그램 문서 체계의 기본 원칙을 확정한다.
• 최소한 아래를 명확히 정한다.
  • ERD는 무엇을 표현하는가
  • Mermaid는 어디까지 쓰는가
  • 세부 인덱스/쿼리/운영 메모는 어디에 남기는가
  • 전체 다이어그램과 도메인 축약 다이어그램을 어떻게 구분하는가

메모

2026-03-30 기준으로는 문서화 우선, 버저닝 별도 방향이 더 실용적이라고 판단했지만, 다이어그램 도구 체계 자체는 별도 결정이 필요하다.