Frontend Wiki

🧭 Frontend Team Wiki

이 문서는 프론트엔드 팀의 기술, 규칙, 결정사항, 운영 방식을 기록하고 공유하기 위한 위키입니다. 모든 변경 사항은 문서화 및 날짜 기록을 원칙으로 합니다.

---

1. 프로젝트 개요

2. 기술 스택 및 선정 이유

3. 아키텍처 및 구조

4. WebView 애플리케이션 구조

5. 협업용 컨벤션 정의

---

🗂️ 참고 자료

공식 문서

기술	문서
Stackflow	https://stackflow.so
TanStack Query	https://tanstack.com/query/latest
Zustand	https://zustand.docs.pmnd.rs
Ky	https://github.com/sindresorhus/ky
TailwindCSS 4	https://tailwindcss.com/docs
CVA	https://cva.style
@webview-bridge	https://github.com/gronxb/webview-bridge
openapi-typescript	https://openapi-ts.dev
Expo	https://docs.expo.dev

서비스 URL

환경	URL
프로덕션 웹	https://hellocs.site
API	https://api.hellocs.site
API Docs (Swagger)	https://api.hellocs.site/v3/api-docs
Grafana	https://hellocs.site/grafana/

---

✨ 8. 사용 팁 및 규칙

8-1 개발 시작

# Web
cd web && pnpm install && pnpm dev        # http://localhost:5173

# Mobile
cd mobile && npm install && npm start     # Expo dev server

8-2 API 타입 재생성

백엔드 API가 변경됐을 때 실행:

cd web && pnpm generate:api-models

.env에 API_SWAGGER_URL 설정 필요.

8-3 새 페이지 추가 체크리스트

• src/pages/<feature>/<PageName>.tsx 생성
• src/app/stackflow-route.tsx에 { name, component, path } 등록
• 필요 시 src/api/<feature>/, src/model/<feature>/ 추가

8-4 새 브릿지 기능 추가 체크리스트

• mobile/bridge/index.ts의 AppBridgeType에 메서드 시그니처 추가
• bridge() 구현체에 실제 로직 작성
• 웹에서 window.bridge.xxx() 호출로 검증

8-5 협업 주의사항

• api-models.ts는 자동생성 파일 — 직접 수정 금지, pnpm generate:api-models로만 갱신
• 커밋 메시지 형식 미준수 시 commitlint 훅이 거부함
• main 브랜치 push 시 GitHub Actions가 자동 빌드 + 배포 트리거됨 (web 경로 변경 시)
• ESLint import 순서 위반 시 CI에서 실패 — 로컬에서 pnpm lint 먼저 확인

8-6 Vite 개발 프록시

로컬 개발 시 아래 경로는 https://hellocs.site로 프록시됨:

• /api/
• /v3/
• /swagger-ui/

---

📚 9. 기술 심화 / 논문 참고 내용

이 섹션은 프로젝트에서 적용한 기술 개념을 학술적 관점에서 기술한다. 실제 구현 파일과 연결해 이론과 실천의 연결고리를 확인할 수 있다.

---

9-1 WebView 기반 하이브리드 앱 아키텍처

개념

네이티브 앱과 웹 앱의 이분법 대신, WebView를 쉘(Shell)로 사용하고 웹 앱이 UI 전체를 담당하는 하이브리드 아키텍처. 단일 코드베이스로 iOS/Android를 동시 지원하면서, 웹의 빠른 배포 주기를 유지할 수 있다.

이 프로젝트의 구현

[React Native Shell]
  └─ LinearGradient 배경
  └─ SafeAreaView
  └─ <WebView source={{ uri: WEBVIEW_URL }} />  ← 웹 앱 전체 렌더링
       └─ @webview-bridge로 Native API 노출

• 네이티브 역할: 마이크, 로그인 상태, 딥링크, 스플래시 화면
• 웹 역할: 전체 UI/UX, 라우팅, 비즈니스 로직

학술적 맥락

