Frontend Wiki

🧭 Frontend Team Wiki

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

📌 1. 프로젝트 개요

🎯 1-1 목적

CS 퀴즈 / 면접 준비 플랫폼 hellocs.site 의 클라이언트 애플리케이션 개발 및 유지보수
웹과 모바일(iOS/Android) 두 플랫폼 동시 지원을 단일 모노레포로 관리

👥 1-2 대상 사용자

구분	대상
주요 사용자	CS 취업 준비 중인 개발자
보조 사용자	이미 취업한 뒤 지식 점검을 원하는 개발자

⚙️ 1-3 주요 기능

퀴즈 풀기: OX / 객관식 / 단답형 3가지 유형의 CS 퀴즈 (회당 5문항)
음성 답변 (Voice Quiz): 모바일 마이크 녹음 → STT 변환으로 단답형 답변 입력
채점 및 피드백: 퀴즈 제출 후 AI 채점 + 오답 상세 확인
학습 스트릭: 연속 학습일 달력 시각화
랭킹: 전체 사용자 점수 순위
온보딩: 이름 → 관심사 → 퀴즈 레벨 → 완료 4단계
소셜 로그인: 카카오 OAuth

🧑‍💻 2. 기술 스택

🧩 2-1 Web 기본 스택

구분	기술	버전
Framework	React	19
Language	TypeScript	~5.9
Build Tool	Vite	8
Routing	Stackflow (`@stackflow/react`)	1.x
Styling	TailwindCSS + tailwind-merge + CVA	4.2
Client State	Zustand	5
Server State	TanStack React Query	5
HTTP Client	Ky	1.x
Animation	Motion (Framer Motion)	12
Package Manager	pnpm	9.15

🧩 2-2 Mobile 기본 스택

구분	기술	버전
Framework	React Native (Expo)	54
Language	TypeScript	catalog 공유
Navigation	expo-router	6
WebView	react-native-webview	13.15
Bridge	@webview-bridge/react-native	1.7
음성 녹음	expo-av	16
Package Manager	npm	-

🧩 2-3 공통 / 인프라

구분	기술
API 타입 자동생성	openapi-typescript (OpenAPI → TypeScript)
CI/CD	GitHub Actions (self-hosted runner)
서빙	Docker + Nginx 1.27
모니터링	Grafana (Nginx 프록시)
Lint	ESLint 9 + typescript-eslint
Commit	commitlint (커스텀 emoji 타입)

🏗️ 3. 아키텍처 및 구조

3-1 모노레포 구조

Deadlock-Client/
├── web/          # React 19 + Vite 웹 앱 (pnpm)
├── mobile/       # React Native Expo 앱 (npm)
└── CLAUDE.md

두 앱은 별도 패키지 매니저와 node_modules를 사용한다. 타입 공유는 없고, 브릿지 인터페이스(AppBridgeType)를 통해 Web ↔ Native 계약을 맞춘다.

3-2 Web 디렉토리 구조

web/src/
├── app/            # Stackflow 설정, 라우트 정의, 인증 쉘
├── pages/          # 각 라우트 Activity 컴포넌트
│   ├── home/
│   ├── login/
│   ├── onboarding/
│   ├── quiz/
│   ├── ranking/
│   ├── streak/
│   ├── user/
│   └── interview/
├── components/     # UI 컴포넌트 (feature별 + common/)
├── model/          # Zustand 스토어 + 커스텀 훅
│   ├── auth/       # useAuthStore
│   ├── quiz/       # useQuizStore, useQuizSolve, useVoiceQuiz
│   └── user/       # useUserStore
├── api/            # API 레이어
│   ├── config/     # ky 클라이언트, 엔드포인트, 자동생성 타입
│   ├── auth/
│   ├── quiz/
│   ├── ranking/
│   ├── streak/
│   └── user/
└── assets/         # 아이콘 SVG 컴포넌트

3-3 Routing (Stackflow)

각 페이지 = Activity 단위. stackflow-route.tsx에서 name / component / path 를 등록.
URL 동기화: historySyncPlugin — 브라우저 히스토리와 Activity 스택 자동 연동.
기본 fallback Activity: LoginPage
진입점: HomePage (인증 완료 후)
모든 Activity는 lazy() 로드로 코드 스플리팅 적용.

// 새 페이지 추가 예시
{ name: "NewPage", component: lazy(() => import("@/pages/new/NewPage")), path: "/new" }

3-4 상태 관리

상태 유형	도구	위치
인증 토큰	Zustand (`useAuthStore`)	`model/auth/`
퀴즈 풀이 흐름 (OX→객관식→단답형 순서)	Zustand (`useQuizSolveStore`)	`model/quiz/`
서버 데이터 캐시	React Query	`api/*/api.query.ts`
유저 프로필	Zustand (`useUserStore`)	`model/user/`

