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

"관심사 분리를 통한 위젯 엔진 패키지화와 하이브리드 운영 전략"

사용자 자율도가 높은 대시보드 시스템의 확장성을 확보하고, 인프라 운영 효율을 극대화하는 하이브리드 아키텍처를 설계하는 데 집중했습니다.

🛠 Tech Stack Overview

---

🔍 Architecture Deep-Dive

[구조] 관심사 분리를 위한 위젯 엔진 패키지화

• Widget Engine Isolation: 메인 애플리케이션의 비즈니스 로직과 복잡한 레이아웃 연산 로직을 분리하기 위해 내부 패키지(packages/widget)를 구축했습니다. 이를 통해 위젯의 기능 확장이 앱 전체 빌드 성능에 주는 영향을 차단하고, 시스템의 뼈대가 되는 '그리드 엔진'의 독립적인 테스트 환경을 확보했습니다.

[검증] 운영 환경 동기화를 위한 하이브리드 인프라

• Environment-Aware Mocking: NEXT_PUBLIC_API_MODE 환경 변수에 따라 Vercel(Mock Mode)과 AWS(Real Mode)를 유연하게 스위칭합니다. 특히 Vercel 환경에서도 MSW와 instrumentation.ts를 활용해 실서버와 동일한 인터페이스를 검증할 수 있는 모킹 전략을 수립했습니다.

[운영] 브랜치 전략 기반의 효율적인 배포 파이프라인

• Git-flow 기반 배포 최적화: 기능 개발(feature)부터 출시(main)까지의 사이클에 맞춰 Vercel(Preview/STG)과 AWS(Production)를 교차 활용합니다. 이를 통해 비용 부담 없는 상시 통합 테스트 환경을 구축하고, 운영 환경 에러에 즉각 대응할 수 있는 안정성을 확보했습니다.

헬로월드 프로젝트의 하이브리드 배포 파이프라인 및 브랜치 운영 전략

---

2. 📱 주요 기능 및 서비스

"사용자 편의를 고려한 위젯 기반의 자유로운 대시보드 환경"

🧩 그리드 시스템 기반 커스텀 대시보드

• 자석 같은 그리드 스냅(Snapping): 위젯을 드래그할 때 모호한 위치에 배치되지 않도록, 미리 정의된 그리드 칸에 맞춰 '착' 달라붙는 정렬 기능을 구현하여 조작의 편의성을 높였습니다.
• 유기적인 위젯 재배치: 특정 위젯이 이동하거나 크기가 변할 때, 주변 위젯들이 겹치지 않고 빈 공간을 찾아 자동으로 밀려나는 실시간 충돌 감지 로직을 적용했습니다.

📸 편집 모드와 스냅샷(Snapshot) 기능

• 원자적 수정 취소: 편집 중 배치가 마음에 들지 않을 경우, '취소' 버튼 하나로 편집 시작 전 상태로 즉시 복구할 수 있는 스냅샷 패턴을 적용했습니다. 사용자가 데이터 유실 걱정 없이 자유롭게 레이아웃을 실험해 볼 수 있는 환경을 제공합니다.

💾 대시보드 설정 자동 저장 및 유지

• 브라우저 기반 레이아웃 저장: Zustand Persist를 활용해 사용자가 설정한 위젯의 위치와 종류를 브라우저에 기록합니다. 페이지를 새로고침하거나 다시 접속해도 마지막으로 설정한 대시보드 형태가 그대로 유지되어 탐색의 연속성을 보장합니다.

---

🎥 기능 시연 (Feature Showcase)

> 그리드 스냅부터 위젯 충돌 감지, 유기적 재배치까지 이어지는 대시보드 인터랙션 데모

---

3. 🛠️ 주요 해결 과제

개발 과정에서 직면한 기술적 병목과 인프라적 제약을 데이터 기반의 가설 검증으로 해결한 과정입니다.

1. Vercel 환경의 405 에러 극복과 서버 사이드 모킹