접근 방식	예시	특징
네이티브 앱	Swift, Kotlin	최고 성능, 플랫폼별 개발 비용
크로스 플랫폼 네이티브	React Native, Flutter	단일 코드, 네이티브 렌더링
WebView 하이브리드	이 프로젝트	웹 배포 속도 + 네이티브 기능
PWA	Service Worker 기반	설치 없이 앱 유사 경험

관련 키워드: Hybrid Mobile Application Architecture, WebView Bridge Pattern, Cross-Platform Development

---

9-2 JavaScript Bridge 통신 패턴과 타입 안전성

문제

WebView와 Native 사이의 통신은 전통적으로 postMessage(string) — 단방향 문자열 메시지로 이루어졌다. 이 방식은:

• 응답을 추적할 수단이 없음 (Fire-and-forget)
• 타입 정보 소실 (직렬화/역직렬화)
• 에러 처리 불명확

이 프로젝트의 해결책 (@webview-bridge)

요청 흐름:
Web: window.bridge.startRecording()
  → 라이브러리가 고유 messageId 부여 + JSON 직렬화 → postMessage
  → Native: messageId로 응답 매핑 → Promise resolve

타입 계약:
interface AppBridgeType extends Bridge {
  startRecording: () => Promise<{ status: "success" | "error" }>
}
// Web과 Native가 동일 인터페이스 타입을 공유

학술적 맥락

• RPC (Remote Procedure Call) 개념의 WebView 내 적용: 로컬 함수 호출처럼 보이지만 직렬화 → 채널 전송 → 역직렬화 과정을 거침
• 타입 안전 IPC(Inter-Process Communication): 컴파일 타임에 인터페이스 불일치를 감지
• Promise 기반 비동기 처리로 콜백 지옥(Callback Hell) 문제 해결

관련 키워드: JavaScript Bridge, Type-Safe IPC, WebView Communication, RPC Pattern

---

9-3 유한 상태 머신(FSM)으로 모델링한 퀴즈 풀이 흐름

개념

FSM(Finite State Machine): 유한한 상태(State)와 상태 간 전이(Transition)로 시스템을 모델링하는 계산 이론의 기본 개념.

이 프로젝트의 구현

퀴즈 풀이 단계는 명시적 FSM으로 구현되어 있다 (useQuizStore.ts):

States: "ox" | "select" | "text"

Transitions:
  초기화 → ox (OX 문제 있으면)
         → select (객관식만 있으면)
         → text (단답형만 있으면)

  ox → ox     (다음 OX 문제)
  ox → select (OX 완료, 객관식 있으면)
  ox → text   (OX 완료, 객관식 없고 단답형 있으면)
  ox → [완료] (OX 완료, 이후 문제 없으면 completionPayload 세팅)

  select → select (다음 객관식)
  select → text   (객관식 완료, 단답형 있으면)
  select → [완료]

  text → text   (다음 단답형)
  text → [완료]

• 역방향 전이(goToPreviousQuestion)도 구현: 스택 기반으로 이전 상태 복원
• UI 컴포넌트는 현재 state만 받아 렌더링 → 상태와 뷰의 명확한 분리

학술적 맥락

• UI 개발에서 FSM 모델링은 XState 라이브러리로도 널리 쓰임. 이 프로젝트는 Zustand 내에 직접 FSM을 구현한 사례
• **명시적 상태(Explicit State)**는 "impossible state"를 타입 시스템으로 방지 (vs. 여러 boolean 조합)
• React의 useReducer도 FSM 구현 수단으로 자주 인용됨

관련 키워드: Finite State Machine, UI State Modeling, Explicit State, XState, Impossible States

---

9-4 Result 타입 패턴: 타입 안전 에러 처리

문제

try/catch 기반 에러 처리는 함수 시그니처에서 실패 가능성이 드러나지 않는다. 호출자가 에러 처리를 잊어도 컴파일러가 감지하지 못한다.

이 프로젝트의 구현 (api-client-handler.ts)

type Ok<T> = { ok: true;  data: T; status: number; headers: Headers }
type Err   = { ok: false; error: { message: string }; status: number }

export type ApiResult<T> = Ok<T> | Err

호출부에서 ok 여부를 확인하기 전까지 data에 접근 불가:

