군산CC SaaS

멀티테넌트 SaaS 골프장 ERP

Frontend
Engineering Portfolio

골프장 운영 SaaS의 관리자용 ERP(erp-web)를 중심으로 멀티테넌트 아키텍처·예약/티슬롯 도메인·3-Layer 디자인 시스템을 구현했습니다. 고객용 golf-web과 golf-mobile(WebView 셸)의 핵심 플로우 일부에도 직접 참여했습니다.

Period

2026.02 — 2026.03

Stack

Next.js 15 · React 19 · TS

Role

Frontend Engineer · erp-web 중심

Monorepo

10 Apps · 9 Libs

3

담당 앱

erp-web · golf-web · golf-mobile

10

구현 도메인

예약·티슬롯·매출·마감 등 erp-web 전 도메인

3-Layer

디자인 시스템

Primitives → Composites → Features

100%

End-to-End 타입 안전

Zod 단일 소스 (FE↔BE 계약)

10앱·9libs

모노레포 규모

Turborepo + pnpm Workspaces

5종

검증 게이트

lint · build · a11y · 단위 · E2E

Architecture

모노레포 FE 중심 구조

Frontend Apps · Shared Contracts · Monorepo 오케스트레이션을 중심으로, 실시간·백엔드는 FE 관점 컨텍스트로 표기했습니다.

Frontend Apps

관리자·직원·고객 3개 사용자 군을 별도 앱으로 분리해 도메인별 UX를 최적화. App Router 서버 컴포넌트로 초기 로딩을, 공유 라이브러리로 비즈니스 로직 재사용을 확보했습니다.

erp-web · Next.js 15 (담당)golf-web · Next.js (일부 담당)golf-mobile · Expo (담당)erp-admin-web / erp-lite-web (참고)

Shared Libraries (FE↔BE 계약)

Zod 스키마를 단일 소스로 두고 프론트·백 양쪽에서 import — 런타임 검증과 컴파일 타임 타입을 한 곳에서 관리해 계약 불일치를 원천 차단했습니다.

shared-types · Zod 스키마client-api · 타입 안전 HTTP 래퍼api-contracts · 엔드포인트 계약

Monorepo Orchestration

10개 앱·9개 라이브러리의 빌드·린트·테스트를 캐시 + 병렬로 오케스트레이션. 변경 패키지만 빌드해 CI 시간을 단축했습니다.

Turborepo · 캐싱·의존 그래프pnpm Workspacestsconfig.base.json · 경로 별칭

Realtime · Device Bridge

Context

현장 키오스크·프린터·카드리더를 Electron 브릿지가 추상화하고, Socket.io로 ERP와 양방향 통신. 네트워크 불안정 시 큐 버퍼링·자동 재연결로 주문 누락을 방지했습니다.

Socket.io · 키오스크 ↔ ERPdevice-bridge-desktop · Electron

Backend (참고)

Context

동일 모노레포에서 운영되어 shared-types·api-contracts를 통해 FE와 계약을 공유합니다. (구현 범위 외 — FE 관점 컨텍스트로 표시)

erp-api · Express + Kyselyerp-gateway-api · 인증·라우팅
핵심 설계 포인트: Turborepo + pnpm으로 앱·라이브러리 경계를 분리하고, Zod 기반 shared-types · client-api로 프론트-백 계약을 한 곳에서 관리.
Tech Stack

기술 스택 & 선택 이유

각 기술을 왜 선택했고, 어떤 문제를 해결했는지 중심으로 정리.

Next.js

v15.5

App Router 서버 컴포넌트로 ERP 초기 렌더링 비용을 줄이고, Turbopack으로 대규모 모노레포 개발 서버 속도를 확보.

React

v19.2

Suspense + Concurrent 렌더링으로 대시보드의 비동기 로딩 UX를 개선. 트랜지션으로 테넌트 전환 시 화면 깜빡임 제거.

TypeScript

v5.x

FE·BE·라이브러리 전 구간 End-to-End 타입 안전성. shared-types Zod로 런타임 검증까지 단일 소스로 관리.

18개 핵심 라이브러리 · 6개 카테고리

Deep Dive

기술 의사결정 Deep Dive

구현 중 마주친 문제와 그에 따른 트레이드오프·해결을 정리했습니다.

tenantId 데이터 격리Middleware 인증RBAC 메뉴TanStack Query 캐시 격리

핵심 구현

  • 서버 컴포넌트로 공통 셸을 렌더하고, 개인화 데이터는 UserDataLoader가 비동기로 채우는 패턴으로 레이아웃 블로킹 제거
  • 모든 API 호출에 client-api 인터셉터가 tenantId를 자동 주입 — 도메인 코드에서 테넌트 누락 불가
  • queryKey 앞단에 tenantId를 묶어 테넌트 전환 시 캐시 자동 격리
  • 역할(관리자·직원·캐디·입점사)별 메뉴를 라우트 메타 + 훅으로 필터링

아키텍처

Next.js Middleware · 인증·테넌트 라우팅서버 컴포넌트 공통 셸UserDataLoader · 클라이언트 비동기 부트스트랩QueryClient 캐시 격리 (tenantId queryKey)RBAC 메뉴 필터링 훅

문제 → 해결

서버 컴포넌트에서 사용자 정보를 동기 조회 시 레이아웃 블로킹

