src/
├── entities/                 # 비즈니스 엔티티 (도메인 객체)
│   ├── comment/             
│   │   ├── api/             # 댓글 관련 API 호출
│   │   ├── constants/      
│   │   ├── lib/          
│   │   └── types/   
│   ├── post/                
│   │   ├── api/         
│   │   ├── constants/
│   │   ├── lib/             
│   │   └── types/      
│   ├── tag/               
│   │   ├── api/           
│   │   └── types/     
│   └── user/           
│       ├── api/          
│       └── types/    
├── features/                # 사용자 행동 중심 기능
│   ├── comment-management/   # 댓글 관리 도메인
│   │   ├── create/          # 댓글 생성 기능
│   │   │   └── api/      
│   │   ├── list/            # 댓글 목록 표시
│   │   │   └── ui/    
│   │   ├── interactions/    # 댓글 상호작용 (좋아요)
│   │   │   └── api/        
│   │   ├── shared/          # 댓글 공통 UI
│   │   │   └── ui/          
│   │   └── update/          # 댓글 수정/삭제
│   │       └── api/        
│   ├── post-management/     # 게시물 관리 도메인
│   │   ├── create/          # 게시물 생성
│   │   │   ├── api/       
│   │   │   └── ui/        
│   │   ├── list/            # 게시물 목록/검색/필터
│   │   │   ├── api/         
│   │   │   ├── hooks/    
│   │   │   ├── model/   
│   │   │   └── ui/         
│   │   ├── shared/          # 게시물 공통 UI  
│   │   │   └── ui/        
│   │   └── update/          # 게시물 수정/삭제
│   │       └── api/      
│   └── user-profile/        # 사용자 프로필 조회
│       └── ui/            
├── shared/                  # 공통 요소
│   ├── hooks/              
│   ├── lib/                
│   ├── types/          
│   └── ui/               
├── widgets/                 # 독립적 위젯
│   ├── header/           
│   └── footer/           
├── pages/                   # 페이지 조합
│   └── PostsManagerPage.tsx 
└── app/                     # 앱 레벨 설정
    └── Providers.tsx       

Features 레이어 - 사용자 행동 중심 분리

전체 구조

features/
├── comment-management/     # 댓글과 관련된 모든 사용자 행동
├── post-management/       # 게시물과 관련된 모든 사용자 행동
└── user-profile/          # 사용자 정보 조회 행동

각 도메인별 내부 구조:

• create/ - 새로운 데이터를 생성하는 행동
• list/ - 데이터를 조회하고 표시하는 행동
• interactions/ - 데이터와 상호작용하는 행동 (좋아요, 공유 등)
• update/ - 기존 데이터를 수정/삭제하는 행동
• shared/ - 해당 도메인 내에서 공통으로 사용되는 UI/로직

A. Post Management - 검색/필터링

폴더 구조 상세 분석

post-management/list/
├── api/                           # 복합 조회 API 집합
│   ├── listWithAuthorPostApi.ts          # 기본 목록 + 작성자
│   ├── searchWithAuthorPostApi.ts        # 검색 결과 + 작성자  
│   ├── tagWithAuthorPostApi.ts           # 태그 필터 + 작성자
│   ├── filterPostApi.ts                  # 순수 태그 필터
│   └── searchPostApi.ts                  # 순수 검색
├── hooks/                         # 커스텀 훅
│   └── usePostsUrlSync.ts                # URL 상태 동기화
├── model/                         # 상태 관리 (Jotai)
│   └── queryParams.ts                    # 모든 필터/검색 상태
└── ui/                           # UI 컴포넌트 분리
    ├── PostManagerList.tsx              # 최상위 컨테이너
    ├── SearchAndFilters.tsx             # 검색/필터 UI
    ├── PostTable.tsx                    # 테이블 표시
    ├── PostTableRow.tsx                 # 개별 행
    └── PaginationControls.tsx           # 페이지네이션

API 폴더 - Entities와 Features 분리 이유

과제에서 게시물 목록에 작성자 정보를 함께 표시해야 했습니다. API 응답 구조상 게시물과 사용자 정보가 분리되어 있어 데이터 조합이 필요했고, 데이터 조합 로직을 어디에 둘 것인지 고민이 많았습니다.

GET /posts → { posts: [{ id, title, body, userId, tags }], total }
GET /users → { users: [{ id, username, image }], total }

Entities 레이어: 순수한 도메인 API만

// entities/post/api/listPostApi.ts
export const fetchPosts = async (params) => {
  return api.get<PostsResponse>(`/posts?${queryParams}`)
}

// entities/user/api/listUserApi.ts  
export const fetchUsers = async (params) => {
  return api.get<UsersResponse>(`/users?${queryParams}`)
}

