소개
Glossary는 특정 조직·팀·제품군이 사용하는 용어집을 관리하는 셀프호스팅 플랫폼이다. 현재 UI와 데이터 모델은 한국어를 모국어로 쓰면서 기술 용어는 영어와 함께 사용하는 한국 기업 환경에 최적화되어 있다. 완전한 다국어 지원은 현재 범위가 아니며, 추후 실제 요청이 생기면 선택한 모국어 + 영어 구조로 확장할 수 있다.
왜 만들었나
용어집을 엑셀과 컨플루언스로 관리해 왔다. 용어가 여러 시트와 페이지에 흩어져 있어 중복 등록을 발견하기 어렵고, 표기가 문서마다 제각각이며, 도구가 읽을 수 있는 형태가 아니었다.
이 플랫폼은 다음 문제를 해결한다.
- 단일 사전 — 모든 용어를 한곳에 모으고 등록 시점에 중복을 잡는다.
- 기계 판독 가능 — 도구가
/terms/lookup과/lexicon으로 표기 목록을 조회하고/validate로 문서 본문을 검사한다. 발견한 후보는/check에서 사람의 검토를 거쳐 용어집으로 환류된다. - 업무 지식 창고 — 용어에 연결된 원칙·프로세스·플레이북을 별도 위키 문서로 쌓는다.
- AI가 읽는 조직 맥락 — 용어집·공개 위키·회의록을 출처별로 구분해 설명한다.
핵심 결정사항
| 항목 | 결정 |
|---|---|
| 배포 | 사내망 온프레미스, Docker Compose |
| 검증 범위 | 비표준 표기 교정, 미등록 전문용어 발견, 금지어·폐기어 검출 |
| 네임스페이스 | 단일 사전 + 동음이의어 허용 (domain 태그로 구분) |
| 거버넌스 | 용어집은 협업 편집, 위키는 초안→공개→보관 상태와 전체 리비전 |
| AI 활용 | 용어 성격별 작성 기준 + Gemini/OpenAI-compatible 기반 챗봇·pgvector RAG 검색 |
| 인증 | 자체 계정 + OIDC/OAuth 2.0 SSO, 도구는 API Key |
| 아키텍처 | Next.js 모놀리스 + Postgres, 검증 엔진은 독립 TS 패키지 |
| 첨부 저장 | Postgres bytea, content-addressed, WebP 변환, 파일당 2MB 상한 |
채택하지 않은 대안
- 제품별 네임스페이스 분리 — 엑셀 시트 분산 문제가 재현될 위험이 커서 기각.
- Python/FastAPI 검증 서비스 분리 — 사전이 이미 있는 상태의 매칭은 형태소 분석이 거의 불필요하다. 컨테이너와 언어가 둘로 늘어나는 비용 대비 이득이 작아 기각.
- 매칭을 Postgres에 위임 — 검증 로직이 SQL로 흩어지고 문서 내 위치 기반 규칙을 표현할 수 없어 기각. 단
pg_trgm은 UI 검색과 유사 후보 제시에 채택했다. - 로컬 볼륨 첨부 저장 — DB 백업과 파일 백업의 시점 불일치로 고아 파일이 생기고, Compose 볼륨명이 디렉터리명에서 파생되어 서버 이동 시 데이터 유실 위험이 있어 기각.
지금 어디까지 됐나
사전 코어와 협업 화면, 표기 정규화, 세션·SSO·API Key 인증, 용어 CRUD, 엑셀 임포트, 관계도·통계, 용어 연결형 위키 문서·리비전·공개 상태, 콘텐츠 완성도 자동 판정과 용어집·위키·회의록 근거 챗봇, 프로덕션 Docker 구성 및 백업·복구 스크립트가 구현되어 있다.
마크다운 편집·미리보기, 이미지 첨부와 리비전 조회·되돌리기도 구현되어 있다. 검증 엔진(POST /validate), 미등록 후보 수집과 /check 검토 흐름은 M2에서 구현되어 있다. CI 연동과 리비전 diff UI는 후속 범위다. 자세한 범위는 로드맵을 참고한다.
다음 단계
- 제품 화면 둘러보기 — 홈, 시트, 협업, 문서 검증, AI 화면을 이미지로 확인
- 시작하기 — 로컬 개발 환경 구성
- 아키텍처 — 패키지 구조와 의존 방향
- 데이터 모델 — Term과 Surface의 분리
- 위키 지식 창고 — 용어에 연결하는 업무 맥락 문서와 공개·RAG 규칙
- 온톨로지와 관계 경로 — 승인 관계·위키 연결·제한적 그래프 확장
- 협업과 관계도 — 담당자, 업무 분류·태그, 그래프와 Confluence 임베드
- 함께 정리 — 정리 대기, AI 제안·큐, 중복 작업
- 필드 보완 — 한줄 정의·도메인·업무 분류 집중 작업
- AI 활용과 챗봇 — 작성 기준, AI·RAG 공급자 연결, 모델 선택과 보안
- 에이전트 고도화 전략 — 회의록·용어 RAG, 전문가 대화, 품질 평가 로드맵
- API 개요 — 인증과 에러 규약