프론트엔드 아키텍처 설계 시 고려 항목 리스트 (Checklist)

 

 

프론트엔드 아키텍처 설계 시 고려 항목 리스트

📌 프론트엔드 아키텍처 설계 시 고려 항목 리스트

1. 기술 스택 및 개발 환경 (Tech Stack & Environment)
2. 라우팅 및 페이지 구조 전략 (Routing & Page Structure Strategy)
3. 렌더링 전략 및 기반 환경 (Rendering Strategy & Foundation)
4. 상태 관리 전략 (State Management Strategy)
5. 컴포넌트 및 UI 설계 (Component & UI Design)
6. 데이터 통신 및 어댑터 패턴 (Data Layer & Adapter)
7. 에러 핸들링 및 사용자 경험 (Resilience & UX)
8. 품질 보증 및 배포 (QA & DevOps)
9. 보안 및 성능 (Security & Performance)

 

 

 

 

1. 기술 스택 및 개발 환경 (Tech Stack & Environment)

• SPA vs MPA 전략 선택
  - 프로젝트의 크기, 복잡도, 필요한 SEO 수준, 개발팀의 숙련도에 따라 결정
• 렌더링 방식
  : SPA를 선택했다면 CSR (Client-Side Rendering)이 기본이 되며, 성능 개선을 위해 SSR/SSG를 추가로 고려
• 언어
  : TypeScript 사용 여부 (현대 웹 개발에서는 필수 권장)
• 프레임워크/라이브러리
  - SPA라면 React, Vue, Svelte 등의 현대적 라이브러리가 필수적이며, MPA라면 서버 측 템플릿 엔진 주로 사용
• 빌드 도구
  : Vite, Webpack, rspack 등 번들링 속도와 생태계 고려
• 코드 스플리팅
  : 라우트 단위(Page-level)로 JavaScript 코드를 분할(Split)하여 초기 로딩 속도를 최적화하는 전략
• 패키지 매니저
  : npm, yarn berry(PnP), pnpm (Monorepo 필요 여부에 따라 결정)
  
  

🔖 Monorepo vs Multi-repo

 

 

 

 

2. 라우팅 및 페이지 구조 전략 (Routing & Page Structure Strategy)

 

💡 라우팅은 라우팅은 단순히 URL을 연결하는 기능이 아니라, 
      사용자에게 어떤 페이지를 어떤 권한으로 어떤 레이아웃에 담아 보여줄 것인가를 결정하는 구조적 핵심으로
      접근 제어, 데이터 로딩, 레이아웃 관리를 포괄.

• 라우터 라이브러리 선정
  - 프레임워크 종속: Next.js Router, Vue Router 등 프레임워크 내장 라우터 사용 여부
  - 독립적: React Router DOM 등 별도 라이브러리 사용 여부
• 라우팅 방식 결정
  - 파일 시스템 기반 라우팅: 파일 구조가 곧 URL 경로가 되도록 할 것인가? (Next.js, Remix, Nuxt 등)
  - 선언적 라우팅: 모든 경로를 별도의 파일에 수동으로 정의할 것인가?
• 접근 제어 (Access Control) 전략
  - 인증 가드 (Authentication Guard)
     : 로그인/권한이 필요한 페이지에 대한 접근을 어떻게 막을 것인가? (예: AuthGuard 컴포넌트 또는 훅 사용)
  - 리다이렉션 처리: 접근 권한이 없을 때 로그인 페이지 또는 403 페이지로 리다이렉트하는 공통 로직
• 레이아웃 관리
  : 페이지 그룹별 공통 레이아웃 컴포넌트를 어떻게 구조화하여 중복 코드를 제거할 것인가? (예: Nested Layouts)
• 데이터 로딩 전략
  : 라우트 기반 로딩: 페이지 진입 시 필요한 데이터를 라우트 레벨에서 미리 로딩할 것인가? (Suspense, Router Loader 활용)

 

 

3. 렌더링 전략 및 기반 환경 (Rendering Strategy & Foundation)

 

💡 프로젝트의 성격(SEO, 초기 로딩 속도, 데이터 갱신 빈도)에 따라 앱이 브라우저에 그려지는 방식을 결정

• 렌더링 방식 결정 (Critical)
  - CSR (Client-Side Rendering): SEO가 덜 중요한 어드민, 대시보드.
  - SSR (Server-Side Rendering): SEO 중요, 초기 로딩 빨라야 함.
  - SSG (Static Site Generation): 변경이 적은 블로그, 소개 페이지.
  
  
• 폴더 구조 패턴 (Directory Pattern)
  - src/components: 정말 재사용 가능한 UI만 (Button, Input)
  - src/features 또는 src/modules: 특정 기능과 관련된 컴포넌트, 훅, API를 한곳에 응집 
     (User, Cart, Product 등 도메인 기준). 유지보수에 가장 강력한 영향
• 환경 변수 관리
  : 개발(Dev), 검증(Staging), 운영(Prod) 환경별 변수 분리 및 타입 안전성 확보 (예: zod를 이용한 환경변수 검증)

 

 

4. 상태 관리 전략 (State Management Strategy)

