2nd/10_Wiki/Topics/Frontend/Frontend-Architecture-and-Folder-Structure.md

---
id: wiki-2026-0508-frontend-architecture-and-folder
title: Frontend Architecture and Folder Structure
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Project Structure, Folder Convention, Frontend Layout]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [frontend, architecture, project-structure, conventions]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: TypeScript
  framework: React
---

# Frontend Architecture and Folder Structure

## 매 한 줄
> **"매 file layout 의 의 architecture 의 — folder 의 dependency direction 의 enforce"**. 2026 의 의 매 dominant convention 의 **Feature-Sliced Design (FSD)** + **colocation by route** (Next.js App Router). 매 monorepo 의 의 매 cross-package boundary 의 의 nx/turbo 의 의 enforce.

## 매 핵심

### 매 layered approach (FSD)
- **app**: 의 entrypoint, provider, router setup.
- **pages / routes**: 의 page-level composition.
- **widgets**: 의 self-contained UI block (Header, Sidebar).
- **features**: 의 user action (LoginForm, AddToCart).
- **entities**: 의 domain object (User, Product).
- **shared**: 의 reusable utility (UI kit, lib, config).

매 dependency 의 down-only — 의 widget 의 entity/shared 의 import 의 OK, 의 reverse 의 X.

### 매 colocation 의 rule
- 의 component 의 의 close 의 의 use site.
- 의 test, story, type 의 의 same folder.
- Route folder 의 의 page-only 의 keep — 의 reusable 의 의 lift up.

### 매 응용
1. Solo project 의 의 minimal (`src/components`, `src/pages`).
2. Team project 의 의 FSD layered.
3. Monorepo 의 의 nx/turbo 의 의 boundary enforce.
4. Design system 의 의 separate package.

## 💻 패턴

### FSD layout
```
src/
  app/
    providers/
    routes/
    main.tsx
  pages/
    home/
    profile/
  widgets/
    header/
    sidebar/
  features/
    auth-login/
      ui/
      model/
      api/
      index.ts
  entities/
    user/
      ui/
      model/
      api/
  shared/
    ui/
    lib/
    config/
    api/
```

### Next.js App Router 의 colocation
```
app/
  layout.tsx
  page.tsx
  (marketing)/          # route group
    pricing/
      page.tsx
      _components/
        PricingCard.tsx
  dashboard/
    layout.tsx
    page.tsx
    [id]/
      page.tsx
      loading.tsx
      error.tsx
      _lib/
        fetch-data.ts
components/             # shared, lifted
  ui/
lib/
  utils.ts
```

### Public API per slice (`index.ts`)
```ts
// features/auth-login/index.ts
export { LoginForm } from "./ui/LoginForm";
export { useLogin } from "./model/use-login";
// 매 internal helper 의 의 of export 의 X — barrier.
```

```ts
// widgets/header/Header.tsx
import { LoginForm } from "@/features/auth-login";  // OK — public API
// import { internalHelper } from "@/features/auth-login/lib/internal";  // X
```

### TS path alias
```jsonc
// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@app/*":      ["src/app/*"],
      "@pages/*":    ["src/pages/*"],
      "@widgets/*":  ["src/widgets/*"],
      "@features/*": ["src/features/*"],
      "@entities/*": ["src/entities/*"],
      "@shared/*":   ["src/shared/*"]
    }
  }
}
```

### ESLint boundaries
```js
// eslint.config.js
import boundaries from "eslint-plugin-boundaries";

export default [{
  plugins: { boundaries },
  settings: {
    "boundaries/elements": [
      { type: "app",      pattern: "src/app/*" },
      { type: "pages",    pattern: "src/pages/*" },
      { type: "widgets",  pattern: "src/widgets/*" },
      { type: "features", pattern: "src/features/*" },
      { type: "entities", pattern: "src/entities/*" },
      { type: "shared",   pattern: "src/shared/*" },
    ],
  },
  rules: {
    "boundaries/element-types": ["error", {
      default: "disallow",
      rules: [
        { from: "app",      allow: ["pages", "widgets", "features", "entities", "shared"] },
        { from: "pages",    allow: ["widgets", "features", "entities", "shared"] },
        { from: "widgets",  allow: ["features", "entities", "shared"] },
        { from: "features", allow: ["entities", "shared"] },
        { from: "entities", allow: ["shared"] },
        { from: "shared",   allow: ["shared"] },
      ],
    }],
  },
}];
```

### Slice 의 internal layer
```
features/auth-login/
  ui/                    # React component
    LoginForm.tsx
    LoginForm.test.tsx
    LoginForm.stories.tsx
  model/                 # state, hooks, business logic
    use-login.ts
    login-store.ts
  api/                   # network call
    login-request.ts
  lib/                   # helpers (private)
    validate-credentials.ts
  index.ts               # public API
```

### Monorepo (turbo)
```
apps/
  web/                   # Next.js app
  mobile/                # React Native
packages/
  ui/                    # design system
  api-client/            # tRPC/REST client
  config-eslint/
  config-tsconfig/
```

```jsonc
// turbo.json
{
  "tasks": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**"] },
    "lint":  {},
    "test":  { "dependsOn": ["^build"] }
  }
}
```

### Barrel file 의 caution
```ts
// 매 export * 의 의 tree-shaking 의 hurt 의 가능
export * from "./Button";
export * from "./Card";

// 매 explicit re-export 의 더 의 safe
export { Button } from "./Button";
export { Card }   from "./Card";
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Solo / prototype | `src/{components,pages,lib}` flat |
| Team < 5, single app | FSD-lite (skip `entities`, merge `widgets`) |
| Team > 5 | Full FSD + ESLint boundaries |
| Multi-app | Monorepo (turbo / nx) + shared `packages/ui` |
| Next.js App Router | Route colocation + `_private` folders |

**기본값**: FSD-lite (app/pages/features/shared) + path alias + ESLint boundaries.

## 🔗 Graph
- 부모: [[Software Architecture]] · [[Project Structure]]
- 변형: [[Feature-Sliced Design]] · [[Atomic Design]] · [[Clean Architecture]]

## 🤖 LLM 활용
**언제**: new project 의 scaffold, legacy reorg, monorepo migration, dependency direction 의 enforce.
**언제 X**: 의 매 < 50 file project — flat structure 의 충분.

## ❌ 안티패턴
- **`src/components/` god folder**: 매 1000+ file 의 의 unscalable.
- **Cross-feature import**: feature-A 의 feature-B 의 internal 의 reach — 의 shared/entities 의 의 lift up.
- **Deep nesting** (`a/b/c/d/e/f/`): 매 navigate 의 hard — 매 max 4-level 의 keep.
- **Barrel `export *`**: 매 tree-shake 의 의 break, 매 circular 의 의 hide.
- **No boundary enforcement**: convention 의 의 의 only — 의 violation 의 의 silent 의 accumulate.

## 🧪 검증 / 중복
- Verified (Feature-Sliced Design docs, Next.js App Router, Vercel monorepo guide, nx docs, eslint-plugin-boundaries).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — FSD layout + ESLint boundaries + monorepo 추가 |