fullstack-mirror-arch

name	fullstack-mirror-arch
description	풀스택 미러 아키텍처 규칙. BE↔FE 1:1 타입 동기화, 레이어 의존 규칙, barrel re-export, API 클라이언트 패턴, 상태관리 분리 규칙을 적용. 풀스택 프로젝트 설계 시 사용.

Fullstack Mirror Architecture (풀스택 미러 아키텍처)

백엔드와 프론트엔드 간 1:1 미러 구조를 유지하기 위한 규칙과 패턴. 기술 스택과 무관한 개념 규칙을 정의하고, 구현 예시는 참고용으로 표기한다.

---

1. 미러 구조 원칙

규칙

• 도메인별 모델/타입 파일을 1:1 대응시킨다
• BE 모델 변경 시 FE 타입을 반드시 동시 수정한다
• 새 도메인 추가 시 양쪽 barrel re-export를 함께 갱신한다
• 도메인 이름(파일명)은 BE/FE 양쪽에서 동일하게 유지한다

구조 매핑

BE: models/{domain}      ↔  FE: types/{domain}        (타입/모델 정의)
BE: api/{domain}/router   ↔  FE: lib/api/{domain}      (API 엔드포인트)
BE: services/{domain}     ↔  (FE에서 직접 대응 없음)   (비즈니스 로직)

예시 (참고)

BE (FastAPI/Pydantic)	FE (Next.js/TypeScript)
models/session.py	types/session.ts
api/session/router.py	lib/api/session.ts
models/schemas.py (barrel)	types/index.ts (barrel)

Django: serializers/{domain}.py, Express: models/{domain}.ts, Spring: dto/{domain}.java 등으로 대체 가능

---

2. Barrel Re-export 패턴

규칙

• BE와 FE 각각 하나의 barrel 파일에서 모든 도메인 모델/타입을 re-export
• 새 도메인 추가 시 barrel 파일에 반드시 추가
• 새 코드에서는 도메인 모듈 직접 import 권장, barrel은 하위 호환용 유지

구조

BE barrel:
  models/schemas.py     → 모든 도메인 모델 re-export + __all__

FE barrel:
  types/index.ts        → 모든 도메인 타입 re-export
  lib/api/endpoints.ts  → 모든 API 클라이언트 re-export

예시 (참고)

// types/index.ts
export * from './common';
export * from './session';
export * from './upload';
export * from './labeling';

# models/schemas.py
from .common import *
from .session import *
from .upload import *
from .labeling import *

---

3. 자동 케이스 변환 패턴

규칙

• BE의 네이밍 컨벤션(snake_case)과 FE의 네이밍 컨벤션(camelCase)을 자동 변환한다
• DB 컬럼명(snake_case) → API 응답(camelCase) → FE 타입(camelCase)
• 수동 변환은 금지 — 반드시 프레임워크/라이브러리의 자동 변환 기능 사용

예시 (참고)

스택	구현 방법
Pydantic (Python)	CamelModel 기반 클래스 + alias_generator=to_camel
Django REST	CamelCaseJSONRenderer / djangorestframework-camel-case
Spring (Java)	@JsonNaming(PropertyNamingStrategies.LowerCamelCaseStrategy.class)
Express (Node)	미들웨어에서 camelCase ↔ snake_case 변환
Go	json:"fieldName" 태그

---

4. Backend 레이어 규칙

의존 방향 (바깥 → 안쪽)

api/ (라우터/컨트롤러)
  ↓ 의존
services/ (비즈니스 로직)
  ↓ 의존
models/ (도메인 모델/스키마)
  ↓ 의존
core/ (설정, DB 클라이언트, 인증)

규칙

• api/: HTTP 요청 수신, 응답 반환만 담당. 비즈니스 로직 금지
• services/: 비즈니스 로직 캡슐화. DB 접근은 여기서 수행
• models/: 순수 데이터 정의. 비즈니스 로직/DB 접근 금지
• core/: 설정(config), DB 클라이언트, 인증 헬퍼. 싱글턴 패턴
• 역방향 의존 금지: models/가 api/를 import하면 안 됨

라우터 등록

• main 파일에서 라우터 등록 순서를 명시적으로 관리
• 새 도메인 라우터 추가 시 등록 순서 문서화

