기술 스택 (버전 고정)

기준 BE v0.19.0 / FE v0.20.0 — 2026-06-04. apps/admin · apps/docs · packages/ 의 실제 의존성과 일치.*

Overview

스택은 baseline 보안과 응답성을 보장하기 위해 버전을 명시 핀 한다. 자유 upgrade 금지 — 변경은 SPEC 승인 필수.

Backend (linkmusic-msa-space-was)

분류	버전	비고
언어	Kotlin 2.x	JVM 21
프레임워크	Spring Boot 3.x	Spring Web · Data JPA · Security · Validation
DB	PostgreSQL 16	Render PG · prod schema 단일
마이그레이션	Flyway	V1~V7 + 후속 (Flyway 9.x)
ORM	Hibernate 6	`@UuidGenerator(style=TIME)` = RFC 4122 v1
JWT	jjwt 0.12.6	HS256 + 단일 secret `JWT_SECRET` (≥64자)
비밀번호	BCrypt strength=12	Spring Security `BCryptPasswordEncoder`
문서	Springdoc OpenAPI 2.x	`/v3/api-docs` + Swagger UI
테스트	JUnit5 + Testcontainers (PG)	`@DataJpaTest` 슬라이스 + `@SpringBootTest` 통합
빌드	Gradle Kotlin DSL	`./gradlew build test ktlintCheck`
배포	Render	branch `main` → auto-deploy. develop = staging (옵션)
코드 스타일	ktlint	`./gradlew ktlintFormat`

Frontend (linkmusic-frontend-space)

분류	버전	비고
Node	`.nvmrc` 20.20.2 (권장) · `engines.node` `>=20.19.0` (최소)	`engine-strict=true`
pnpm	10.33.0	`packageManager` field 핀
TypeScript	5.9.3	`strict` · `noUncheckedIndexedAccess` · `verbatimModuleSyntax=false`
Next.js (admin)	16.2.6	App Router · Turbopack
Next.js (docs)	15.5.18	Nextra v3 호환 (자체 판단점, SPEC #014 §8)
React	19.2.6	RSC + use client 분기
Tailwind CSS	4.3.0	v4 — `@import "tailwindcss"`
Nextra	3.3.1	docs sub-app · MDX · 자동 sidebar
iron-session	8.0.4	BFF sealed cookie · `lm_session`
react-query	5.x	client cache + invalidation
Zod	3.25	form validation · backend DTO 검증
orval	7.13.0	OpenAPI → typed client (`packages/api-client`)
lucide-react	0.577.0	icon set
Radix UI	dialog · dropdown · label · slot · switch · toast	accessibility primitive
검증	vitest 3.2 · Testing Library 16 · Playwright	단위 + e2e
폰트	Pretendard Variable 1.3.9	`apps/admin/src/app/globals.css` 최상단 @import
ESLint	10.4.0 (apps · `packages/ui`) · 9.39.4 (`packages/config` · `api-client`)	`packages/config/eslint`

Monorepo 구조

linkmusic-frontend-space/
├── apps/
│   ├── admin/       Surface 10 (운영사 백오피스). Next 16 + App Router
│   └── docs/        이 문서. Next 15 + Nextra v3
├── packages/
│   ├── ui/          OKLCH v2 토큰 + shells + atoms (source-only, no build)
│   ├── api-client/  orval generated · OpenAPI 단일 소스
│   └── config/      eslint · tsconfig (base/next/react-lib) · tailwind preset
├── pnpm-workspace.yaml
├── tsconfig.base.json
└── .npmrc           engine-strict=true · auto-install-peers=false

Constraints — 버전 핀 정책

Node 버전: .nvmrc + engines.node 최소 호환 patch 버전 (예 20.20.2). major-only 금지. Vercel 의 monorepo sub-app Root Directory 도 동일 (apps/admin·apps/docs 각자에 .nvmrc).
pnpm 버전: packageManager field 로 강제.
자유 upgrade 금지: 모든 dependency upgrade 는 SPEC PR 로.

Roadmap

Next 16 일관화 (docs 도 16 으로) — Nextra v4 의 Layout schema 버그가 fix 되면.
Storybook 도입 — packages/ui atoms 시각 카탈로그 (후속 SPEC).

References

linkmusic-frontend-space/apps/admin/package.json
linkmusic-frontend-space/apps/docs/package.json
linkmusic-msa-space-was/build.gradle.kts
.claude/rules/frontend.md · backend.md

Surface 10 · 11 · 12 용어