💡 SPA인 경우 모든 상태가 메모리에 유지되므로, 복잡한 전역 상태 관리 라이브러리(Zustand, Recoil 등)가 필수적으로 요구
      MPA인 경우 페이지 이동 시 모든 상태가 초기화되므로, 상태 관리가 비교적 단순하거나 URL, 쿠키 등에 의존하는 경향

• Server State (데이터 캐싱): 백엔드 DB 데이터의 스냅샷.
  : API 데이터 캐싱, 동기화 (예: TanStack Query, SWR)
• Client State (UI 상태): 다크 모드, 사이드바 열림/닫힘, 모달 상태, UI 테마, 유저 세션 등 전역적으로 필요한 데이터
  - 전역 라이브러리(Zustand 등)를 쓰되 최소화
• Form State
  : 복잡한 폼 유효성 검사 및 핸들링 (예: React Hook Form)
• URL State (URL 동기화)
  검색 필터, 페이지네이션 정보는 스토어가 아닌 URL Query Parameter에 저장
  그래야 "새로고침" 해도 유저가 보던 화면이 유지

 

 

5. 컴포넌트 및 UI 설계 (Component & UI Design)

💡 컴포넌트 간의 엉킴을 방지하기 위한 명확한 규칙이 필요

• 디자인 패턴
  : 아토믹 디자인(Atomic Design), 합성 컴포넌트(Compound Component), Headless UI 패턴 중 선택
• 스타일링
  : CSS-in-JS (Styled-components, Emotion) vs 유틸리티 클래스 (Tailwind CSS) vs CSS Modules
• 디자인 시스템
  : 공통 UI 컴포넌트 라이브러리 도입 여부 (MUI, Shadcn UI 등)
• Presentational vs Container 패턴 (또는 Headless 패턴)
  - Presentational: 스타일과 보여지는 것만 담당 (로직 X)
  - Container/Hooks: 비즈니스 로직과 상태만 담당 (UI X)
• 의존성 방향
  - 페이지(Pages)는 컴포넌트(Components)를 알지만, 컴포넌트는 페이지를 몰라야 함
  - 공통 컴포넌트는 비즈니스 로직(특정 도메인 데이터)을 직접 참조하지 않고 Props로만 받아야 함
• 페이지 컴포넌트
  : 라우팅 경로에 매핑되는 페이지 컴포넌트 내에서는 비즈니스 로직만 수행하고,
    재사용 가능한 작은 컴포넌트들을 합성하는 역할만 하도록 책임을 명확하게 함

 

 

6. 데이터 통신 및 어댑터 패턴 (Data Layer & Adapter)

💡 백엔드 API 변경이 프론트엔드 코드 전체를 망가뜨리지 않도록 방어막

• Mapper/DTO (Data Transfer Object) 패턴
  - 백엔드에서 user_name으로 주더라도, 프론트에서는 userName으로 변환해서 사용
  - 백엔드 필드명이 바뀌어도 매퍼 함수 하나만 수정하면 앱 전체가 안전
• API 클라이언트 추상화
  - axios.get을 컴포넌트에서 직접 쓰지 않고, api.user.getProfile() 처럼 함수로 감싸서 호출
  - 인터셉터(Interceptor)에서 토큰 갱신(Silent Refresh) 로직을 중앙화

 

 

7. 에러 핸들링 및 사용자 경험 (Resilience & UX)

• 선언적 에러 처리 (Declarative Handling)
  - ErrorBoundary를 사용하여 특정 컴포넌트가 터져도 전체 페이지(헤더, 푸터)는 살아있도록 함
• 낙관적 업데이트 (Optimistic Update)
  - '좋아요' 버튼을 누르면 서버 응답을 기다리지 않고 즉시 색을 채운 뒤, 실패하면 롤백 (체감 속도 향상)
• 로딩 전략 (Suspense/Skeleton)
  - 단순 스피너(Spinner)보다 스켈레톤 UI를 사용하여 로딩 중 체감 지루함을 줄

 

 

8. 품질 보증 및 배포 (QA & DevOps)

💡 SPA인 경우 초기 로딩 속도 최적화(Code Splitting)와 Hydration 테스트가 중요해지고, 
      MPA인 경우 페이지별 서버 응답 시간(TTFB) 최적화가 중요해 짐

• 테스트 전략
  : Unit Test (Vitest/Jest), E2E Test (Cypress/Playwright), 시각적 테스트 (Storybook)
• 린트 및 포맷팅
  : ESLint, Prettier 설정의 엄격도(Strictness) 결정
• CI/CD
  : GitHub Actions 등을 통한 빌드/테스트/배포 자동화 파이프라인
• 모니터링
  : 배포 후 에러 트래킹 (Sentry) 및 성능 모니터링

 

 

9. 보안 및 성능 (Security & Performance)

• 보안
  - XSS 방지: innerHTML 사용 지양 및 Sanitization 라이브러리(DOMPurify) 사용
  - 인증: Access Token은 메모리 변수에, Refresh Token은 HttpOnly Cookie에 저장하는 것이 일반적인 보안 권장 사항
• 성능
  - Code Splitting: 라우트별로 JS 파일을 쪼개서 초기 로딩 속도 최적화
  - Image Optimization(이미지 최적화): WebP 포맷 사용, Lazy Loading 적용