• 고민: Next.js App Router의 Server Action 요청이 Vercel 라우터와 충돌하여 405 Method Not Allowed가 발생하고, 백엔드 미완성 시 서버 런타임 로직 검증이 불가능한 문제
• 해결: instrumentation.ts를 통해 서버 MSW를 선제 구동하고, 가짜 도메인(Dummy Domain) 전략을 도입해 라우팅 간섭을 우회했습니다. 이를 통해 운영 환경과 동일한 인증/데이터 흐름을 백엔드 없이도 선제 검증하는 하이브리드 모킹 아키텍처를 구축했습니다.
• 🔗 [인프라 제약을 넘어선 하이브리드 모킹 아키텍처 구축기]

2. 고빈도 DnD 인터랙션의 렌더링 성능 최적화 (52% 개선)

• 고민: 60개 이상의 위젯이 포함된 대시보드에서 드래그 중 발생하는 무수한 상태 변화로 인해 프레임 저하(Jank)와 연산 부하 발생
• 해결: useMemo를 통한 연산 격리와 useShallow 기반의 정밀 상태 구독을 적용했습니다. 그 결과 렌더링 시간을 9.4ms에서 4.5ms로 약 52% 단축했으며, React Profiler를 통해 불필요한 자식 렌더링이 완벽히 차단됨을 실증 데이터로 확인했습니다.
• 🔗 [연산 효율화: useMemo와 정밀 구독으로 달성한 고성능 대시보드 엔진]

3. 메인 스레드 점유율 최소화 (연산 횟수 98% 절감)

• 고민: 드래그 중 매 순간 발생하는 위치 동기화 로직이 메인 스레드를 과점하여 저사양 기기에서 반응 속도가 느려지는 현상
• 해결: Debounced Interaction Sync 기법을 도입해 조작 중에는 UI 피드백에만 집중하고, 조작 종료 시점에만 최종 상태를 확정하도록 설계했습니다. 이를 통해 불필요한 상태 업데이트 연산을 약 98% 절감하여 끊김 없는 고품질 UX를 확보했습니다.
• 🔗 [프레임 예산 사수하기: 디바운싱을 통한 인터랙션 최적화 전략]

4. 위젯 엔진 격리 및 패키지 마이그레이션

• 고민: 비즈니스 로직과 뒤섞인 위젯 코드로 인한 유지보수 리스크와 운영 환경 파편화로 인한 코드 중복 발생
• 해결: 시스템 핵심 로직을 별도 내부 패키지(@helloworld/widget)로 분리하고, Turborepo 캐싱을 활용해 빌드 속도를 3분 29초에서 21초로 단축했습니다. 독립적인 테스트 환경에서 라인 커버리지 100%를 달성하여 시스템 확장성을 근본적으로 개선했습니다.
• 🔗 [관심사의 분리부터 빌드 성능 최적화까지: 위젯 엔진 패키지 이관 기록]

---

4. 📊 서비스 안정성 및 품질 관리

"사용자가 공들여 만든 공간이 무너지지 않도록, 보이지 않는 곳에서의 견고함을 추구했습니다."

🛡️ 유저의 '경험의 연속성'을 지키는 테스트

• 사용자 설정 보호를 위한 핵심 로직 검증: 사용자가 공들여 배치한 위젯 설정이 꼬이지 않도록, 시스템의 '뇌' 역할을 하는 그리드 엔진과 상태 스토어에 대해 라인 커버리지 100% 를 달성했습니다. 이를 통해 어떤 환경에서도 유저의 데이터가 의도한 대로 유지되도록 방어했습니다.
• 일관된 대시보드 환경 제공: 모든 위젯의 베이스가 되는 컴포넌트를 사전에 검증하여, 새로운 기능이 추가되더라도 기존 유저의 조작 맥락이 깨지지 않는 안정적인 환경을 구축했습니다.

⚡ 기민한 개선을 위한 빌드 최적화