const res = await postQuizList(params);
if (!res.ok) throw new Error("퀴즈 조회 실패");
return res.data; // 여기서만 data 타입 보장

학술적 맥락

• Rust의 Result<T, E> 타입, Haskell의 Either 모나드에서 영감
• TypeScript의 Discriminated Union(판별 유니온) 패턴의 실무 적용 사례
• Railway-Oriented Programming: 성공/실패 두 레일로 로직을 흘려보내는 함수형 에러 처리 기법

관련 키워드: Result Type, Discriminated Union, Railway-Oriented Programming, Type-Safe Error Handling

---

9-5 선언적 서버 상태 관리와 캐시 전략

문제

전통적 방식(Redux + 수동 fetch)에서 서버 상태를 관리하면:

• 로딩/에러/성공 상태를 매번 직접 관리
• 캐시 무효화 타이밍 직접 지정
• 중복 요청 방지 로직 반복 작성

이 프로젝트의 구현 (React Query)

// 선언적 쿼리 정의
export const quizQueries = {
  getQuizTopicQuery: () =>
    queryOptions({
      queryKey: ["quiz", "topic"],
      queryFn: async () => { /* fetch */ },
    }),
};

// 컴포넌트에서는 캐시/로딩/에러를 자동으로 처리
const { data, isLoading, isError } = useQuery(quizQueries.getQuizTopicQuery());

캐시 키 계층 구조:

["quiz"]
  └─ ["quiz", "topic"]
  └─ ["quiz", "list", { topicId, count }]
  └─ ["quiz", "grading-log", gradingLogId]

학술적 맥락

• Stale-While-Revalidate(SWR): 캐시된 데이터를 즉시 반환하면서 백그라운드에서 갱신 — HTTP RFC 5861에서 정의, React Query가 이 전략을 UI에 적용
• 서버 상태(Server State) vs 클라이언트 상태(Client State) 분리: 서버 상태는 비동기적이고 공유됨 → 전용 라이브러리로 관리
• React Query의 캐시는 Normalized Cache 방식이 아닌 Key-Value 방식 (Apollo와 차이점)

관련 키워드: Server State Management, Stale-While-Revalidate, Cache Invalidation, Declarative Data Fetching

---

9-6 인증 토큰 갱신과 경쟁 조건(Race Condition) 방지

문제

SPA에서 Access Token 만료 시 여러 API 요청이 동시에 401을 받으면, Refresh Token으로 토큰 갱신 요청이 N번 중복 발생할 수 있다 → Refresh Token이 단 한 번만 유효한 경우 나머지 요청 실패.

이 프로젝트의 해결책 (api-client.ts)

// Promise를 변수에 공유 → 중복 요청 방지
let refreshAccessTokenPromise: Promise<string | null> | null = null;

async function refreshAccessToken() {
  if (!refreshAccessTokenPromise) {
    refreshAccessTokenPromise = (async () => {
      // 실제 갱신 요청 (한 번만 실행)
      const result = await apiClientHandler(baseApiClient, END_POINTS.AUTH.REISSUE, { method: "POST" });
      // ...
    })().finally(() => {
      refreshAccessTokenPromise = null; // 완료 후 초기화
    });
  }
  return refreshAccessTokenPromise; // 진행 중이면 같은 Promise 반환
}

동시에 5개 요청이 401을 받아도 갱신 요청은 정확히 1회만 발생하고, 나머지 4개는 같은 Promise를 await.

학술적 맥락

• Promise Coalescing / Request Deduplication: 동일 비동기 작업을 하나로 합치는 패턴
• Refresh Token Rotation: 갱신 시마다 새 Refresh Token 발급 → 탈취된 Refresh Token 재사용 방지 (OAuth 2.0 BCP)
• Silent Authentication: 사용자 개입 없이 세션을 자동 복구하는 UX 패턴

관련 키워드: Token Refresh Race Condition, Promise Coalescing, Silent Authentication, OAuth 2.0 Token Rotation

---

9-7 코드 스플리팅과 지연 로딩

개념