예시 (참고)

스택	api/	services/	models/	core/
FastAPI	APIRouter	서비스 클래스/함수	Pydantic Model	BaseSettings
Express	Router	서비스 모듈	Mongoose/Prisma	config.ts
Django	views.py	services.py	models.py	settings.py
Spring	@Controller	@Service	@Entity/DTO	@Configuration

---

5. Frontend 레이어 규칙

의존 방향 (안쪽 → 바깥쪽)

types/       (순수 타입, 의존 없음)
  ↑ 의존
lib/         (API, 스토어, 훅, 유틸)
  ↑ 의존
components/  (UI 컴포넌트)
  ↑ 의존
app/         (라우트/페이지 엔트리)

규칙

• types/: 순수 타입 정의만. 런타임 코드/import 없음
• lib/: API 클라이언트, 상태 스토어, 커스텀 훅, 유틸. app/이나 components/를 절대 import 금지
• components/: UI 렌더링. lib/, types/ 의존 가능
  • ui/: 도메인 무관 공용 프리미티브 (Button, Modal, Toast 등)
  • domain/: 도메인 특화 재사용 뷰
  • layout/: 앱 셸 (사이드바, 탑바, 네비게이션)
  • providers/: 컨텍스트 래퍼 (Auth, Theme 등)
• app/: 라우트 엔트리. 모든 레이어 의존 가능

Import 규칙

• 절대경로 alias 사용: @/lib/api/session (상대경로 지양)
• 순환 의존 금지

---

6. API 클라이언트 패턴

규칙

• 인증 래퍼 함수로 토큰 주입을 자동화한다 (매 요청마다 수동 토큰 추가 금지)
• 도메인별로 API 클라이언트 파일을 분리한다
• API base URL은 환경변수로 관리한다
• 모든 API 에러는 catch 후 의미 있는 메시지로 throw한다

구조

lib/api/
├── auth-fetch.ts (또는 http-client.ts)   ← 인증 래퍼
├── {domain-1}.ts                          ← 도메인별 API
├── {domain-2}.ts
└── endpoints.ts                           ← barrel re-export

예시 (참고)

// lib/api/auth-fetch.ts (개념)
export async function authFetch(url: string, options?: RequestInit) {
  const token = await getAccessToken(); // 프레임워크별 방법
  return fetch(url, {
    ...options,
    headers: { ...options?.headers, Authorization: `Bearer ${token}` },
  });
}

axios interceptor, ky hooks, ofetch onRequest 등으로도 구현 가능

---

7. 상태관리 패턴

규칙

• 도메인별 독립 스토어로 분리한다 (하나의 거대 스토어 금지)
• 스토어에 UI 컴포넌트 import 금지
• 스토어에 fetch/navigation side effect를 직접 넣지 않기 (훅이나 미들웨어에서 처리)
• 스토어 간 결합은 명확한 인터페이스를 통해서만
• Toast/Modal 같은 UI 상태는 전용 UI 스토어에서 관리 (인라인 생성 금지)

스토어 분류 예시

스토어	역할
ui-store	사이드바, 모달, 토스트, 로딩 상태
auth-store	현재 사용자, 인증 상태
{domain}-store	도메인별 데이터 및 상태

예시 (참고)

스택	구현 방법
Zustand	create<State>() 패턴, 도메인별 파일 분리
Redux Toolkit	createSlice(), 도메인별 slice 분리
Pinia (Vue)	defineStore(), 도메인별 store 분리
Svelte Store	writable(), 도메인별 파일 분리

---

8. BE↔FE 동기화 체크리스트

코드 변경 시 아래 항목을 확인한다:

• BE 모델 필드 추가/변경/삭제 → FE 타입 동시 변경
• 새 도메인 추가 → 양쪽 barrel re-export 갱신
• 새 API 엔드포인트 → FE API 클라이언트 + endpoints barrel 갱신
• enum/상수 값 변경 → BE/FE 양쪽 반영
• 필드명 변경 → 케이스 변환 규칙 확인 (snake↔camel)
• 응답 구조 변경 → FE에서 사용하는 모든 컴포넌트 확인
• 에러 코드 추가 → FE 에러 핸들링에 반영