아키텍처·폴더 구조 + 시작점에서 무엇을 어떻게 분해했는가

시작점을 처음 봤을 때 두 가지 시그널을 읽었습니다. 하나는 SearchPage.tsx 안에 CountBottomSheet와 DateBottomSheet가 통째로 인라인으로 들어가 있고 모든 onClick이 () => {} 스텁이라는 점, 다른 하나는 package.json에 jotai나 react-query가 없어서 상태 라이브러리를 직접 골라야 한다는 점이었습니다. 토스가 마크업·스타일은 거의 다 깔아놓고 기능만 비워둔 거니까, 결국 평가 포인트는 "이 인라인 덩어리를 어떤 기준으로 쪼갤 줄 아느냐"라고 봤습니다.

분해 기준은 검색 조건의 어떤 한 필드를 책임지는가로 잡았습니다. 출발/도착역, 편도·왕복, 가는날·오는날, 인원 — 이렇게 네 필드가 있으니 각각을 StationSection, TripTypeTab, DateSection, CountField로 분리하고, 페이지는 그것들을 위에서 아래로 조립만 합니다. 그 결과 SearchPage.tsx는 43줄까지 줄었고, 페이지를 한 번 훑으면 화면 구조가 바로 읽힙니다.

분해할 때 의식적으로 피한 게 하나 있는데, "미래에 재사용될 수도 있으니까"라는 이유로 추상화하지 않는다는 거였습니다. 6시간짜리 과제고 토스가 "화려한 방법보다 평소에 익숙한 방법"을 권장한 만큼, 지금 화면 한 군데에서만 쓰이는 건 그냥 그 자리에 두자고 결정했습니다. EmptyResult처럼 station/ticket 두 곳에서 같은 빈 상태를 보여줘야 할 때만 components/common/으로 빼냈습니다.

폴더 구조는 두 가지 축을 섞었습니다. 최상위는 역할(layer) 기준 — pages, components, atoms, query, types, utils, lib — 이고, components 안쪽만 기능(feature) 기준으로 한 번 더 나눴습니다. 작은 과제라 React 생태계에서 가장 익숙한 형태로 가는 게 토스 가이드라인에도 맞다고 봤습니다.

여기서 한 가지 명시적인 의도가 있는데, atoms와 query를 따로 둔 부분입니다. atoms는 사용자 입력(출발역, 가는날, 인원 등) 같은 client state를 담고, query는 useStationsQuery, useTicketsQuery, useReservationQuery, useReservationMutation처럼 서버에서 가져오는 server state를 담습니다. 둘이 한 폴더에 섞이면 어디까지가 사용자가 만든 상태고 어디부터가 서버 동기화 상태인지 흐려지는데, 폴더로 분리해두니 새 atom이나 새 쿼리를 추가할 때 어디에 넣어야 할지 고민할 일이 없습니다.

lib/에는 queryClient 인스턴스 같은 third-party 설정만 두고, atoms·query 같은 우리 코드와 섞이지 않게 했습니다. 만약 axios 인스턴스나 ky 클라이언트 같은 게 추가되면 자연스럽게 lib/에 들어가게 되는 자리입니다.

페이지를 얇게 유지한 가장 큰 이유는 상태 매개체로 만들지 않는 것입니다. atom이라는 글로벌 client state를 도입한 이상, 페이지가 atom을 구독해서 자식에게 props로 내려줄 필요가 없습니다. 자식이 자기가 필요한 atom을 직접 useAtomValue 하면 됩니다.

이 결정의 효과 두 가지가 있습니다. 첫 번째는 props 드릴링이 사라지는 것입니다. SearchPage가 출발역·도착역·날짜·인원을 다 들고 있다가 각각 StationSection, DateSection, CountField에 내려주는 구조였으면 페이지 props 시그니처가 길어지고, 자식 컴포넌트도 props로 받느라 결합도가 올라갑니다. 두 번째는 리렌더 범위 최소화입니다. 페이지가 passengerCountAtom, tripTypeAtom, departureStationAtom을 다 구독하면 인원 한 번 바꿔도 페이지 통째로 리렌더되는데, 지금 구조는 인원이 바뀌면 CountField만, 편도/왕복이 바뀌면 TripTypeTab + DateSection만 리렌더됩니다.

