> ## Content Index
> Fetch the complete content index at: https://blog.frostk.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# 앱의 버튼 뒤에 뭐가 연결됐을까, Floorplan의 코드 지도
- URL: https://blog.frostk.com/floorplan-cross-repo-map/
- Published: 2026-11-06T01:00:00.000Z
- Updated: 2026-11-06T14:35:42.000Z
- Description: Floorplan은 프런트엔드의 요청과 서버 코드를 연결해 앱을 지도로 보여주는 Claude Code·Codex 플러그인이에요. 격리 환경에서 요청 모양을 바꿔 스캔하니 흔한 요청은 이어졌지만, 서버 파일 안에서 만든 라우터는 주소가 틀리게 기록됐어요.
- Author: Cat
- Tags: IT, 개발도구, 오픈소스

앱은 동작하는데, 결제 버튼을 누른 뒤 어느 서버 코드가 실행되는지는 설명하기 어려울 수 있어요. 프런트엔드와 백엔드가 다른 저장소에 있다면 파일의 `import`만 따라가서는 연결이 보이지 않고요.

Floorplan은 Claude Code나 Codex가 읽은 코드에 설명을 붙이고, 구성 요소와 파일, 웹 요청을 탐색 가능한 지도로 만드는 플러그인이에요. MIT 라이선스이고 Node.js 18 이상에서 돌아요. 이 연결을 맡는 스캐너를 격리 환경에서 돌려 보니, 흔한 요청 모양 일곱 가지는 모두 서버 코드에 이어졌어요. 하지만 서버 파일 안에서 만든 Express 라우터는 경로가 빠지고 다른 주소까지 틀리게 기록됐고, 다른 파일의 공용 요청 함수는 기본 주소가 길면 연결되지 않았어요.

## 버튼 뒤의 코드를 지도에서 따라가요

제작자의 샘플 앱 Brewline은 커피 판매·구독 서비스를 가정해요. 지도에서 Gift 화면을 고르면 선물 입력 폼, 그 화면이 보내는 요청, 서버 코드, 데이터와 외부 서비스까지 이어지는 구성을 볼 수 있다고 설명해요.