다른 feautres에서도 동일한 AP를 사용할 수 있도록 재사용성을 위해 단순하게 유지했습니다. 예를 들어 댓글 작성자 정보를 가져올 때도 동일한 fetchUsers API를 사용할 수 있고, 사용자 프로필 조회 기능에서도 같은 API를 활용할 수 있습니다.

Features 레이어: 비즈니스 로직 처리

// features/post-management/list/api/listWithAuthorPostApi.ts
const fetchPostsWithAuthors = async (params) => {
  // 1. 필요한 데이터를 병렬로 가져오기
  const [postsData, usersData] = await Promise.all([
    fetchPosts(params),                           // entities API 재사용
    fetchUsers({ limit: 0, select: "username,image" })  // entities API 재사용
  ])

  // 2. UI에서 필요한 형태로 데이터 조합
  const postsWithUsers = postsData.posts.map(post => ({
    ...post,
    author: usersData.users.find(user => user.id === post.userId)
  }))

  return { posts: postsWithUsers, total: postsData.total }
}

게시물 목록에서 작성자 이름과 이미지를 함께 표시하기 위해 features 레이어에 데이터 조합 로직을 위치시켰습니다. 이렇게 하면 UI 컴포넌트에서는 복잡한 데이터 처리 없이 필요한 정보를 바로 사용할 수 있습니다. 만약 나중에 게시물에 댓글 수 같은 추가 정보가 필요하다면, entities의 기본 API는 그대로 두고 features에서만 새로운 조합 로직을 추가하면 됩니다.

사용자 시나리오별 API 분리 게시물 목록에서 다양한 상황에 대응하기 위해 시나리오별로 API를 분리했습니다.

// 1. 일반 목록 조회
// features/post-management/list/api/listWithAuthorPostApi.ts
const fetchPostsWithAuthors = async (params) => {
  const [postsData, usersData] = await Promise.all([
    fetchPosts(params),              // GET /posts
    fetchUsers({ limit: 0 })
  ])
  // 데이터 조합...
}

// 2. 검색 결과 조회
// features/post-management/list/api/searchWithAuthorPostApi.ts  
const fetchSearchPostsWithAuthors = async (query) => {
  const [searchResults, usersData] = await Promise.all([
    fetchSearchPosts({ query }),     // GET /posts/search
    fetchUsers({ limit: 0 })
  ])
  // 데이터 조합...
}

// 3. 태그별 조회
// features/post-management/list/api/tagWithAuthorPostApi.ts
const fetchPostsByTagWithAuthors = async (tag) => {
  const [tagResults, usersData] = await Promise.all([
    fetchPostsByTag({ tag }),        // GET /posts/tag/{tag}
    fetchUsers({ limit: 0 })
  ])
  // 데이터 조합...
}

일반 목록, 검색 결과, 태그별 조회가 각각 독립적인 캐시 키를 가지므로 사용자가 검색하다가 태그를 클릭해도 기존 데이터가 유지됩니다. 또한 검색어가 없거나 태그가 선택되지 않았을 때는 해당 API를 호출하지 않도록 조건부 실행을 적용해서 불필요한 네트워크 요청을 방지했습니다.

Model 폴더 - 전역 상태 관리 설계

게시물 목록 화면에서 사용자는 검색어 입력, 태그 선택, 정렬 기준 변경, 페이지 이동 등 다양한 상호작용을 합니다. 이 모든 상태를 어떻게 관리하고, URL과 동기화할 것인지 고민이 많았습니다. 전역 상태 관리 라이브러리로 Jotai를 선택했습니다. Props Drilling을 제거할 수 있고, 각 컴포넌트가 필요한 상태만 구독해서 최소한의 리렌더링을 보장하기 때문입니다.

상태 설계: 도메인별 분리

// features/post-management/list/model/queryParams.ts

// 1. 사용자 입력 상태
export const postsSearchQueryAtom = atom("")           // 검색어
export const postsSelectedTagAtom = atom("all")        // 선택된 태그
export const postsSortByAtom = atom("none")            // 정렬 기준
export const postsSortOrderAtom = atom<"asc" | "desc">("asc")  // 정렬 순서

// 2. 페이지네이션 상태
export const postsPageAtom = atom(1)                   // 현재 페이지
export const postsLimitAtom = atom(10)                 // 페이지당 항목 수
export const postsSkipAtom = atom(0)                   // 건너뛸 항목 수

상태를 사용자 입력과 페이지네이션으로 분리해서 각 atom이 명확한 역할을 갖도록 설계했습니다. 이렇게 세분화하면 컴포넌트에서 관심있는 상태만 구독할 수 있어 불필요한 리렌더링을 방지할 수 있습니다. 또 각 상태의 변경 영향 범위를 예측하기 쉬워져 유지보수하기 용이해집니다.