• 필요한 것만 빌드하는 효율성: turbo prune을 활용해 모노레포 내 전체 패키지가 아닌, 서비스 실행에 필요한 최소한의 컨텍스트만 추출하여 빌드 프로세스를 가볍게 유지했습니다.
• 캐시 최적화를 통한 빠른 피드백: Docker의 멀티 스테이지 빌드와 레이어 캐싱(type=gha) 전략을 통해 종속성 변화가 없을 시 중복 연산을 건너뜁니다. 이를 통해 전체 배포 과정을 21초까지 단축하여, 유저의 불편 사항을 지연 없이 개선할 수 있는 환경을 만들었습니다.

🔒 안전한 운영 환경 관리

• 최소 권한 원칙의 자동화: 보안을 위해 SSH 포트를 상시 개방하는 대신, 배포 시점에만 GitHub Actions 러너의 IP를 동적으로 화이트리스트에 등록하고 종료 후 즉시 회수하는 파이프라인을 구축했습니다. 유저의 정보가 흐르는 인프라를 보다 안전하게 관리하는 데 주력했습니다.

---

🔍 Stability Proof

🛡️ Core Logic Coverage: 유저 데이터를 지키는 핵심 레이어 집중 테스트 (Vitest 100%)

[Vitest Report] 위젯 배치 및 상태 관리 로직에 대한 완벽한 검증으로 유저 경험의 안정성 확보

⚡ CI/CD Performance: 캐시 최적화를 통한 기민한 버그 수정 (Hot Build 21s)

[GitHub Actions] Docker 캐싱과 turbo prune을 활용해 유저에게 개선 사항을 빠르게 전달하는 배포 지표

---

5. 📈 엔지니어링 가치 및 회고

기술적 화려함보다는 확장 가능한 구조와 지속 가능한 운영 환경을 구축하는 데 에너지를 쏟았습니다.

✅ 엔진 내재화를 통한 시스템 주도권 확보

• 기성 라이브러리에 의존해 UI를 구성하기보다, packages/widget이라는 독립된 엔진을 직접 설계하며 시스템의 통제권을 확보했습니다.
• 이러한 격리된 아키텍처는 향후 어떤 복잡한 위젯이 추가되더라도 메인 앱의 성능에 영향을 주지 않는 견고한 확장성의 밑바탕이 되었습니다.

✅ 효율을 위한 하이브리드 인프라 설계

• AWS의 안정성과 Vercel의 기민함을 결합한 하이브리드 배포 전략을 통해, 1인 개발 환경에서 발생할 수 있는 인프라 비용과 관리 공수를 최적화했습니다.
• 특히 배포 시점에만 방화벽을 제어하는 보안 자동화는 "안전하면서도 빠른 개발" 이라는 두 마리 토끼를 잡는 소중한 경험이었습니다.

🚀 현재의 한계와 향후 로드맵 (Roadmap)

'헬로월드'는 현재 핵심 엔진과 인프라 파이프라인이 완성된 상태이며, 유저에게 더 풍부한 학습 경험을 제공하기 위한 기능들을 순차적으로 개발하고 있습니다.

• 사전 레벨 테스트: 유저의 현재 수준을 정밀하게 측정하고 최적화된 학습 경로를 추천하는 로직을 준비 중입니다.
• 코딩 테스트 풀이 엔진: 대시보드 내에서 직접 코드를 작성하고 결과를 확인할 수 있는 위젯을 기획하고 있습니다.
• 성취 및 업적 시스템: 학습의 재미를 더해줄 뱃지, 포인트, 랭킹 등 게이미피케이션 요소들을 엔진 위에 얹어갈 예정입니다.

---

"완벽한 결과물보다, 완벽한 기초를 다지는 과정에 집중했습니다."

단순한 코드 작성을 넘어 인프라와 성능, 그리고 사용자 경험을 동시에 조망할 수 있었던 의미 있는 프로젝트였습니다.