2nd/10_Wiki/Topics/Architecture/Feature-Driven_Architecture.md

---
id: wiki-2026-0508-feature-driven-architecture
title: Feature-Driven Architecture
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [FDD, Feature Slices, Vertical Slice Architecture]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [architecture, feature-slices, modularity, frontend]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: typescript
  framework: nextjs
---

# Feature-Driven Architecture

## 매 한 줄
> **"매 layer-by-type 의 feature-by-vertical-slice 의 invert"**. Feature-Driven Architecture 매 codebase 의 organization unit 매 feature/use-case — 매 each feature 매 own UI + state + API + tests 의 own. Frontend 매 FSD (Feature-Sliced Design), Backend 매 vertical slice / modular monolith 의 manifest.

## 매 핵심

### 매 Why
- **Layer-by-type problem**: 매 `controllers/`, `services/`, `models/` 매 small project 의 fine, 매 100+ features 시 매 cross-cutting changes 의 5 directories 의 touch.
- **Feature 의 lifecycle**: 매 feature 의 add/remove/own 의 single folder 의 happen.
- **Team scaling**: 매 vertical squad 의 own 매 single feature folder, 매 conflicts 의 minimize.

### 매 FSD layers (frontend)
1. `app/` — global setup, routing, providers.
2. `pages/` — route compositions.
3. `widgets/` — composite UI blocks.
4. `features/` — user actions (login, addToCart).
5. `entities/` — business objects (User, Product).
6. `shared/` — UI kit, utils, API client.
- 매 import rule: 매 upper layer → lower layer only.

### 매 응용
1. Next.js / Remix apps with FSD.
2. Modular monolith — Java/.NET vertical slices.
3. Mobile (RN/Flutter) feature modules.
4. Microfrontend per-feature deployment.

## 💻 패턴

### FSD folder layout
```
src/
├── app/                  # providers, router, global styles
├── pages/
│   └── checkout/
│       └── ui/Checkout.tsx
├── widgets/
│   └── header/ui/Header.tsx
├── features/
│   ├── auth-login/
│   │   ├── ui/LoginForm.tsx
│   │   ├── model/store.ts
│   │   ├── api/login.ts
│   │   └── index.ts        # public api
│   └── cart-add-item/
├── entities/
│   ├── user/{ui, model, api}/
│   └── product/{ui, model, api}/
└── shared/
    ├── ui/Button.tsx
    └── api/baseQuery.ts
```

### Public API (index.ts barrel)
```typescript
// features/auth-login/index.ts
export { LoginForm } from './ui/LoginForm';
export { useLoginMutation } from './api/login';
// 매 internal model/store 의 not exported — encapsulation
```

### ESLint 의 enforce layer rules
```javascript
// .eslintrc — eslint-plugin-boundaries
module.exports = {
  plugins: ['boundaries'],
  settings: {
    'boundaries/elements': [
      { type: 'app', pattern: 'src/app/*' },
      { type: 'pages', pattern: 'src/pages/*' },
      { type: 'features', pattern: 'src/features/*' },
      { type: 'entities', pattern: 'src/entities/*' },
      { type: 'shared', pattern: 'src/shared/*' },
    ],
  },
  rules: {
    'boundaries/element-types': ['error', {
      default: 'disallow',
      rules: [
        { from: 'pages', allow: ['features', 'entities', 'shared'] },
        { from: 'features', allow: ['entities', 'shared'] },
        { from: 'entities', allow: ['shared'] },
      ],
    }],
  },
};
```

### Vertical slice (.NET / Node)
```typescript
// features/place-order/handler.ts
export class PlaceOrderCommand {
  constructor(public userId: string, public items: Item[]) {}
}

export async function placeOrder(cmd: PlaceOrderCommand, deps: Deps) {
  const user = await deps.users.findById(cmd.userId);
  if (!user) throw new NotFoundError();
  const order = Order.create(user, cmd.items);
  await deps.orders.save(order);
  await deps.bus.emit('order.placed', { orderId: order.id });
  return { orderId: order.id };
}

// features/place-order/route.ts
router.post('/orders', async (req, res) => {
  const result = await placeOrder(req.body, deps);
  res.json(result);
});
// 매 single folder 매 use-case 의 entire handle
```

### Cross-feature communication via events
```typescript
// features/cart-checkout — 매 features/inventory-update 의 NOT 매 import
// 매 instead: emit event, 매 inventory feature 의 subscribe
import { bus } from '@/shared/event-bus';

async function checkout(cart: Cart) {
  await bus.emit('checkout.completed', { items: cart.items });
}

// features/inventory-update/index.ts
bus.on('checkout.completed', async ({ items }) => {
  await decrementStock(items);
});
```

### Feature flag boundary
```typescript
// features/new-search-v2/index.ts
import { useFlag } from '@/shared/feature-flags';
import { SearchV1 } from '@/features/search-v1';
import { SearchV2 } from './ui/SearchV2';

export function Search() {
  const v2 = useFlag('search-v2');
  return v2 ? <SearchV2 /> : <SearchV1 />;
}
// Removal 의 single folder delete
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Solo / < 10 features | 매 layer-by-type 매 fine |
| Frontend, growing team | 매 FSD |
| Backend, modular monolith | 매 vertical slice (CQRS-style) |
| Microservices | 매 service-per-feature 매 already |
| Strict isolation 의 needed | 매 ESLint boundaries + barrel exports |

**기본값**: 매 frontend 매 FSD, 매 backend 매 vertical slice — 매 cross-feature 의 events.

## 🔗 Graph
- 부모: [[Software-Architecture]] · [[Modular-Monolith]]
- 변형: [[Feature-Sliced-Design]] · [[Vertical-Slice-Architecture]] · [[Hexagonal-Architecture]]
- 응용: [[Microfrontends]] · [[CQRS]] · [[Bounded-Context]]
- Adjacent: [[Domain-Driven-Design]] · [[Clean-Architecture]]

## 🤖 LLM 활용
**언제**: 매 10+ features, 매 multi-team. Frontend 매 page-driven 의 outgrow. Modular monolith 매 service split 의 prepare.
**언제 X**: 매 small app (<10 screens). 매 prototype phase — 매 over-structure cost > benefit.

## ❌ 안티패턴
- **Cross-feature direct import**: 매 `features/cart` 매 `features/checkout/internal` 의 import — 매 coupling 의 reintroduce. Public API 만 의 use.
- **God shared/**: 매 모든 utility 의 `shared/utils/` 의 dump — 매 entities/features 의 leak 의 should.
- **Premature feature split**: 매 single-screen app 의 7 features 의 carve — 매 navigation cost.
- **Layer skipping**: 매 `entities` 매 `features` 의 import — 매 dependency rule violation.

## 🧪 검증 / 중복
- Verified (feature-sliced.design official; Jimmy Bogard "Vertical Slice Architecture").
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — FSD layout + ESLint boundaries + vertical slice patterns |