🚀 Next.js 15장: 프로젝트 아키텍처 & 폴더 구조 — 실무에서 살아남는 설계

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🏗️ 비유로 먼저 이해하기
• 🗂️ 실무 폴더 구조의 정석 🟢
• 🧩 계층별 역할과 규칙 — 무엇이 어디에 있어야 하는가 🟡
• 🔒 DAL (Data Access Layer) 패턴 🟡
• 📦 컴포넌트 분류: ui vs features 🟡
• 🚫 의존성 방향의 규칙 — 순환 참조 방지 🔴
• 💥 에러 해결 카탈로그
• 🏁 이번에 배운 내용 총정리
• 📝 마무리 퀴즈
• 🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 15분 (전체) / 핵심 파트만: 8분

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 영철(신입): "컴포넌트 파일이 50개 넘어가니까 어디에 뭘 넣어야 할지 모르겠어요. 공통 버튼 컴포넌트도 만들었는데 어디 폴더에 넣어야 하고, API 호출하는 함수는 어디에 있어야 하고, 유틸 함수는 또 어디에... utils/components/helpers 폴더가 뒤섞여서 어디서 뭘 찾아야 할지 머릿속이 혼돈이에요."
• 영호(리드): "영철 님, 폴더 이름이 아니라 '이 파일이 하는 일'로 분류해야 해요. /lib은 '서버에서만 실행되는 핵심 비즈니스 로직', /components/ui는 '도메인을 모르는 순수 UI', /components/features는 '비즈니스를 아는 UI'. 이 세 가지만 지켜도 50개가 1000개 돼도 찾을 수 있어요."

🗺️ 이 문서의 흐름
실무 폴더 기준 구조 → 계층별 역할 규칙 → DAL 패턴 → 컴포넌트 분류 → 의존성 방향

🎯 이 문서를 다 읽으면 할 수 있는 것

• 실무에서 바로 쓸 수 있는 Next.js 프로젝트 폴더 구조를 설계할 수 있다
• 새 파일을 만들 때 어느 폴더에 넣어야 하는지 바로 판단할 수 있다
• DAL 패턴으로 데이터 접근 로직을 안전하게 분리할 수 있다

🤔 왜 알아야 하는가

프로젝트가 커질수록 폴더 구조는 점점 중요해져. 잘못된 구조로 시작하면:

• 같은 파일을 두 명이 동시에 수정하는 충돌이 빈번해짐
• 어디에 뭐가 있는지 몰라서 매번 전체 검색
• 클라이언트와 서버 코드가 뒤섞여 보안 취약점 발생 (서버 비밀키가 클라이언트 번들에!)
• 순환 참조로 빌드 오류 발생

"처음에 대충 만들고 나중에 정리하자"는 생각은 프로젝트가 클수록 기술 부채로 돌아와. 지금 올바른 구조로 시작하는 게 나중에 리팩토링 3번 하는 것보다 빠르다.

🏗️ 비유로 먼저 이해하기

🧒 5살에게 설명한다면?
도서관을 생각해봐. 책을 그냥 아무 데나 꽂으면 나중에 찾을 수 없어.
인문학, 과학, 소설처럼 분류가 있어야 해.

프로젝트 폴더도 마찬가지야. "이 코드가 하는 일"에 따라 분류하면 어디에 있을지 바로 알 수 있어.
lib은 백과사전 구역(서버 핵심 로직), components/ui는 잡지 구역(순수 UI), app은 열람실(라우팅).

🗂️ 실무 폴더 구조의 정석 🟢

🎯 이 섹션을 읽고 나면:

• 2026년 Next.js 실무에서 권장하는 폴더 구조를 이해하고 바로 적용할 수 있다