URL 자동 동기화

// 3. 파생 상태로 URL 쿼리스트링 자동 생성
export const postsQueryStringAtom = atom((get) => {
  const limit = get(postsLimitAtom)
  const skip = get(postsSkipAtom)
  const searchQuery = get(postsSearchQueryAtom)
  const selectedTag = get(postsSelectedTagAtom)
  const sortBy = get(postsSortByAtom)
  const sortOrder = get(postsSortOrderAtom)

  const params = { limit: String(limit), skip: String(skip) }
  
  if (searchQuery.trim()) params.search = searchQuery
  if (selectedTag && selectedTag !== "all") params.tag = selectedTag
  if (sortBy && sortBy !== "none") params.sortBy = sortBy
  if (sortOrder !== "asc") params.sortOrder = sortOrder

  return new URLSearchParams(params).toString()
})

사용자의 모든 필터 상태를 URL 쿼리스트링으로 자동 변환하는 파생 상태를 구현했습니다. 이를 통해 사용자가 새로고침해도 현재 필터 상태가 유지되고, URL을 복사해서 공유하면 동일한 화면을 볼 수 있습니다.

Jotai의 액션 패턴 활용

// 복잡한 상태 변경을 하나의 액션으로 처리
export const setPostsPageAtom = atom(null, (get, set, page: number) => {
  const limit = get(postsLimitAtom)
  set(postsPageAtom, page)
  set(postsSkipAtom, (page - 1) * limit)  // skip 값 자동 계산
})

export const setPostsLimitAtom = atom(null, (get, set, limit: number) => {
  const page = get(postsPageAtom)
  set(postsLimitAtom, limit)
  set(postsSkipAtom, (page - 1) * limit)  // 현재 페이지 기준으로 skip 재계산
})

페이지 변경 시 skip 값도 함께 업데이트해야 하는 로직을 액션 패턴으로 해결했습니다. 여러 상태를 동기화해서 변경하는 로직을 한 곳에 집중시켜서 일관성을 보장하고, 컴포넌트에서는 단순히 setPage(2) 호출만 하면 되도록 구성했습니다.

실제 사용 예시: 컴포넌트 간 상태 공유

// 검색 컴포넌트
export const SearchInput = () => {
  const [searchQuery, setSearchQuery] = useAtom(postsSearchQueryAtom)
  const [, setPage] = useAtom(setPostsPageAtom)

  const handleSearchChange = (value: string) => {
    setSearchQuery(value)  // 검색어 변경
    setPage(1)             // 첫 페이지로 자동 이동
  }
  // ...
}

// 필터 컴포넌트
export const FiltersContainer = () => {
  const [selectedTag, setSelectedTag] = useAtom(postsSelectedTagAtom)
  const [, setPage] = useAtom(setPostsPageAtom)

  const handleTagChange = (tag: string) => {
    setSelectedTag(tag)    // 태그 변경
    setPage(1)             // 첫 페이지로 자동 이동
  }
  // ...
}

// 목록 컴포넌트 - 모든 상태를 읽기만 함
export const PostManagerList = () => {
  const searchQuery = useAtomValue(postsSearchQueryAtom)
  const selectedTag = useAtomValue(postsSelectedTagAtom)
  const limit = useAtomValue(postsLimitAtom)
  const skip = useAtomValue(postsSkipAtom)
  
  // 상태 조합해서 적절한 API 호출
  // ...
}

B. Post Management - shared 폴더 설계

전역 shared vs 도메인 shared 구분

shared/ui/ (전역 공통 - 모든 도메인에서 사용)
├── Button.tsx        # 범용 버튼
├── Dialog.tsx        # 범용 다이얼로그
├── Input.tsx         # 범용 입력
└── Table.tsx         # 범용 테이블

post-management/shared/ui/ (게시물 도메인 전용)
├── PostFormDialog.tsx     # 게시물 생성/수정 폼
└── PostDetailDialog.tsx   # 게시물 상세보기

PostFormDialog - 생성/수정 공통 폼 설계

// features/post-management/shared/ui/PostFormDialog.tsx

interface PostFormDialogProps {
  mode: "create" | "update"    // 모드에 따른 동작 분기
  isOpen: boolean
  onClose: () => void
  post?: PostWithAuthor | null // 수정 모드일 때만 필요
}