SPA(Single Page Application)의 단점인 초기 번들 크기 문제를 해결하는 기법. 라우트 단위로 JavaScript를 분리해 필요할 때만 로드.

이 프로젝트의 구현

// stackflow-route.tsx: 모든 Activity가 lazy()로 선언됨
const QuizSolvePage = lazy(() => import("@/pages/quiz/QuizSolvePage"));
const RankingPage   = lazy(() => import("@/pages/ranking/RankingPage"));
// ...

// stackflow-auth-shell.tsx: lazy된 AuthInitializer를 Suspense로 감싸
<Suspense fallback={null}>
  <AuthInitializer>{children}</AuthInitializer>
</Suspense>

• 초기 진입 시 LoginPage 번들만 로드
• 퀴즈 페이지 진입 시점에 QuizSolvePage 번들 로드
• Vite가 각 lazy import를 별도 chunk 파일로 분리

학술적 맥락

• PRPL 패턴 (Push, Render, Pre-cache, Lazy-load): Google이 제안한 Progressive Web App 성능 전략
• Core Web Vitals 중 LCP(Largest Contentful Paint) 개선에 직접 기여
• Dynamic Import (import()): ECMAScript 2020 표준. Webpack/Vite가 이를 기반으로 청크 분리

관련 키워드: Code Splitting, Lazy Loading, Dynamic Import, PRPL Pattern, Core Web Vitals

---

9-8 피처 기반 아키텍처 (Feature-Based Architecture)

개념

파일을 역할 기준(components/, services/, utils/)이 아닌 기능(Feature) 기준으로 그룹화하는 구조화 방식.

이 프로젝트의 적용

src/
├── api/
│   ├── quiz/         ← quiz 기능의 API 전부
│   │   ├── api.model.ts      (타입)
│   │   ├── api.query.ts      (React Query options)
│   │   └── postQuizList.ts   (fetch 함수)
│   └── ranking/      ← ranking 기능의 API 전부
├── model/
│   ├── quiz/         ← quiz 기능의 상태 전부
│   └── auth/
└── components/
    ├── quiz/         ← quiz 기능의 UI 전부
    └── common/       ← 공유 컴포넌트

한 기능을 수정할 때 관련 파일이 같은 폴더에 모여 있어 응집도(Cohesion) 높음, 기능 간 직접 의존성 낮아 결합도(Coupling) 낮음.

학술적 맥락

• 고응집 저결합(High Cohesion, Low Coupling): 소프트웨어 공학의 모듈 설계 원칙
• Screaming Architecture (Robert C. Martin): 디렉토리 구조를 보면 시스템이 무엇을 하는지 바로 알 수 있어야 한다
• Vertical Slice Architecture: 레이어(Controller-Service-Repository) 대신 기능 단위로 코드를 수직으로 자르는 패턴

관련 키워드: Feature-Based Architecture, Screaming Architecture, Vertical Slice, High Cohesion Low Coupling

---

9-9 OpenAPI 기반 타입 자동 생성 (Contract-First API)

개념

백엔드가 OpenAPI(Swagger) 스펙을 기준(Contract)으로 정의하고, 프론트엔드는 그 스펙에서 타입을 자동 생성. API 변경 시 재생성만 하면 타입 불일치를 컴파일 타임에 감지.

이 프로젝트의 흐름

백엔드 서버
  └─ /v3/api-docs (OpenAPI JSON 스펙 노출)
       ↓ pnpm generate:api-models
web/src/api/config/api-models.ts (자동 생성)
  └─ 각 api/*.model.ts에서 타입 참조
  └─ 컴포넌트에서 타입 안전하게 사용

학술적 맥락

• Schema-First / Contract-First Development: API 스펙을 코드보다 먼저 정의 → 프론트/백엔드 병렬 개발 가능
• Code Generation: 반복적인 보일러플레이트를 자동화 — 휴먼 에러 감소, 일관성 유지
• OpenAPI 3.0은 REST API의 사실상 표준 명세 언어로, IDL(Interface Definition Language)의 역할 수행

관련 키워드: Contract-First API Design, OpenAPI, Code Generation, Schema-Driven Development, IDL