my-app/
├── app/                          # 라우팅 전용 — 최대한 얇게 유지
│   ├── (auth)/                   # 라우트 그룹 (URL에 영향 없음)
│   │   ├── login/page.tsx
│   │   └── signup/page.tsx
│   ├── (dashboard)/
│   │   ├── layout.tsx            # 대시보드 공통 레이아웃
│   │   ├── page.tsx
│   │   └── settings/page.tsx
│   ├── posts/
│   │   ├── page.tsx
│   │   └── [id]/
│   │       ├── page.tsx
│   │       └── opengraph-image.tsx
│   ├── api/                      # Route Handlers
│   │   ├── posts/route.ts
│   │   └── webhooks/stripe/route.ts
│   ├── layout.tsx                # 루트 레이아웃
│   └── globals.css
│
├── components/
│   ├── ui/                       # 도메인 모르는 순수 UI 원자 단위
│   │   ├── Button.tsx
│   │   ├── Input.tsx
│   │   ├── Modal.tsx
│   │   └── Badge.tsx
│   └── features/                 # 비즈니스 로직을 아는 도메인 컴포넌트
│       ├── auth/
│       │   ├── LoginForm.tsx
│       │   └── SignupForm.tsx
│       └── posts/
│           ├── PostCard.tsx
│           ├── PostList.tsx
│           └── PostEditor.tsx
│
├── lib/                          # 서버에서만 실행되는 핵심 비즈니스 로직
│   ├── dal.ts                    # Data Access Layer (DB 접근 + 인증 검증)
│   ├── db.ts                     # DB 클라이언트 (Prisma, Drizzle 등)
│   ├── auth.ts                   # 세션 생성/검증 함수
│   ├── actions/                  # Server Actions 모음
│   │   ├── post.actions.ts
│   │   └── auth.actions.ts
│   └── schemas/                  # Zod 유효성 검사 스키마
│       ├── post.schema.ts
│       └── auth.schema.ts
│
├── hooks/                        # 클라이언트 전용 커스텀 훅
│   ├── useAuth.ts
│   └── useInfiniteScroll.ts
│
├── types/                        # TypeScript 타입 정의
│   ├── post.types.ts
│   └── user.types.ts
│
├── public/                       # 정적 파일 (이미지, 폰트 등)
│   └── fonts/
│
└── middleware.ts                 # Edge Middleware (프로젝트 루트)

🧩 계층별 역할과 규칙 — 무엇이 어디에 있어야 하는가 🟡

🎯 이 섹션을 읽고 나면:

• 각 폴더의 역할을 한 줄로 설명할 수 있다
• 새 파일을 만들 때 어느 폴더에 넣어야 할지 즉시 판단할 수 있다

판단 기준: 이 코드가 어디서 실행되고, 무엇을 아는가?

app/ 폴더는 얇게 유지해야 해:

// ❌ 영철이의 비대한 page.tsx — 비즈니스 로직이 page에 직접
// app/posts/page.tsx
export default async function PostsPage() {
  // 이런 로직이 page.tsx에 있으면 안 돼
  const session = await cookies().get('session')
  const user = await prisma.user.findUnique({ where: { sessionId: session } })
  const posts = await prisma.post.findMany({ where: { authorId: user.id } })
  // ...
}
 
// ✅ 영호가 권장하는 패턴 — page는 조합만, 로직은 lib/dal.ts에
// app/posts/page.tsx
import { getMyPosts } from '@/lib/dal'
 
export default async function PostsPage() {
  const posts = await getMyPosts()   // 인증 + DB 조회 + 권한 체크가 dal에서 처리됨
  return <PostList posts={posts} />
}

💡 한 줄로 기억하기
app/ 폴더는 "레고 조립 설명서"야. 블록을 만드는 공장(lib, components)과 조립하는 사람(app)은 달라야 해.

🔒 DAL (Data Access Layer) 패턴 🟡

🎯 이 섹션을 읽고 나면:

• DAL이 왜 필요한지 설명할 수 있다
• lib/dal.ts에 인증 + 데이터 접근을 결합한 안전한 함수를 작성할 수 있다

📖 용어: DAL (Data Access Layer) — 데이터베이스 접근 로직을 한 곳에 모아둔 계층이야. 페이지나 컴포넌트가 직접 DB를 건드리지 않고, 반드시 DAL을 통하도록 해.

DAL이 없으면 어떤 일이 생기나:

// ❌ DAL 없는 세계 — 모든 page.tsx가 직접 DB에 접근
// app/posts/[id]/page.tsx
const post = await prisma.post.findUnique({ where: { id } })
// 여기서 실수로 권한 체크를 빠뜨리면? 다른 사람 게시글을 누구나 볼 수 있는 보안 구멍!
 
// app/posts/page.tsx에서도 또 prisma 직접 호출...
// app/dashboard/page.tsx에서도 또...
// 권한 체크 로직이 20군데에 흩어져 있으면 하나라도 빠뜨릴 수 있어