3-5 API 통신 방식

api/config/
├── api-client.ts         # ky 인스턴스 (baseApiClient, authApiClient)
├── api-client-handler.ts # 응답 파싱 유틸
├── api-client-method.ts  # GET/POST/PATCH/DELETE 래퍼
├── api-endpoints.ts      # END_POINTS 상수
└── api-models.ts         # openapi-typescript 자동생성 타입

인증 흐름: beforeRequest 훅에서 Authorization: Bearer <token> 주입
토큰 갱신: 401 응답 시 afterResponse 훅에서 /auth/reissue 자동 호출, 동시 요청 중복 방지(Promise 공유)
기능별 쿼리: api/*/api.query.ts 에서 queryOptions / mutationOptions 로 export

🔗 4. 브릿지 / 외부 연동 구조

4-1 Web ↔ Native 구조

모바일 앱은 WebView로 웹 앱을 래핑한다. 네이티브 기능(마이크, 로그인 상태)은 @webview-bridge 라이브러리를 통해 Web에서 호출한다.

Web (React)                  Native (React Native)
─────────────────────────── ──────────────────────────────
window.bridge.xxx()   ─────▶  bridge/index.ts 구현체 실행
                      ◀─────  Promise 결과 반환

4-2 현재 브릿지 인터페이스

interface AppBridgeType extends Bridge {
  isLoggedIn: boolean;
  logout: () => Promise<void>;
  startRecording: () => Promise<{ status: "success" | "error"; errorMessage?: string }>;
  stopRecording: () => Promise<{ status: "success" | "error"; text?: string; errorMessage?: string }>;
}

메서드	설명
`isLoggedIn`	네이티브에서 관리하는 로그인 상태
`logout()`	네이티브 측 로그인 상태 초기화
`startRecording()`	iOS/Android 마이크 권한 요청 + 녹음 시작 (expo-av)
`stopRecording()`	녹음 종료 + STT 변환 후 텍스트 반환

4-3 새 네이티브 기능 추가 절차

mobile/bridge/index.ts의 AppBridgeType 인터페이스에 메서드 추가
bridge() 구현체 내부에 로직 작성
웹에서 window.bridge.newMethod() 호출

4-4 딥링크 / 네비게이션 처리

webview/createHandleShouldStartLoad.ts: onShouldStartLoadWithRequest 핸들러
- intent: 스킴 → browser_fallback_url 파싱 후 window.location 이동
- kakaotalk://, kakaokompass:// 등 → Linking.openURL() 로 앱 실행
- kauth.kakao.com → WebView 내 처리 (카카오 OAuth 플로우)
- HTTP/HTTPS → WebView 처리
- 그 외 커스텀 스킴 → 네이티브 위임

4-5 음성 녹음 (STT) 흐름

Web: window.bridge.startRecording()
       ↓
Native: 마이크 권한 요청 → expo-av 녹음 시작
       ↓ (사용자가 완료 시)
Web: window.bridge.stopRecording()
       ↓
Native: 녹음 종료 → STT 서버 전송 → 텍스트 반환
       ↓
Web: 반환된 텍스트를 단답형 입력값으로 사용

⚠️ 현재 STT 서버 전송 로직은 미구현 (mock 텍스트 반환 중). bridge/audioRecorder.ts의 sendAudioToServer 함수 구현 필요.

📏 5. 코드 규칙 및 컨벤션

5-1 커밋 메시지

emoji [type] 한글 설명

type	사용 상황
`feat`	신규 기능
`fix`	버그 수정
`refactor`	리팩토링
`chore`	빌드/설정 변경
`docs`	문서
`style`	스타일(코드 변경 없음)
`test`	테스트
`perf`	성능 개선
`rename`	파일/변수명 변경
`remove`	코드/파일 삭제

예시: ✨ [feat] 퀴즈 타이머 추가

5-2 파일 / 컴포넌트 네이밍

대상	규칙	예시
컴포넌트 파일	PascalCase	`QuizSolvePage.tsx`
훅 파일	camelCase, `use` 접두사	`useQuizStore.ts`
API 파일	camelCase, 동사+명사	`postQuizList.ts`
상수	UPPER_SNAKE_CASE	`QUIZ_SOLVE_TOTAL_COUNT`
경로 alias	`@/` → `src/`	`@/components/common/Button`

5-3 디렉토리 규칙

pages: Stackflow Activity만 배치. 페이지 로직은 model/ 또는 components/로 분리.
components: feature명 폴더 하위에 관련 컴포넌트 배치. 재사용 공통 컴포넌트는 common/.
model: Zustand store + 관련 커스텀 훅을 feature별로 묶음.
api: api.model.ts (응답 타입) / api.query.ts (queryOptions) / 개별 fetch 함수 파일로 구분.

5-4 스타일링 규칙

유틸리티 클래스: TailwindCSS 4.2
클래스 병합: cn() 유틸 (tailwind-merge + clsx)
컴포넌트 variants: CVA (class-variance-authority) 사용

// CVA 예시
const buttonVariant = cva("base-class", {
  variants: { size: { large: "...", medium: "..." } },
  defaultVariants: { size: "large" },
});

5-5 ESLint Import 순서 (강제)

@/app → @/pages → @/components → @/api → @/model → 나머지

5-6 상태 관리 규칙

서버 데이터(목록, 상세): React Query
UI 흐름 상태(퀴즈 단계, 선택값): Zustand
전역 인증 토큰: Zustand (useAuthStore)
Zustand store는 model/<feature>/ 하위에 위치

⚠️ 6. 기술적 의사결정 (ADR)

ADR-001: Stackflow 채택 (vs React Router / TanStack Router)

항목	내용
결정	Stackflow 사용
이유	모바일 앱 같은 Activity 스택 기반 네비게이션 UX 구현 (push/pop 슬라이드 트랜지션), WebView 내에서도 네이티브 느낌의 화면 전환 필요
대안	React Router v7, TanStack Router
트레이드오프	생태계가 작고 레퍼런스 부족. URL 동기화는 `historySyncPlugin`으로 별도 구성 필요

ADR-002: Ky HTTP 클라이언트 채택 (vs fetch / axios)

항목	내용
결정	Ky 사용
이유	fetch 기반으로 번들 크기 최소화, 훅(beforeRequest / afterResponse)으로 토큰 주입/갱신 처리가 깔끔함
대안	axios, 순수 fetch
트레이드오프	axios 대비 인터셉터 API가 달라 팀 러닝 커브 존재

ADR-003: @webview-bridge 채택 (vs postMessage 직접 구현)

항목	내용
결정	@webview-bridge 라이브러리 사용
이유	postMessage 기반 수동 구현 대비 TypeScript 타입 안전성 확보, Promise 기반 비동기 호출 자동 처리
대안	`window.ReactNativeWebView.postMessage` 직접 구현
트레이드오프	라이브러리 의존성 추가, 내부 직렬화 방식에 종속

ADR-004: OpenAPI TypeScript 자동 생성

항목	내용
결정	`openapi-typescript`로 백엔드 OpenAPI spec → TypeScript 타입 자동 생성
이유	수동 타입 관리 시 API 변경 때마다 누락 위험, 백엔드 스펙과 항상 동기화
명령어	`pnpm generate:api-models`
출력	`src/api/config/api-models.ts`

🗂️ 7. 참고 자료

공식 문서

기술	문서
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

Uh oh!

Frontend Wiki

🧭 Frontend Team Wiki

📌 1. 프로젝트 개요

🎯 1-1 목적

👥 1-2 대상 사용자

⚙️ 1-3 주요 기능

🧑‍💻 2. 기술 스택

🧩 2-1 Web 기본 스택

🧩 2-2 Mobile 기본 스택

🧩 2-3 공통 / 인프라

🏗️ 3. 아키텍처 및 구조

3-1 모노레포 구조

3-2 Web 디렉토리 구조

3-3 Routing (Stackflow)

3-4 상태 관리

3-5 API 통신 방식

🔗 4. 브릿지 / 외부 연동 구조

4-1 Web ↔ Native 구조

4-2 현재 브릿지 인터페이스

4-3 새 네이티브 기능 추가 절차

4-4 딥링크 / 네비게이션 처리

4-5 음성 녹음 (STT) 흐름

📏 5. 코드 규칙 및 컨벤션

5-1 커밋 메시지

5-2 파일 / 컴포넌트 네이밍

5-3 디렉토리 규칙

5-4 스타일링 규칙

5-5 ESLint Import 순서 (강제)

5-6 상태 관리 규칙

⚠️ 6. 기술적 의사결정 (ADR)

ADR-001: Stackflow 채택 (vs React Router / TanStack Router)

ADR-002: Ky HTTP 클라이언트 채택 (vs fetch / axios)

ADR-003: @webview-bridge 채택 (vs postMessage 직접 구현)

ADR-004: OpenAPI TypeScript 자동 생성

🗂️ 7. 참고 자료

공식 문서

서비스 URL

✨ 8. 사용 팁 및 규칙

8-1 개발 시작

8-2 API 타입 재생성

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

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

8-5 협업 주의사항

8-6 Vite 개발 프록시

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

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

개념

이 프로젝트의 구현

학술적 맥락

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

문제

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

학술적 맥락

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

개념

이 프로젝트의 구현

학술적 맥락

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

문제

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

학술적 맥락

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

문제

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

학술적 맥락

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

문제

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

학술적 맥락

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

개념

이 프로젝트의 구현

학술적 맥락

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

개념

이 프로젝트의 적용

학술적 맥락

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

개념

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

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

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