Framework: Next.js 14.2.28 (App Router, reactStrictMode: false)
Language: JavaScript + TypeScript (allowJs: true, strict: false)
Canvas: Fabric.js 5.5.2 (커스텀 확장 — src/components/fabric/, src/util/fabric-extensions.js)
State: Recoil 0.7.7 (도메인별 atom — src/store/)
Session/Auth: iron-session 8 (쿠키 기반)
Data fetching: axios 1.7 + SWR 2.3
i18n: next-international (ja / ko — src/locales/)
UI: react-responsive-modal, react-select, react-datepicker, ag-grid-react, sweetalert2, react-icons, framer-motion, tailwindcss + sass
PDF/이미지: jimp, sharp, convertapi
DB 클라이언트: mssql (서버 사이드), sqlite/sqlite3 (로컬 캐시)
AWS: @aws-sdk/client-s3
Geo: @turf/turf, mathjs, big.js
Path alias: @/* → ./src/*

Getting Started

yarn install
yarn dev           # .env.localhost 사용, http://localhost:3000

.env.localhost 가 워크트리에 있어야 한다(실제 시크릿 포함). 새 머신에서는 팀에서 받아 배치할 것.

HTTPS 가 필요하면 ./certificates/key.pem, cert.pem 을 준비한 뒤 yarn serve (HTTP 3000 + HTTPS 3001).

Scripts

모든 스크립트는 env-cmd 로 .env.<mode> 를 주입한다. 테스트 러너는 별도로 wiring 되어 있지 않다.

Script	설명
`yarn dev`	로컬 개발 (`.env.localhost`)
`yarn dev:log`	dev + stdout 을 `dev.log` 로 미러링
`yarn dev:local-api`	API 를 `http://localhost:8080` 으로 고정
`yarn local:dev`	`.env.local.dev` 모드 (로컬에서 dev 서버 환경 흉내)
`yarn build`	프로덕션 빌드 (`.env.production`)
`yarn build:dev`	dev 빌드 (`.env.development`)
`yarn build:local.dev`	local.dev 빌드
`yarn start:cluster1`	`next start -p 5000` (PM2 prd1)
`yarn start:cluster2`	`next start -p 5001` (PM2 prd2)
`yarn start:dev`	`next start -p 5010` (PM2 dev)
`yarn serve`	`server.js` — HTTP 3000 + HTTPS 3001 (certificates 필요)
`yarn lint`	`next lint` — 완료 전 필수

Environment Variables

각 모드별 .env.<mode> 파일에 정의. 키 목록(전체 값은 절대 공개 채널에 노출 금지):

Key	용도
`NEXT_PUBLIC_RUN_MODE`	`src/config/config.export.js` 가 어떤 config 를 로드할지 결정 (`local` / `local.dev` / `development` / `production`)
`NEXT_PUBLIC_API_SERVER_PATH`	백엔드 API base URL
`NEXT_PUBLIC_HOST_URL`	프론트엔드 호스트 (자기 자신)
`NEXT_PUBLIC_API_HOST_URL`	API 호스트
`SESSION_SECRET`	iron-session 쿠키 서명 키 — 32 byte 이상 필수
`NEXT_PUBLIC_CONVERTER_DWG_API_URL`	DWG → SVG 변환 서비스
`NEXT_PUBLIC_CONVERTER_DXF_API_URL`	DXF → SVG 변환 서비스
`NEXT_PUBLIC_Q_ORDER_AUTO_LOGIN_URL`	Q-Order autoLogin 진입점
`NEXT_PUBLIC_Q_MUSUBI_AUTO_LOGIN_URL`	Q-Musubi autoLogin 진입점
`NEXT_PUBLIC_AWS_S3_BASE_URL`	S3 정적 자산 base URL
`NEXT_PUBLIC_ENABLE_LOGGING`	`true` 일 때만 `src/util/logger.js` 와 `debugCapture.js` 가 실제로 출력
`AWS_REGION`, `AMPLIFY_BUCKET`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `S3_PROFILE`	S3 업로드 (서버 전용 — `.env.localhost` 등에만)

.env.* 자체는 git 추적 대상이고 시크릿을 포함한다. 머신별 오버라이드는 .env.*.local (gitignore 됨) 에 둘 것.

Routes (App Router)

src/app/
  api/                  # Next.js Route Handlers (S3, debug, 이미지 등)
  community/            # 커뮤니티
  floor-plan/           # 도면 캔버스 — 본 앱의 핵심
    estimate/           # 견적 화면
    simulator/          # 시뮬레이터
    page.jsx            # 도면 에디터 진입점
  join/                 # 회원가입
  login/                # 로그인
  management/           # 관리자
    image/              # 이미지 관리
    stuff/              # 자재/제품 관리
  layout.js             # 루트 레이아웃 — 세션 체크 후 비로그인 시 /login 으로 리다이렉트
  page.js               # 홈

세션이 없는 상태로 /login 외 경로 접근 시 루트 레이아웃이 강제 리다이렉트한다. src/middleware.js 는 x-pathname 헤더를 주입해 루트 레이아웃이 현재 경로에 따라 분기할 수 있게 한다.

Source Layout

src/
  app/                  # App Router 라우트 + 글로벌 Provider 들
  common/               # 공용 유틸 / 모듈
  components/           # 도메인별 UI 컴포넌트
    fabric/             # QLine, QPolygon — Fabric.js 확장 클래스
    floor-plan/         # 캔버스 툴 모달 (roofShape, placementShape, panelBatch …)
    estimate/, management/, simulator/, ui/, …
  config/               # 모드별 런타임 config (config.export.js 가 분기)
  hooks/                # 도메인별 hook (roofcover, surface, module, object, option …)
  lib/                  # 세션, 캔버스 저장/복원, 파일/이미지 액션
  locales/              # ja.json, ko.json
  middleware.js         # x-pathname 주입
  models/               # 도메인 모델
  store/                # Recoil atom (canvas, roof, estimate, modal, menu, setting …)
  styles/               # sass entry (includePaths)
  util/                 # logger, debugCapture, fabric-extensions, canvas-util …

Deployment (PM2)

*.ecosystem.config.js + startscript*.js 조합으로 실행. startscript 가 child_process.exec 로 yarn 스크립트를 호출한다.

File	용도	Port
`ecosystem.config.js`	프로덕션 클러스터 (instances: 2)	—
`prd1.ecosystem.config.js`	프로덕션 #1 (fork)	5000
`prd2.ecosystem.config.js`	프로덕션 #2 (fork)	5001
`dev.ecosystem.config.js`	dev 서버	5010
`dev.local.ecosystem.config.js`	local.dev 모드 dev 서버	—

Conventions

상세 사항은 CLAUDE.md 와 docs/Qcast coding convention.pdf, docs/Qcast development guilde.pdf 참조. 핵심만 옮기면:

Prettier: single quote, no semicolons, tabWidth 2, printWidth 150, trailingComma all. 완료 전 yarn lint.
No raw alert() — useSwal / useMessage + sweetalert2 만 사용. docs/메세지 처리 가이드.pdf.
Path alias @/... 우선, ../../.. 체인 지양.
로깅 — console.log 직접 사용 금지. src/util/logger.js 사용 (NEXT_PUBLIC_ENABLE_LOGGING=true 일 때만 출력).
Commit message — .gitmessage.txt 형식 ([일감번호] : [제목]) 또는 최근 브랜치 스타일 [2204] <제목> — <상세>. Prefix 만 영문, 본문은 한국어.
i18n — UI 텍스트는 src/locales/{ja,ko}.json 에 키 추가 후 useI18n 으로 접근.

Documentation

File	내용
`CLAUDE.md`	에이전트(Claude / Codex) 작업 규약 + 비명시적 패턴 · gotcha
`docs/Canvas Status.md`	캔버스 기능 상태 · 타겟별 컨텍스트 메뉴 인벤토리
`docs/Qcast coding convention.pdf`	전체 코딩 컨벤션
`docs/Qcast development guilde.pdf`	개발 가이드
`docs/메세지 처리 가이드.pdf`	모달 / 알럿 메시지 규칙
`docs/git commit message Convention.pdf`	커밋 메시지 컨벤션
`docs/Nextjs 14 컴포넌트에 대해서….pdf`	App Router 서버/클라이언트 컴포넌트 노트
`docs/dictionary.txt`	도메인 용어집 (지붕 / 패널 용어 JP/KR)
`docs/diagrams/`	아키텍처 다이어그램
`.agents/skills/{next-best-practices,vercel-react-best-practices}/`	Next/React 패턴 결정 시 우선 참조 (총 95개 룰 .md)

Troubleshooting

빌드 시 Module not found: fs / canvas — next.config.mjs 의 webpack externals 에 추가. node-only deps 는 클라이언트 번들에서 제외해야 한다.
세션이 즉시 풀림 — SESSION_SECRET 이 32 byte 미만이면 iron-session 이 거부한다. .env.<mode> 확인.
플랜 로드 시 InvalidStateError — src/lib/canvas.js / src/util/canvas-util.js 의 3-layer guard (entry/cache/save) 와 SizeSetting 의 0-area guard 로 차단된다. 가드 약화 금지 — 손상된 플랜은 정상 데이터로 교체할 것.
App Router 캐시로 인한 stale plan/estimate — next.config.mjs 의 experimental.staleTimes 가 의도적으로 모두 0. 다시 켜지 말 것.
HTTPS dev 실패 — ./certificates/key.pem, cert.pem 부재. gitignore 대상이라 팀에서 받아 배치해야 한다.
dev 서버에서만 한글/일본어 폰트 깨짐 — next/font 캐시 문제일 가능성. .next/ 삭제 후 재시작.