뮤룸 (Muroom) | const-tommy.dev

1. 🏗️ 프로젝트 아키텍처

"1인 개발의 효율을 극대화하는 지속 가능한 시스템 설계"

코드 중복을 최소화하고, 런타임 성능과 데이터 정합성을 보장하는 견고한 아키텍처를 구축하는 데 집중했습니다.

분류	기술 스택	핵심 역할
Monorepo	`Turborepo`, `pnpm`	멀티 앱 운영 및 공통 패키지(`ui`, `util`) 격리 관리
Framework	`Next.js 15 (App Router)`	서버 컴포넌트(RSC) 중심의 번들 최적화 및 Vercel 배포
State	`nuqs`, `Zustand`	URL 기반 단방향 데이터 흐름(SSOT) 및 전역 상태 관리
Network	`customFetch`, `TQ`	표준 API 기반 통신 계층 내재화 및 선언적 데이터 호출
Responsive	`Custom Hook`	브레이크포인트 기반의 모바일/웹 뷰 시스템 통제

Internal Packages 전략: Musician과 Manager 앱을 분리하되, packages/ui와 packages/util을 통해 핵심 로직과 UI를 공유합니다. 수정 사항이 모든 앱에 즉각 반영되어 관리 비용을 최소화했습니다.

Middleware Guard: 서버 로직이 실행되기 전인 **Edge 단계(요청의 최전방)**에서 JSESSIONID를 검증합니다. 인가되지 않은 접근을 페이지 렌더링 전에 차단하여 보안 성능과 서버 자원 효율을 동시에 확보했습니다.

customFetch 설계: 외부 라이브러리(Axios 등) 의존성을 낮추기 위해 Native Fetch를 래핑한 전용 레이어를 구축했습니다. AbortSignal 기반 타임아웃, 환경별 엔드포인트 자동 분기, Generic 기반의 응답 타입 추론을 표준화하여 시스템의 예측 가능성을 높였습니다.
Data Integration: TanStack Query를 결합해 URL 변화가 즉각적인 데이터 호출로 이어지는 파이프라인을 구축했습니다.

useResponsiveLayout: 1080px 브레이크포인트를 기준으로 모바일과 웹 레이아웃을 엄격히 분리합니다.
Hydration Issue 해결: isMounted 상태를 추적하여 클라이언트와 서버 간의 미스매치를 방지하고, 런타임 시 디바이스 환경에 맞는 정확한 UI를 렌더링하도록 강제합니다.

Next.js Entry & Security-2026-02-18-110212.png

Middleware 보안 계층부터 nuqs 기반의 단방향 데이터 흐름까지 아우르는 muroom 프론트엔드 시스템 아키텍처

"사용자 경험의 완결성을 위한 뷰 통제와 커뮤니티 아키텍처"

커스텀 지도 엔진: 네이버 지도 SDK를 리액트 환경에 최적화하여 구현했습니다. 현재 위치 기반의 실시간 데이터 동기화를 통해 연습실 정보를 시각화합니다.
useResponsiveLayout 기반의 뷰 통제: 1080px 브레이크포인트를 기준으로 모바일과 웹 레이아웃을 엄격히 분리합니다. 하이드레이션 이슈를 방지하기 위해 isMounted 상태를 추적하며, 디바이스별로 최적화된 UI를 렌더링하도록 시스템적으로 통제합니다.

나의 작업실 자랑하기: 뮤지션들이 본인의 작업 공간을 공유하는 이미지 중심의 커뮤니티입니다.
무한 계층형 댓글 시스템: 댓글-대댓글-답글로 이어지는 다중 중첩 구조를 구현했습니다.
- 재귀적 컴포넌트 설계: 데이터의 깊이에 상관없이 선언적으로 렌더링을 수행하도록 설계했습니다.
- 인터페이스 최적화: 복잡한 계층 구조에서도 모바일과 웹 각각의 환경에 맞는 가독성을 유지하는 데 집중했습니다.

Desktop View (Web)	Mobile View (App)

지도 탐색부터 복합 필터링, 커뮤니티 인터랙션까지 이어지는 핵심 서비스 플로우

개발 과정에서 마주한 기술적 고민들과 이를 해결하기 위해 시도한 접근 방식입니다. 상세 내용은 개별 회고록에 정리되어 있습니다.

"예외 상황을 통제하고 시스템의 예측 가능성을 높이는 데 집중했습니다."

데이터 기반의 에러 트래킹: 공통 error.tsx와 GA4를 연동하여 예외 발생 시 상세 로그(description, digest 등)를 데이터화합니다. 장애 발생 빈도를 실시간으로 모니터링하며, 배포 후 안정성을 객관적 지표로 관리합니다.
사용자 친화적 복구 UI: 404/500 에러 상황에서 useResponsiveLayout을 통해 디바이스별로 최적화된 복구 경로를 제공하여 서비스 이탈을 최소화했습니다.

타입 안정성 확보 (Generic): customFetch에 제네릭을 적용하여 API 응답 규격을 컴파일 단계에서 검증합니다. 런타임 데이터 구조 불일치 에러를 차단하여 시스템의 견고함을 확보했습니다.
2,000ms 타임아웃 제어: AbortSignal.timeout을 적용해 2초가 지나도 데이터가 오지 않는 지연 요청은 강제로 종료합니다. 백엔드 네트워크 오류 등으로 사용자가 무작정 기다리는 일을 방지하기 위해 프론트에서 먼저 연결을 끊고, 자연스러운 재연결을 유도하여 시스템의 반응성을 일정하게 유지합니다.
메모리 무결성 검증: 크롬 힙 스냅샷(Heap Snapshot) 분석을 통해 페이지 전환 간 메모리 누수 지점을 제거했습니다. 반복적인 라우팅 상황에서도 메모리 점유율을 일정하게 유지하며 저사양 기기에서의 안정성을 높였습니다.

📉 Network Resiliency: 2.0s 타임아웃 강제 종료를 통한 무한 로딩 방지 (Network Waterfall 기반)