// ✅ DAL 패턴 — lib/dal.ts
import 'server-only'  // 이 파일이 클라이언트 번들에 절대 포함되지 않도록 강제
import { cookies } from 'next/headers'
import { decrypt } from '@/lib/auth'
import { db } from '@/lib/db'
 
// 세션 검증 함수 — DAL의 모든 함수는 이걸 먼저 호출해야 해
export async function verifySession() {
  const cookieStore = await cookies()
  const sessionCookie = cookieStore.get('session')?.value
 
  if (!sessionCookie) return null
 
  const session = await decrypt(sessionCookie)
  if (!session?.userId) return null
 
  return session
}
 
// 게시글 목록 — 세션 검증 포함
export async function getMyPosts() {
  const session = await verifySession()
  if (!session) throw new Error('로그인이 필요해요')
 
  return db.post.findMany({
    where: { authorId: session.userId },
    orderBy: { createdAt: 'desc' },
  })
}
 
// 게시글 상세 — 작성자 또는 공개 게시글만 접근 가능
export async function getPost(id: string) {
  const session = await verifySession()
 
  const post = await db.post.findUnique({ where: { id } })
  if (!post) throw new Error('게시글을 찾을 수 없어요')
 
  // 비공개 게시글은 작성자만 볼 수 있어
  if (post.isPrivate && post.authorId !== session?.userId) {
    throw new Error('접근 권한이 없어요')
  }
 
  // DTO 패턴: 민감한 필드(내부 ID, 비밀 등) 제거하고 반환
  return {
    id: post.id,
    title: post.title,
    content: post.content,
    createdAt: post.createdAt,
    // authorInternalId: post.internalId  ← 이런 민감 데이터는 제외
  }
}

💡 한 줄로 기억하기
DAL은 "DB로 가는 유일한 문"이야. 모든 데이터 접근은 이 문을 통해야 해. 문 앞에 항상 경비원(세션 검증)이 서 있어.

📦 컴포넌트 분류: ui vs features 🟡

components/ui/ — "도메인을 모르는 순수 UI"

// components/ui/Button.tsx
// ✅ 영수 커뮤니티를 "전혀 모른다"는 게 핵심
// variant, size, onClick만 있고 "게시글", "유저", "댓글" 같은 개념이 전혀 없음
 
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'danger'
  size?: 'sm' | 'md' | 'lg'
  isLoading?: boolean
  children: React.ReactNode
  onClick?: () => void
}
 
export function Button({ variant = 'primary', size = 'md', ...props }: ButtonProps) {
  return <button className={`btn btn-${variant} btn-${size}`} {...props} />
}

components/features/ — "비즈니스를 아는 도메인 컴포넌트"

// components/features/posts/PostCard.tsx
// ✅ "게시글"이라는 도메인을 알고 있음
// PostType, 좋아요, 댓글 수, 작성자 같은 비즈니스 개념이 포함됨
 
import { Button } from '@/components/ui/Button'  // ui 컴포넌트 사용 가능
import type { Post } from '@/types/post.types'
 
interface PostCardProps {
  post: Post
  onLike: (postId: string) => void
}
 
export function PostCard({ post, onLike }: PostCardProps) {
  return (
    <div className="post-card">
      <h3>{post.title}</h3>
      <span>{post.author.name}</span>
      <Button variant="secondary" onClick={() => onLike(post.id)}>
        좋아요 {post.likeCount}
      </Button>
    </div>
  )
}

🚫 의존성 방향의 규칙 — 순환 참조 방지 🔴

🎯 이 섹션을 읽고 나면:

• 올바른 의존성 방향(app → components → lib)을 이해하고 위반 케이스를 탐지할 수 있다

올바른 의존성 방향 (단방향, 하향):

app/               → (사용) components/, lib/, hooks/
components/features → (사용) components/ui/, hooks/, types/
components/ui/     → (사용) types/
lib/               → (사용) types/, (외부 패키지)
hooks/             → (사용) types/, (React 훅)

❌ 절대 금지 — 역방향 참조:

lib/ → components/   (서버 로직이 UI 컴포넌트를 import? 말이 안 돼)
components/ui/ → components/features/  (ui가 도메인을 알게 되는 순간 재사용 불가)

순환 참조 실제 에러 예시:

