artifact-transformer 작업 일지 #19

경계를 긋고, 관계를 잇다 — C4를 boundary로 쪼개 OVERVIEW로 묶고, 인증·Keycloak을 제 소관으로 돌려보내고, ERD의 끊긴 FK를 메우다

이 글은 2026-06-24 하루 동안 artifact-transformer와 그 산하 도메인 저장소들에서 경계를 긋고, 끊긴 관계를 이은 작업 기록이다. 한쪽 손으로는 아키텍처 다이어그램을 boundary로 쪼개고 도메인을 제 소관으로 갈라 보냈고, 다른 손으로는 ERD에서 끊겨 있던 FK를 메웠다. 나누는 일과 잇는 일을 같은 날에 했다.

배경

artifact-transformer는 Jira 이슈와 PlantUML 다이어그램을 입력으로 받아 요구사항·유스케이스·기능·시퀀스 명세서와 데이터 정의서/명세서 등을 docx/xlsx로 자동 생성·역파싱하는 도구다 (#4 참조).

#18에서 도구를 여섯 도메인 저장소에 풀고, 표지 버전과 ERD↔데이터 정합이라는 “맞다고 믿어 온 창”을 실제와 맞췄다. 그날 마지막에 적어 둔 빚은 도메인 정정분 재생성과 위험도 평가 AI 역량 상세화였다.

오늘은 그 도메인들 안으로 한 걸음 더 들어갔다. ERD의 관계와 아키텍처 다이어그램의 경계 — 어제까지 “있다고 믿었지만 실제로는 끊겨 있거나 잘못 그어져 있던” 선들을 손봤다. 그리고 늘 그렇듯, 도메인을 들여다보니 도구가 아직 못 그리는 구조가 보였다. 그래서 오늘도 도구 안쪽과 도메인 바깥쪽을 번갈아 손댔다.

문제

손대기 전, 네 결의 어긋남이 보였다.

ERD 식별 관계가 평범한 관계처럼 그려졌다 — 공유 PK가 곧 FK인 식별 관계(identifying relationship)인데도 ERD에는 일반 관계선으로 찍혔다.
C4 아키텍처 다이어그램이 한 파일에 뭉쳐 있었다 — 컨테이너·컴포넌트 다이어그램이 boundary 없이 한 덩어리라, 레벨별로 따로 보거나 합쳐 보기 어려웠다.
도메인 경계가 어긋나 있었다 — JWT 인증·토큰은 IAMS가, Keycloak 스키마는 Keycloak이 맡는 영역인데 SDSP·IAM의 ERD에 그 엔티티가 그대로 남아 있었다.
ERD의 관계가 군데군데 끊겨 있었다 — GOV/LCM 허브, 복원 흐름, 원시↔정제 데이터 계보 등에서 FK가 정의되지 않은 채 떠 있었다.

결정 1 — ERD 식별 관계는 1:1로, 별칭은 원형을 지킨 채 정합만 본다

아침은 ERD의 가장 안쪽 표기부터 손봤다.

공유 PK가 FK를 겸하는 식별 관계는 ERD에서 1:1(||--||)로 렌더하도록 init_erd를 고쳤다. 같은 키를 양쪽이 공유한다는 사실은 관계의 차수(cardinality)로 드러나야 한다 — 일반 관계선으로 그리면 “공유”라는 의미가 다이어그램에서 사라진다.
ERD 엔티티 별칭을 physical-data.json의 id와 일치시키는 작업도 했는데, 여기서 한 번 길을 잘못 들었다(아래 함정). 결론은 밑줄 별칭(SDSP_PDE_COM_001) 원형을 그대로 둔 채, 정합성만 점검하는 쪽이었다.

별칭과 id는 형태만 다를 뿐 서로 역추출되는 같은 값이다. 정합성을 보겠다고 한쪽 형태를 다른 쪽으로 바꿔 버리면, 점검 대상이던 차이 자체를 지워 놓고 “맞다”고 선언하는 꼴이 된다.

padx·sugcs는 이 정합 기준으로 ERD를 재생성하고 physical-data 버전을 동기화했다.

결정 2 — C4 아키텍처 다이어그램을 boundary로 쪼개 OVERVIEW로 묶는다

오늘의 가장 큰 도구 작업이었다.

C4 다이어그램을 boundary 단위로 파일을 분리하도록 생성기를 고쳤다. 컨테이너 다이어그램(CNTDG)은 System_Boundary로, 컴포넌트 다이어그램(CMPDG)은 Container_Boundary로 쪼개고, 쪼갠 partial들을 OVERVIEW로 다시 병합하는 구조다.
이를 위해 ERD 파서를 추가하고, 같은 커밋에서 다이어그램↔JSON 정합성 검사와 C4 생성기를 함께 들였다. 다이어그램이 데이터·구조의 또 다른 표현인 한, 둘이 갈라지면 check가 잡는다 — 결정적 검증을 도구에 맡긴다는 #13의 연장이다.
partial은 단독으로도 렌더되어야 한다(!startsub/!includesub). CNTDG·CMPDG는 각자 그려도, OVERVIEW로 합쳐도 같은 그림이 나와야 한다.

도메인에서는 이 구조를 곧장 적용했다. sdsp·fdsp 모두 BCDG·CTXDG·CNTDG를 partial + OVERVIEW 구조로 전환하고, FDSP-BCDG-COM-001 → FDSP-BCDG-OVERVIEW, SDSP-CTXDG-COM-001 → SDSP-CTXDG-OVERVIEW 식으로 명명을 정규화했다.

다이어그램을 boundary로 쪼개는 건 그림을 잘게 나누려는 게 아니다. 무엇이 어느 경계 안에 속하는가를 파일 구조로 못박아, 나중에 한 컨테이너만 따로 보거나 전체를 합쳐 볼 때 같은 경계가 보이도록 하려는 것이다.

결정 3 — 정합의 눈을 레벨 간(L1~L3)으로, 시퀀스는 컨테이너=box로 넓힌다

boundary로 쪼개고 나니, 쪼갠 조각들 사이의 정합이 새 사각으로 떠올랐다.

CTXDG·CNTDG·CMPDG의 외부 시스템·시스템·Person이 레벨마다 일치해야 한다. 상위 레벨에 없는 액터가 하위에서 튀어나오거나, 같은 외부 시스템이 레벨마다 다른 이름으로 등장하면 안 된다. 이를 check에 C4 레벨 간(L1~L3) 정합성 검사로 추가했다 — participant.json의 systems/actors가 세 레벨에 모두 일관되게 놓였는지 기계적으로 대조한다.
도메인에서는 sdsp의 외부 데이터소스를 externalDataDeliveryServers로 전 계층 병합해, 레벨마다 흩어져 있던 외부 시스템을 한 정의로 모았다.
시퀀스 다이어그램도 FDSP 규약에 맞췄다 — 컨테이너를 box로, participant를 컴포넌트로 매칭하도록 생성기와 파서를 함께 고쳤다. 시퀀스의 라이프라인 작성 수준(컨테이너 C4 L2)이 CNTDG와 같은 경계를 가리키게 된다.

결정 4 — 도메인 경계를 제자리로 돌려보낸다

ERD에 남아 있던 “남의 일”을 갈라 보냈다.

JWT 인증·토큰은 IAMS 소관이다. SDSP에서 인증 토큰을 제외하고, 인증·사용량 기록·접근 제어 클러스터를 표시 다이어그램에서 걷어낸 뒤, IAMS를 외부 시스템으로 추가해 이관을 마무리했다.
Keycloak 스키마는 Keycloak 소관이다. iam에서 Keycloak 경계를 ERD에 반영해 식별 엔티티를 제거하고, DFDG 데이터 흐름을 그 경계에 맞춰 다시 그렸다.
Airflow 메타데이터 ERD는 SDSP 데이터 모델에서 분리했다 — 별도 ERD로 다룰 영역이지 SDSP가 떠안을 구조가 아니다.
iam에서는 조직(ORG)→그룹(GRP) 리네이밍도 정리했다.

ERD가 비대해지는 가장 흔한 이유는 엔티티가 많아서가 아니라, 다른 시스템이 책임질 구조를 자기 안에 그려 두기 때문이다. 경계를 긋는다는 건 선을 더 그리는 일이 아니라, 남의 구조를 지워 내 모델을 자기 책임만큼으로 줄이는 일이다.

결정 5 — 끊긴 관계를 잇는다: ERD FK 정밀화

경계를 그어 줄인 만큼, 안에 남은 관계는 꼼꼼히 이었다. 오후~저녁은 대부분 sdsp ERD의 FK 정의였다.

GOV/LCM 허브 FK — data_source_catalog·client·backup 등을 대상으로 허브 FK 관계를 정의했고(이벤트 알림 서브도메인·export 포함), 미설정 FK를 추가로 메웠다.
복원 흐름 FK — restore_point를 restore_target_point 마스터에 연결해 백업·복원 계보를 닫았다.
원시↔정제 데이터 계보 — DAT의 원시→정제 데이터 8건을 계보로 표기하고, 단순 선 연결이 아니라 raw↔parsed 참조 무결성 FK로 승격했다.
location 마스터 신설 — target_location_id를 정규화해 location 마스터를 새로 두고, 흩어진 위치 참조를 그 마스터로 모았다.

logical-data도 같은 관계로 맞추고, 변경분은 revise.py로 관심사별로 분리 커밋했다.

의도치 않은 함정

별칭을 physical-data id로 “바꿔서” 정합을 보려 했다 — 아침에 ERD 별칭(SDSP_PDE_COM_001)을 physical-data.json의 하이픈 id(SDSP-PDE-COM-001) 형태로 일괄 치환해 정합을 확인하려 했다. 하지만 둘은 밑줄↔하이픈 형태만 다를 뿐 서로 역추출되는 같은 값이라, 형태를 바꾸면 점검하려던 차이 자체가 사라진다는 걸 깨닫고 원형으로 되돌렸다(parse_erd와 테스트까지). 정합성 점검의 정답은 “한쪽을 다른 쪽에 맞춰 버리기”가 아니라 “형태가 달라도 같은 값인지 확인하기”였다.
participant.json에 boundaries가 왜 필요한가 — C4를 boundary로 쪼개다 보니, 생성·파싱 시 파일 분할의 기준이 boundary가 됐다. 그렇다면 그 boundary 정보가 participant.json에 명시돼 있어야 parse cdg --reset을 돌려도 같은 경계로 다시 쪼개지고, reset 라운드트립이 통과한다. boundaries를 participant.json에 채우고 나서야 reset 후에도 JSON↔다이어그램 정합이 유지됐다. 분할 규칙을 코드에만 두면, 분할 결과를 되돌릴 때 그 규칙을 다시 알 길이 없다.

무언가를 쪼개는 기준은, 쪼갠 산출물 안에 적어 둬야 한다. 기준이 코드에만 있으면 한 방향(생성)으로만 흐르고, 되돌리는(파싱) 순간 기준을 잃는다.

마무리

오늘 관통한 결은 “경계를 긋고, 끊긴 관계를 잇는 것” 이었다.

식별 관계를 1:1로 그리고 — 공유 PK=FK를 ||--||로 렌더, 별칭은 원형을 지킨 채 정합만.
C4를 boundary로 쪼개 OVERVIEW로 묶고 — ERD 파서·C4 생성기·다이어그램↔JSON 정합을 도구에 더하고, 도메인의 BCDG/CTXDG/CNTDG를 partial+OVERVIEW로 전환.
정합의 눈을 레벨 간으로 넓히고 — C4 L1~L3 Person·외부시스템·시스템 정합 검사, 시퀀스 box=컨테이너 매칭.
도메인 경계를 제자리로 — JWT/인증을 IAMS로, Keycloak을 Keycloak으로, Airflow ERD를 분리.
끊긴 FK를 메우고 — GOV/LCM 허브, 복원 흐름, 원시↔정제 계보, location 마스터.

#18이 도구를 여섯 저장소에 “풀어 본” 날이라면, 오늘은 그 저장소들의 구조 자체를 — 다이어그램의 경계와 ERD의 관계를 — 손으로 다듬은 날이다. 도구는 그 과정에서 C4 분할·레벨 정합·시퀀스 매칭이라는 새 능력을 얻었다.

다음에 할 것:

레벨 간 정합 검사 실전 확대 — 오늘 더한 C4 L1~L3 정합 검사를 나머지 도메인 저장소에도 돌려, 레벨마다 어긋난 외부 시스템·액터를 일괄로 잡는다.
boundary 분할 구조 잔여 저장소 전개 — partial+OVERVIEW 전환과 participant.json boundaries를 아직 안 돌린 저장소까지 마저 적용한다.
위험도 평가 AI 역량 상세화 — #18에서도 남긴 빚. C4·ERD가 정리된 지금, AI 서비스·군집을 요구사항·유스케이스·시퀀스까지 마저 내린다.