페이지가 유일하게 들고 있는 상태는 useNavigate와 isSearchValidAtom 정도인데, 둘 다 "기차 보기" 버튼의 활성화/이동을 결정하기 위한 페이지 레벨 책임이라 자연스럽습니다. 만약 페이지에 이런 것까지 자식에 묻어두면 페이지의 역할이 모호해지니까, 라우팅 결정과 검증 결과 소비는 페이지에 두는 식으로 경계를 잡았습니다.

components 하위를 화면 단위로 나눈 건 **수정의 폭발 반경(blast radius)**을 좁히기 위해서입니다. 검색 화면을 손대야 한다 → components/search/만 보면 됨, 티켓 페이지를 수정해야 한다 → components/ticket/만 보면 됨. 한 폴더 안에 그 화면에 등장하는 컴포넌트가 다 모여 있으니 PR 리뷰할 때도 어디를 봐야 할지 즉각적입니다.

common/은 의도적으로 매우 보수적으로 운영했습니다. 지금은 EmptyResult 하나만 들어 있는데, station 검색 결과 0개일 때와 ticket 조회 결과 0개일 때 같은 빈 상태 UI를 써야 했기 때문입니다. 두 화면에서 동시에 쓰이지 않으면 common에 두지 않는다는 룰을 지켰습니다 — 그래야 "common 폴더가 어느 시점에 다 흡수해버린 잡동사니 폴더"가 되는 흔한 함정을 피할 수 있습니다.

components/station/hooks/useStationBack.ts처럼 feature 안에 hooks 폴더를 둔 것도 같은 맥락입니다. 이 훅은 station 페이지에서 직접 URL 진입을 처리하기 위한 전용 훅이라 다른 곳에서는 쓰이지 않습니다. 그래서 글로벌 utils/이나 글로벌 hooks/에 올리지 않고 station feature 안에 격리해뒀습니다. 만약 ticket·confirm에서도 같은 훅이 필요해지면 그때 한 단계 끌어올리면 됩니다.

한 컴포넌트가 자기 폴더를 갖는 구조는, 컴포넌트와 함께 살게 될 짝 파일들의 자리를 미리 마련해두는 것입니다. 처음에는 .tsx 파일 하나만 들어 있어도, 나중에 테스트 파일, CSS 모듈, props 타입 분리 파일, 이 컴포넌트만 쓰는 서브컴포넌트 같은 게 같이 들어올 때 폴더 단위로 묶이니 이동도 삭제도 쉽습니다.

이게 단순 약속이 아니라 실제로 본 과제에서 자연스럽게 진화한 사례가 있는데, components/confirm/ConfirmTripInfo/ 폴더 안에 ConfirmTripInfo.tsx 본체와, 그 안에서만 쓰는 서브컴포넌트 TripInfoRow/가 다시 자기 폴더로 들어 있고, 거기에 또 TripInfoRow.tsx와 types.ts가 같이 살고 있습니다. props 타입을 별도 파일로 빼고 싶을 때, 컴포넌트 옆에 두는 게 가장 직관적이라 이 구조가 그 결정을 자연스럽게 받쳐줍니다.

단점은 디렉토리 트리의 깊이가 깊어진다는 점인데, IDE 시각적 부담은 있지만 실제 import는 alias로 평탄화되니 코드 작성·읽기 단계에선 문제없다고 봤습니다. 그리고 협업 관점에서 이 방식이 한 컴포넌트의 ownership을 폴더로 명확히 표현해주는 게 더 큰 가치라고 판단했습니다.