2) 용어 정의
문서에 자주 나오는 용어를 쉬운 말로 풀었다.
국악 용어
| 용어 | 쉬운 설명 |
| 장단 | 국악의 리듬 틀. 서양음악의 박자표와 비슷하지만 “빠르기 + 강약 + 분위기”를 함께 규정한다 |
| 자진모리 | 빠르고 몰아치는 장단. 12박. 신나고 경쾌한 대목에 쓴다 |
| 중모리 | 중간 빠르기의 대표 장단. 12박. 서정적이고 차분하다 |
| 굿거리 | 흥겹고 넉넉한 장단. 12박. 민속악에서 널리 쓴다 |
| 휘모리 | 가장 빠른 장단. 4박. 절정·긴박한 대목 |
| 세마치 | 3박 계열의 장단. 6박. 슬픔·애잔함 |
| 엇모리 | 박이 고르지 않은 특이한 장단. 10박. 신비롭고 독특한 느낌 |
| 루프 단위(박) | 그 장단이 한 바퀴 도는 데 걸리는 박 수. 이 단위로 음원을 자르면 반복해도 마디가 어긋나지 않는다 |
| 악구(phrase) | 음악의 한 덩어리. 국립국악원 API가 제공하는 데이터 단위 |
| 계면조 / 평조 | 국악의 조(調). 계면조는 슬프고 애잔한 색, 평조는 밝고 평온한 색 |
라이선스
| 용어 | 쉬운 설명 |
| KOGL (공공누리) | 공공기관이 만든 저작물의 이용 조건을 표시하는 한국의 공공 라이선스 |
| KOGL 제1유형 | 출처만 표시하면 상업적 이용까지 가능. 이 프로젝트에서 가장 가치 있는 유형 |
| KOGL 제2유형 | 출처 표시 + 상업적 이용 금지. 개인 습작·비영리 프로젝트에만 사용 가능 |
| 로열티 프리 | 사용할 때마다 별도 비용을 내지 않아도 되는 것. 저작권이 없다는 뜻은 아니다 |
AI · 검색
| 용어 | 쉬운 설명 |
| 임베딩(Embedding) | 문장을 숫자 목록(벡터)으로 바꾼 것. 뜻이 비슷한 문장은 숫자도 비슷해진다 |
| 벡터 차원 | 그 숫자 목록의 길이. 이 프로젝트는 1,536개 |
| 코사인 유사도 | 두 벡터가 가리키는 방향이 얼마나 비슷한지. 문장 길이에 휘둘리지 않는다 |
| pgvector | PostgreSQL에서 벡터를 저장하고 유사도 검색을 하게 해 주는 확장 기능 |
<=> | pgvector의 코사인 거리 연산자. 값이 작을수록 가깝다 |
| HNSW | 벡터 검색을 빠르게 하는 인덱스 방식. 데이터가 많아지면 필요 (이 프로젝트는 v1.2 계획) |
| top-k | 가장 가까운 것 k개만 뽑는 것. 이 프로젝트는 k=3 |
| LLM | 대규모 언어 모델. 이 프로젝트에서는 Gemini |
| 할루시네이션 | AI가 사실이 아닌 것을 그럴듯하게 지어내는 현상 |
| 프롬프트 | AI에게 주는 지시문 |
아키텍처
| 용어 | 쉬운 설명 |
| 헥사고날 아키텍처 | 핵심 로직을 가운데 두고, 외부(DB·API·웹)는 갈아 끼울 수 있는 부품으로 두는 구조 |
| Ports & Adapters | 헥사고날의 다른 이름. Port는 “무엇이 필요한지”를 적은 약속(인터페이스), Adapter는 그 실제 구현 |
| DDD | 도메인 주도 설계. 코드를 기술이 아니라 업무 개념 중심으로 짜는 방식 |
| Entity | 고유 식별자를 가진 도메인 객체. 여기서는 GugakTrack |
| Value Object (VO) | 식별자 없이 값 자체가 정체성인 객체. Jangdan, EmotionTag 등. 변하지 않는다(frozen) |
| DTO | 계층 사이에 데이터를 나르는 상자. 로직이 없다 |
| Interactor | 유스케이스 하나를 실행하는 클래스. “순서를 조율”할 뿐 직접 일하지 않는다 |
| Repository | 데이터 저장소에 접근하는 통로. Application은 인터페이스만 알고 구현은 모른다 |
| Composition Root | 모든 부품을 실제로 조립하는 단 하나의 장소. 여기서는 dependencies/ |
| 프랙탈 네이밍 | {도메인}_{성격}_{계층} 규칙으로 파일 이름을 짓는 것. 어느 도메인이든 파일 배치가 똑같아진다 |
데이터베이스
| 용어 | 쉬운 설명 |
| 정규화 | 데이터를 중복 없이 나눠 담는 설계 원칙 |
| 1NF | 한 칸에는 값 하나만. 배열을 한 칸에 넣으면 위반 |
| 3NF | 다른 컬럼에 종속된 값을 따로 저장하지 않는다. “장단 → 루프 단위”가 대표 예 |
| 비정규화 | 일부러 정규화하지 않는 것. 쿼리되지 않는 데이터는 나누지 않는 편이 낫다 |
| JSONB | PostgreSQL이 JSON을 이진 형태로 저장하는 타입. 이 프로젝트는 cue_points에 사용 |
| FK (외래키) | 다른 테이블의 행을 가리키는 컬럼 |
| N+1 문제 | 목록 1번 조회 후 각 항목마다 추가 조회가 나가는 비효율. 3건 조회에 쿼리 4번 |
| joinedload | 한 번의 JOIN으로 연관 데이터를 함께 가져와 N+1을 없애는 방법 |
| Alembic | DB 스키마 변경 이력을 코드로 관리하는 도구 |
| 마이그레이션 | 스키마를 한 버전에서 다음 버전으로 옮기는 작업. upgrade / downgrade |
웹 · 인프라
| 용어 | 쉬운 설명 |
| FastAPI | 파이썬 웹 API 프레임워크. 비동기와 타입 힌트가 기본 |
| async / await | 기다리는 동안 다른 일을 하게 해 주는 비동기 문법. DB·API 호출이 많을 때 유리 |
| Pydantic | 데이터 형식을 검증하고 변환해 주는 라이브러리 |
| Redis | 메모리에 값을 잠깐 저장해 두는 캐시 서버 |
| TTL | 캐시가 살아 있는 시간. 이 프로젝트는 1시간 |
| Next.js App Router | React 기반 프레임워크의 최신 라우팅 방식. 서버/클라이언트 컴포넌트를 나눠 쓴다 |
| SSR / CSR | 서버에서 미리 그리기 / 브라우저에서 그리기 |
| WaveSurfer.js | 오디오 파형을 그리고 재생을 제어하는 자바스크립트 라이브러리 |
| CUE 포인트 | 트랙 안에서 분위기가 바뀌는 지점 표시. 여기서는 A·B·C 세 개 |
| Docker Compose | 여러 컨테이너(DB·API·프론트)를 한 번에 띄우는 도구 |
| healthcheck | 컨테이너가 실제로 준비됐는지 확인하는 검사. 기동 순서를 보장한다 |
이 프로젝트 고유 용어
| 용어 | 쉬운 설명 |
| DISCOVER | 자연어로 국악을 찾는 화면·유스케이스 |
| CREATE | 국악 샘플을 필터링해 고르는 화면·유스케이스 |
| 프리셋 URL (브릿지) | DISCOVER 결과의 악기·감성·BPM을 CREATE 필터 쿼리로 바꾼 주소 |
embed_text | Gemini가 만든 “임베딩 전용 정제 텍스트”. 사용자 원문이 아니라 이걸 벡터로 만든다 |
primary_emotion | sort_order = 0인 대표 감성 태그. 프리셋의 emotion 값이 된다 |
match_logs | 어떤 문장이 어떤 국악으로 이어졌는지 기록하는 표 |
| 파생값 | 원본 API에 없어서 규칙으로 만들어 낸 값 (장단·감성·BPM·라이선스) |
| 폴백(fallback) | 값을 찾지 못했을 때 쓰는 기본값. 장단은 중모리, BPM은 90 |