끄적임 저장소 아키텍처를 archify로 그려 README에 링크한 날

AICassa, AICura, AITessera에서 같은 작업을 세 번 반복했다. 저장소를 읽고 구조를 다이어그램으로 그린 뒤 README에 링크 한 줄을 붙이는 일이다. 결과물이 눈에 보이는 작업이라 기록해 둔다.

1. 왜 그렸나

README에는 스택 표와 디렉터리 설명이 있었다. 하지만 "요청이 들어와서 DB까지 어떻게 흘러가는가"는 글로 읽어서는 한 번에 안 들어온다. 새로 합류한 사람이나 몇 달 뒤의 나에게 필요한 건 표가 아니라 지도였다.

Mermaid로 직접 그리면 노드 배치와 색을 매번 손으로 맞춰야 한다. 그래서 archify 스킬을 썼다. 요구사항이나 저장소 코드를 근거로 아키텍처, 시퀀스, 상태 다이어그램을 탐색형 단일 HTML(인라인 SVG)로 만들어 준다. 다크/라이트 테마, 확대/축소, 경로 추적, PNG/SVG 내보내기가 들어 있다.

2. 2026-08-29 저녁: 세 저장소에 같은 일

커밋 기록 기준으로 세 저장소가 한 시간 안에 끝났다.

세 번 다 커밋 메시지 모양이 같다. 📝 docs: 아키텍처 … 다이어그램 추가 및 README 링크. 문서만 바뀌는 변경이라 규칙대로 커밋 단위는 "다이어그램 + README 링크 한 줄"로 묶었다.

중요한 건 다이어그램을 "상상"으로 그리지 않았다는 점이다. 저장소의 컨트롤러·서비스·워커·CI 설정을 읽고, 실제로 있는 것만 노드로 올렸다. 그래서 같은 도구인데 세 그림이 전혀 다르게 나왔다.

3. 그림이 저장소마다 다른 이유

AICura: 진입면이 네 개, 비동기 파이프라인이 있다

CodeIgniter 4 한 프로젝트에 Admin, Portal, API v1, 공개 웹이 공존한다. 그림에서는 이 네 입구가 위쪽에 나란히 놓이고, 가운데 CI4 앱 아래로 MySQL, Redis Queue, Spark 워커가 이어진다.

• 요청 흐름: 인증 필터(Admin/Portal은 세션, API는 JWT) → 컨트롤러 → Service → Query Builder
• 비동기 파이프라인: 로그·작업을 Redis에 LPUSH, Spark 커맨드가 cron으로 RPOP 소비, 가공 결과를 DB에 저장
• 배포 흐름: GitHub Actions self-hosted 러너가 SSH로 git pull + migrate

archify는 화면 상단에 "요청 흐름 / 비동기 파이프라인 / 배포 흐름" 세 개의 가이드 뷰를 만들어 줬다. 경로를 하나씩 따라가며 볼 수 있어서, 글로 쓰면 세 문단이 될 내용을 클릭 세 번으로 보여 준다.

AITessera: 프레임워크 없는 PSR 스택

AITessera는 프레임워크 없이 PSR-7/15로 짠 인증 API다. 그림도 그 구조 그대로다.

옆으로는 lcobucci/jwt(HS256, alg 고정), Redis(rate limit·큐), Console Workers(로그인·로그·메일 큐), Claude API가 붙는다. 여기에는 시퀀스 다이어그램을 하나 더 만들었다. 로그인 토큰 발급 흐름이다. 인증 서비스는 "어느 단계에서 무엇을 검증하는가"가 핵심이라 정적 구조도만으로는 부족했다.

AICassa: 인증이 둘로 갈린다

AICassa는 간편장부 웹ERP다. 그림의 핵심은 Admin과 Operator 인증 이원화다.

• Admin: 세션 쿠키 → Router·Filters → Admin 컨트롤러 → Service → Model → MySQL(KST 세션)
• Operator: .env 자격증명으로 별도 인증, 세법 파라미터 CRUD 담당
• AI 통합(선택 기능): AnthropicClient → Claude Messages API. 이력에 없을 때만 호출하는 폴백 경로

시퀀스 다이어그램은 계정과목 AI 자동분류로 잡았다. "이력 우선 조회 → Claude 폴백 → 사용량 기록" 순서다. AI 호출은 비용이 드는 경로라서, 언제 호출되고 언제 호출되지 않는지가 한눈에 보여야 했다.

4. README에는 링크 한 줄

세 저장소 모두 README에 아키텍처 절(또는 한 줄)을 추가했다.

링크 옆에 "그림이 무엇을 보여 주는가"를 한 줄로 붙인 게 의외로 효과가 있다. 클릭하기 전에 볼 가치가 있는지 판단할 수 있다.

AITessera는 한 줄 더 달았다. HTML이 GitHub에서 렌더링되지 않고 소스로 보이기 때문이다.

archify 로 생성한 탐색형 HTML — 다운로드 후 브라우저로 열람, 다크/라이트 테마·확대/축소·경로 추적 지원

5. 겪은 함정

HTML이 GitHub 웹에서 안 열린다. 파일이 약 700KB짜리 단일 HTML이라 저장소 화면에서는 소스만 보인다. 그래서 위처럼 "다운로드 후 열람"을 README에 적었다. 바로 보이게 하려면 PNG를 같이 내보내 README에 ![]()로 넣는 방법이 있다. 이 글의 이미지도 같은 방식으로 뽑았다.

다이어그램도 낡는다. 2026-09-04에 GitHub 조직 이름을 pushwing에서 aivance-kr로 바꿨다. 다이어그램 안에 조직 이름과 러너 설명이 박혀 있어서 AITessera는 아키텍처(8d5226c, 12:47)와 로그인 시퀀스(3df09dd, 12:59)를 다시 생성했다. 코드가 아니라 문서인데도 원본 소스(저장소)가 바뀌면 같이 갱신해야 한다. 생성 파일이라 diff가 수백 줄(143 insertions, 135 deletions)이 나오지만, 다시 만드는 비용이 낮아서 감당할 만하다.

단일 HTML이라 커밋이 크다. 파일 하나가 약 1.5만 줄이다. AICassa 커밋은 한 번에 2.9만 줄이 들어갔다. 리뷰 대상이 아니라 산출물로 취급하고, 리뷰는 README 변경분만 보면 된다.

6. 정리

• 구조가 다른 저장소에는 다른 그림이 필요하다. 진입면이 많으면 요청 흐름, 큐가 있으면 비동기 파이프라인, 인증이 핵심이면 시퀀스를 따로 둔다.
• 코드를 읽고 그리니 README의 설명과 실제 구조가 어긋난 곳을 그리면서 발견하게 된다.
• README에는 링크와 한 줄 설명이면 충분하다. 단, GitHub에서 HTML이 렌더링되지 않는다는 점을 같이 적는다.
• 조직 이름 변경처럼 바탕이 바뀌면 다이어그램도 재생성 대상이다.

다음에는 PNG 미리보기를 README에 같이 넣어, 클릭하지 않아도 구조가 보이게 할 생각이다.