![Floorplan의 샘플 앱에서 Gift 화면에 연결된 요청과 서버, 데이터와 외부 서비스를 보여주는 지도](https://blog.frostk.com/content/images/2026/11/61096783.png)

제작자 Hayden Smith의 Brewline 샘플 앱 화면. 출처: Floorplan README, MIT.

파일 이름만 늘어놓는 대신 각 부분이 무슨 일을 하는지 설명을 붙이는 방식이에요. 더 자세히 보려면 구성 요소에서 파일과 요청 처리 지점으로 들어갈 수 있어요. 프로젝트는 코드가 바뀐 부분을 표시하고, 지도에 질문을 던지는 기능도 제공해요.

설치 전에 [공식 라이브 데모](https://haydenschmitty.github.io/floorplan-demo/?ref=blog.frostk.com)에서 지도의 모습을 볼 수 있어요. 브라우저에서 지도 표시를 직접 확인했어요. 다만 데모 옆의 Claude Code·Codex 대화는 **미리 짜인 사용 예시**이고, 방문자가 입력한 질문에 모델이 실시간 답하는 시연은 아니에요.

## 작은 두 저장소로 연결을 확인했어요

Floorplan의 연결 탐색은 전부 AI에 맡겨져 있지 않아요. Node.js 스크립트가 파일과 `import`, 서버가 처리하는 주소, 클라이언트의 웹 요청을 찾고 연결해요. AI는 앱을 어떤 부분으로 나눌지 판단하고, 이름과 설명을 붙이는 일을 맡아요.

확인에는 실제 제품 대신 정답을 아는 작은 코드를 썼어요. `web`과 `api`라는 Git 저장소를 따로 만들고, 한쪽은 요청을 보내고 다른 쪽은 같은 주소를 처리하도록 했어요.

| 확인 항목  | 입력과 실제 결과                                                 |
| ------ | --------------------------------------------------------- |
| 프런트 코드 | web/app.js에서 fetch('/api/ping') 호출                        |
| 서버 코드  | api/server.js에서 GET /api/ping 처리                          |
| 예상한 연결 | 서로 다른 저장소의 두 파일이 HTTP 요청으로 이어짐                            |
| 실제 결과  | 스캔이 요청과 처리 지점 한 쌍을 연결했고, 빌드된 지도 데이터에서도 같은 두 파일의 링크를 확인했어요 |

`scan.mjs`와 `build.mjs`를 실행해 지도 HTML이 만들어지는 것까지 확인했어요. 구성 요소의 이름과 파일 분류는 AI 대신 제가 직접 지정했어요.

## 어떤 요청 모양까지 따라갈까요

공식 문서는 연결 탐색이 컴파일러가 아닌 패턴 매칭이라고 설명해요. 코드에서 흔히 보이는 형태를 찾아 맞추는 방식이라 놓치는 연결이 있을 수 있고, 그때는 AI가 연결을 직접 적어 넣는다고 해요. 그렇다면 실제로 어떤 모양에서 끊길까요? 같은 커밋으로 프런트의 요청 모양을 여러 가지로 바꾸고, 서버에는 각 요청에 맞는 Express 처리 코드를 넣어 다시 스캔해 봤어요.

| 프런트의 요청 모양                                   | 스캔 결과                                       |
| -------------------------------------------- | ------------------------------------------- |
| fetch('/api/ping')                           | 정확한 서버 주소로 연결                               |
| fetch(\`/api/users/${id}\`) → /api/users/:id | 정확한 서버 주소로 연결                               |
| axios.post(\`${API\_BASE}/api/orders\`)      | 정확한 서버 주소로 연결                               |
| 같은 파일의 도우미 함수 call('/items')                 | /api/items로 연결(도우미의 /api까지 읽음)              |
| 변수에 담은 주소 fetch(url)                         | 정확한 서버 주소로 연결                               |
| 다른 파일의 도우미 함수 api('/reports')                | 주소를 /reports로만 기록, 끝부분이 같은 /api/reports에 연결 |
| 서버에 없는 메서드 DELETE /api/ping                  | 연결 없음(서버에 해당 처리가 없으니 맞는 결과)                 |
| 별도 파일 라우터의 /api/v2/health                    | 정확한 서버 주소로 연결                               |

경로 변수, 기본 주소 변수, 같은 파일의 도우미는 모두 정확한 주소로 이어졌어요. 다른 파일에서 가져온 공용 요청 함수는 달랐어요. 스캐너는 도우미 안의 `/api`를 모른 채 `/reports`만 기록했고, 서버 주소의 끝부분이 같아서 연결했어요. 그래서 기본 주소가 길어지면 결과가 바뀌어요. 도우미의 기본 주소를 `/api/v1/shop`으로 바꾸자 같은 요청은 연결되지 않았어요. 코드를 보면 끝 한 단계만 맞고 앞의 모르는 단계가 셋 이상이면 근거가 약하다고 보고, 호출한 파일에 다른 연결 기록이 없으면 버려요.

라우터에서도 차이가 났어요. 라우터는 여러 요청 처리 코드를 묶어 `/api/v2` 같은 공통 주소 아래 붙이는 Express 기능이에요. 이번 작은 예제에서 라우터를 `v2.js`라는 별도 파일로 두면 `/api/v2/health`가 정확히 잡혔어요. 같은 라우터를 서버 파일 안에서 `express.Router()`로 만들고 `app.use('/api/v2', v2)`로 붙이자 결과가 틀어졌어요.

- 라우터의 `/health`는 경로 목록에서 빠졌어요.
- 같은 파일의 다른 처리 코드 여섯 개에는 모두 `/api/v2`가 잘못 붙어 `GET /api/v2/api/ping`처럼 기록됐어요.
- 요청 연결 다섯 개는 생겼지만, 지도에 적힌 서버 주소는 모두 틀렸어요.

코드에서는 마운트한 이름이 다른 파일에서 가져온 것이 아니면 그 파일의 모든 처리 코드에 접두어를 붙이도록 돼 있었어요. 라우터를 한 파일에 같이 둔 서버라면 지도의 주소를 실제 코드와 한 번 대조해 보는 편이 좋아요.

## 지도는 로컬, 코드 설명은 내 AI 계정으로

시작 조건은 Node.js 18 이상과 Claude Code 또는 Codex예요. 프로젝트를 연 뒤 앱의 floorplan을 만들어 달라고 요청하는 방식이고, 프런트와 백엔드가 분리돼 있다면 둘을 담은 상위 폴더에서 시작하도록 안내해요. 설치 명령은 [공식 README](https://github.com/haydenschmitty/floorplan?ref=blog.frostk.com#install)에 있어요.

스캔과 지도 생성은 자기 컴퓨터에서 이뤄져요. 하지만 이름과 설명을 만들거나 질문에 답할 때는 **기존 Claude·Codex 계정으로 AI가 코드를 읽어요.** 지도 파일은 내 컴퓨터에 저장돼요. 그래도 AI가 읽은 코드는 모델 제공자에게 전달돼요. 사내 코드를 다룬다면 원래 쓰는 AI 도구의 사용·전송 기준이 그대로 필요한 부분이에요.

코드 속 키나 인증 없는 처리 지점을 살펴보는 Health check도 있지만, 프로젝트도 이를 보안 감사가 아닌 1차 점검으로 한정해요. 우선은 **화면에서 시작한 요청이 어디로 이어지는지 따라갈 단서**가 필요한 사람에게 맞는 도구예요.

## 확인한 범위

- 기준일: 2026-11-06.
- 직접 한 것: 비특권 Docker 격리 환경의 Node.js 22에서 커밋 `70be3f4`의 `scan.mjs`·`build.mjs`를 돌렸어요. 서로 다른 두 Git 저장소로 요청 한 쌍의 연결과 지도 HTML 생성을 봤고, 요청 모양 8가지, 다른 파일 도우미의 기본 주소 길이 2가지, Express 라우터 배치 3가지(라우터 없음, 별도 파일, 같은 파일)로 연결 결과를 비교했어요. 결과를 `routes.mjs`의 경로 연결·주소 비교 코드와 맞춰 봤어요. 공식 데모의 지도 표시는 실제 브라우저로 봤어요.
- 읽은 것: README와 동작 원리·개발·프라이버시 문서, MIT 라이선스, 스캐너의 요청 추출·경로 연결 코드.
- 확인하지 못한 것: Claude Code·Codex 플러그인 설치와 로그인, AI 설명·질문 기능, AI가 빠진 연결을 채우는지, 큰 실제 프로젝트의 연결 정확도, Express 밖 프레임워크, Health check의 탐지 성능, 공식 영상 재생은 확인하지 않았어요.

## 출처

[GitHub - haydenschmitty/floorplan: See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex. - haydenschmitty/floorplan![](https://blog.frostk.com/content/images/icon/favicon-b489d64c-fe51-4447-b232-f6505f6b0916.png)GitHub![](https://blog.frostk.com/content/images/thumbnail/3d77db05-fafa-4948-8192-baea2c971f0b-d1fa2b14-ebc4-4bfa-906e-464e5a16ef77.png)](https://github.com/haydenschmitty/floorplan?ref=blog.frostk.com)

[프로젝트 README](https://github.com/haydenschmitty/floorplan?ref=blog.frostk.com) · [동작 원리](https://github.com/haydenschmitty/floorplan/blob/main/docs/how-it-works.md?ref=blog.frostk.com) · [프라이버시와 보안](https://github.com/haydenschmitty/floorplan/blob/main/docs/privacy-and-security.md?ref=blog.frostk.com) · [MIT 라이선스, © 2026 Hayden Smith](https://github.com/haydenschmitty/floorplan/blob/main/LICENSE?ref=blog.frostk.com)