export const PostFormDialog = ({ mode, isOpen, onClose, post }) => {
  // 각 기능의 API Hook 사용
  const { mutate: createPost } = useCreatePost()    // create/api
  const { mutate: updatePost } = useUpdatePost()    // update/api

  // 폼 상태 관리
  const [title, setTitle] = useState("")
  const [body, setBody] = useState("")
  const [userId, setUserId] = useState(1)

  // 모드에 따른 폼 초기화
  useEffect(() => {
    if (mode === "update" && post) {
      setTitle(post.title)
      setBody(post.body)
      setUserId(post.userId)
    } else {
      setTitle("")
      setBody("")
      setUserId(1)
    }
  }, [mode, post, isOpen])

  // 모드에 따른 제출 로직 분기
  const handleSubmit = () => {
    if (!title.trim() || !body.trim()) return

    if (mode === "create") {
      createPost(
        { title: title.trim(), body: body.trim(), userId },
        { onSuccess: () => handleClose() }
      )
    } else if (mode === "update" && post) {
      updatePost(
        { id: post.id, data: { title: title.trim(), body: body.trim() } },
        { onSuccess: () => handleClose() }
      )
    }
  }

  return (
    <Dialog open={isOpen} onOpenChange={onClose}>
      <DialogContent>
        <DialogTitle>
          {mode === "create" ? "새 게시물 추가" : "게시물 수정"}
        </DialogTitle>
        
        <div className="space-y-4">
          <Input 
            placeholder="제목" 
            value={title} 
            onChange={(e) => setTitle(e.target.value)} 
          />
          
          <Textarea
            rows={mode === "create" ? 30 : 15}
            placeholder="내용"
            value={body}
            onChange={(e) => setBody(e.target.value)}
          />
          
          {/* 생성 모드일 때만 사용자 ID 입력 */}
          {mode === "create" && (
            <Input
              type="number"
              placeholder="사용자 ID"
              value={userId}
              onChange={(e) => setUserId(Number(e.target.value))}
            />
          )}
          
          <div className="flex gap-2 justify-end">
            <Button variant="outline" onClick={onClose}>
              취소
            </Button>
            <Button onClick={handleSubmit} disabled={!title.trim() || !body.trim()}>
              {mode === "create" ? "게시물 추가" : "게시물 업데이트"}
            </Button>
          </div>
        </div>
      </DialogContent>
    </Dialog>
  )
}

다양한 기능에서 공통 사용

// 1. 게시물 생성에서 사용
// features/post-management/create/ui/CreateButton.tsx
export const CreateButton = () => {
  const { isModalOpen, handleModalOpen, handleModalClose } = useModal()

  return (
    <>
      <Button onClick={handleModalOpen}>
        <Plus className="w-4 h-4 mr-2" />
        게시물 추가
      </Button>
      
      {isModalOpen && (
        <PostFormDialog 
          mode="create" 
          isOpen={isModalOpen} 
          onClose={handleModalClose} 
        />
      )}
    </>
  )
}

// 2. 게시물 수정에서 사용  
// features/post-management/list/ui/PostControlPanel.tsx
export const PostControlPanel = ({ post }) => {
  const { isModalOpen, handleModalOpen, handleModalClose } = useModal()

  return (
    <>
      <Button onClick={handleModalOpen}>
        <Edit2 className="w-4 h-4" />
      </Button>
      
      {isModalOpen && (
        <PostFormDialog 
          mode="update" 
          isOpen={isModalOpen} 
          onClose={handleModalClose} 
          post={post}
        />
      )}
    </>
  )
}

PostDetailDialog - 상세보기 + 댓글 통합

// features/post-management/shared/ui/PostDetailDialog.tsx
export const PostDetailDialog = ({ isOpen, onClose, post }) => {
  // 검색어 상태를 사용해서 하이라이팅
  const searchQuery = useAtomValue(postsSearchQueryAtom)

  // 검색어 하이라이팅 함수
  const renderHighlightedText = (text: string, query: string) => {
    const { parts, isMatch } = splitTextForHighlight(text, query)
    return (
      <span>
        {parts.map((part, i) => 
          isMatch(part) ? <mark key={i}>{part}</mark> : part
        )}
      </span>
    )
  }

  return (
    <Dialog open={isOpen} onOpenChange={onClose}>
      <DialogContent className="max-w-3xl">
        <DialogHeader>
          <DialogTitle>
            {renderHighlightedText(post.title, searchQuery)}
          </DialogTitle>
        </DialogHeader>
        
        <div className="space-y-4">
          <p>{renderHighlightedText(post.body, searchQuery)}</p>

          {/* 댓글 위젯 통합 - 다른 feature의 컴포넌트 사용 */}
          <CommentList postId={post.id} searchQuery={searchQuery} />
        </div>
      </DialogContent>
    </Dialog>
  )
}