→ 레이아웃은 서버 컴포넌트로 유지하되 개인화 데이터를 클라이언트 로더로 분리 → 초기 셸 페인트와 데이터 페치를 병렬화

테넌트 전환 시 이전 데이터가 UI에 잔존하는 위험

→ queryKey에 tenantId를 1급 시민으로 포함 + 전환 감지 시 invalidateQueries로 명시적 무효화

결과

지원 역할4종
데이터 격리100% tenantId
레이아웃 블로킹0건
Monorepo

모노레포 구조와 담당 범위

10개 앱 · 9개 공유 라이브러리. 본인 담당·기여 범위를 명확히 표시.

담당 / 기여 (3 Apps)

Ownederp-webFrontend

메인 ERP 프론트 (예약·매출·운영)

Next.js 15 · React 19

Ownedgolf-mobileMobile

고객용 모바일 WebView 셸

Expo 53 · React Native 0.79

Contributedgolf-webFrontend

고객용 예약·코스안내 웹

Next.js · React 19

팀 내 다른 앱 (참고)

erp-admin-webFrontend

관리자 대시보드

erp-lite-webFrontend

경량 ERP (대시보드·예약)

score-mobileMobile

스코어 기록 모바일

erp-kiosk-desktopDesktop

현장 키오스크 (체크인·결제)

device-bridge-desktopDesktop

하드웨어 브릿지 (프린터·카드리더)

erp-apiBackend

메인 API 서버

erp-gateway-apiBackend

게이트웨이 (인증·라우팅)

공유 라이브러리 (9 Libs)

shared-types

공용 타입 + Zod 스키마

client-api

타입 안전 HTTP 래퍼

api-contracts

API 계약 정의

shared-utils

FE·BE 공용 유틸

shared-eslint

공유 ESLint 설정

server-core

서버 공통 미들웨어·에러

server-kysely

Kysely DB 클라이언트

server-redis

Redis 캐시·세션

server-utils

서버 유틸 함수

Engineering Quality

품질 보장 프로세스

스펙 합의 → 구현 → 자동 검증 → 리뷰 가능한 PR. 변경의 근거와 트레이드오프를 기록 가능한 형태로 남깁니다.

Spec-First Development

기능별 스펙 문서로 요구사항·엣지케이스·검증 기준을 사전 합의 후 구현 진입

Contract-Driven FE/BE

shared-types Zod 스키마를 단일 소스로 두고 양쪽이 import — 계약 불일치 차단

Verification Gate

PR마다 format · lint · build · Storybook a11y · 핵심 시나리오 E2E 자동 검증

Reviewable PR Template

배경/목표/구현 요약/검증 결과/리스크/연관 스펙 6개 섹션으로 리뷰 비용 최소화

표준 워크플로우

Step 1

스펙 작성

요구사항·엣지케이스·검증 기준을 specs/ 문서로 합의

Step 2

계획 수립

단계별 작업 리스트로 범위·순서·의존성 결정

Step 3

컨텍스트 정리

도메인 README로 기존 결정·용어·연관 모듈 파악

Step 4

구현

레이어드 아키텍처에 따라 순차 구현 (Primitives → Features)

Step 5

검증

format · lint · build · 시나리오 테스트 통과 확인

Step 6

PR 정리

6개 섹션 PR 본문으로 구현 근거와 트레이드오프 기록

리뷰 가능한 PR 템플릿

1배경 / 문제
2목표와 범위
3구현 요약
4검증 결과
5리스크 / 후속 작업
6연관 스펙

자동 검증 게이트

format · prettier
lint · eslint
build · type-check
a11y · storybook
unit · vitest
e2e · playwright

PR마다 자동 통과해야 머지 가능 — 회귀를 사람 검토 이전 단계에서 차단합니다.

Summary

담당 범위 한눈에 보기

2026.02 — 2026.03 · Frontend Engineer · erp-web 중심

OWNED
erp-web

메인 ERP 프론트 · Owned

Next.js 15 · React 19

예약·티슬롯·매출·마감 등 10개 도메인. 멀티테넌트 아키텍처와 3-Layer 디자인 시스템 직접 설계·구현.

OWNED
golf-mobile

WebView 네이티브 셸 · Owned

Expo 53 · React Native 0.79

@webview-bridge 타입 안전 브릿지, 딥링크, 오프라인 자동 복구, Android 백버튼 정책.

CONTRIBUTED
golf-web

고객용 예약 웹 · Contributed

Next.js · React 19

예약 멀티스텝 플로우 일부 구간, 골프룸 커머스 페이지, 마이페이지 자기 서비스 기능 참여.

핵심 역량

Monorepo 운영 경험

10앱·9libs Turborepo 환경에서 빌드 캐시·의존 그래프·공유 계약을 활용한 협업 경험

End-to-End 타입 안전

Zod 스키마를 단일 소스로 FE·BE 양쪽에서 import — 런타임 검증과 컴파일 타임 타입 일원화

확장 가능한 FE 아키텍처

App Router 서버 컴포넌트, 멀티테넌시, 가상 스크롤, WebView 브릿지 등 도메인 난이도 높은 구현

Project Snapshot

Project

군산CC ERP

Period

2026.02 — 2026.03

Role

Frontend Engineer · erp-web 중심

Stack

Next.js 15/16 · React 19 · RN · TypeScript

Keywords

Multi-TenantMonorepoWebView BridgeZod ContractTanStack QueryTiptapSocket.ioDesign System
GitHubContact