// ❌ 순환 참조 지옥
// components/features/PostList.tsx
import { getMyPosts } from '@/lib/dal'  // features가 lib을 import → 나쁘진 않음
 
// lib/dal.ts
import { PostCard } from '@/components/features/posts/PostCard'  // ← 이건 금지!
// lib(서버 로직)이 UI 컴포넌트를 import하면 클라이언트/서버 경계가 무너짐

server-only 패키지로 실수 방지:

// lib/dal.ts 최상단에 추가
import 'server-only'
// 이 파일이 클라이언트 컴포넌트에서 import되면 빌드 에러를 내줘
// 실수로 서버 비밀이 클라이언트 번들에 들어가는 걸 방지

💥 에러 해결 카탈로그

❌ You're importing a component that needs... only works in a Client Component

원인: lib/ 안의 서버 전용 함수를 클라이언트 컴포넌트에서 import.

해결책: 서버 로직을 서버 컴포넌트에서만 호출하고, 결과를 props로 클라이언트 컴포넌트에 전달해.

❌ Module not found — tsconfig paths가 안 작동

원인: @/ 경로 별칭이 설정되지 않음.

해결책:

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

🏁 이번에 배운 내용 총정리

📋 파일 배치 결정 기준

⚠️ 절대 하지 말 것

📝 마무리 퀴즈

Q1. 로그인 사용자의 게시글 목록을 DB에서 가져오는 함수를 어디에 두는 것이 맞는가?

• A) app/posts/page.tsx 안에 inline으로
• B) components/features/posts/PostList.tsx 안에
• C) lib/dal.ts 안에 export 함수로
• D) hooks/usePosts.ts 안에

✅ 정답: C

오답 해설:

• A — page는 얇게 유지. 비즈니스 로직 포함 금지
• B — features 컴포넌트는 UI 담당. DB 직접 접근은 서버 전용 계층에서
• D — hooks는 클라이언트 전용. DB 접근 불가

📌 핵심 기억법: "DB 건드리는 건 무조건 lib/."

Q2. components/ui/Button.tsx에서 import하면 안 되는 것은?

• A) React, ReactNode
• B) CSS 모듈 파일
• C) @/types/button.types.ts
• D) @/components/features/posts/PostCard.tsx

✅ 정답: D

해설: ui 컴포넌트는 도메인 컴포넌트(features)를 알면 안 돼. 재사용성이 사라지고 의존성이 엉키기 시작해.

📌 핵심 기억법: ui → features 방향 import는 금지. ui는 항상 "아래 방향"으로만.

Q3. 친구에게 설명한다면?

DAL 패턴을 쓰지 않으면 어떤 문제가 생기는지 비유로 설명해봐.

예시 답변:

"은행에 비유하면 이래. DAL 없이 모든 창구(page)가 직접 금고(DB)에 접근하면, 어느 창구가 권한 체크를 빠뜨렸는지 알 수가 없어. DAL은 금고 앞에 딱 하나 있는 경비실이야. 경비실 통하지 않고는 금고에 못 들어가. 권한 체크를 빠뜨릴 수가 없는 구조야."

🐣 영철이의 퇴근 일기

오늘은 드디어 가이드의 마지막 장인 '아키텍처'까지 마쳤어! 처음엔 컴포넌트 하나 폴더에 넣는 것도 고민이었는데, 이제는 서비스가 아무리 커져도 흔들리지 않을 단단한 뼈대를 설계할 수 있다는 자신감이 생겼어.

💡 오늘의 교훈: "폴더 이름이 아니라 파일의 역할로 분류하자. app은 얇게, lib은 튼튼하게! 단단한 아키텍처가 서비스를 살린다."

단순히 기능이 돌아가는 걸 넘어, 보안을 생각하고 동료들이 찾기 쉬운 구조를 만드는 게 진짜 '시니어'의 길이라는 영호 리드 님의 말씀이 가슴에 깊게 박혔어. 앞으로 저희 서비스를 인스타보다 더 멋지게 만들면 영호 리드 님이 맛있는 수육 사주시겠지? 오늘은 가이드 완독 기념으로 일기장 덮고 일찍 퇴근해서 넷플릭스나 보면서 푹 쉬어야겠다! 🐣

🔗 더 알아보기

• Next.js 공식 문서 — Project Organization
• Next.js 공식 문서 — Security (DAL)
• server-only 패키지