frontend-design-patterns

1. DDD + FSD Hybrid Architecture

• Philosophy: Think in domains, not pages
• Structure: Layered architecture with unidirectional dependencies
• Key Concept: Features (user actions) vs Entities (data representation)

Reference: See references/ddd-fsd-fundamentals.md for detailed DDD/FSD fusion strategy.

2. FSD Layer Hierarchy

```

App -> Pages -> Widgets -> Features -> Entities -> Shared

```

Each layer only depends on layers below it. No upward dependencies.

• Slices: Domain-based directories (e.g., features/cart, features/auth)
• Segments: ui/, model/, api/, lib/, config/, index.ts

Reference: See references/fsd-layers-guide.md for complete layer definitions.

3. Component Structure: Index/Types/Styles

```

ComponentName/

├── index.tsx # React logic & JSX

├── types.ts # TypeScript interfaces

└── styles.ts # CSS-in-JS (Emotion/styled-components)

```

Separates concerns at filesystem level. Improves collaboration and reduces merge conflicts.

Reference: See references/component-structure.md for implementation details.

4. Data Layer: Service/Hook 1:1 Mapping

```

Service Layer (Pure TS) -> Hook Layer (React Query) -> Components

```

• Service: API calls, DTOs (React-agnostic)
• Hook: React Query integration, caching, loading/error states
• Rule: One service function = one custom hook
• Query Keys: Use factory pattern

Reference: See references/data-layer-architecture.md for Axios/React Query setup.

5. State Management: Zustand + React Query

• React Query: Server state (API data, caching)
• Zustand: Client state (theme, modals, complex forms)
• Store Location: Domain-specific in model/ segment
• Pattern: Slice pattern with selector optimization

Reference: See references/state-management.md for Zustand patterns.

6. TypeScript Conventions

| Target | Case | Example |

|--------|------|---------|

| Component | PascalCase | UserProfile |

| Interface | PascalCase | UserProfileProps |

| Variable | camelCase | userList, isLoading |

| Boolean | camelCase | is, has, should, can prefix |

| Constant | UPPER_SNAKE | MAX_COUNT |

| Hook | camelCase | useAuth, useWindowSize |

Reference: See references/typescript-conventions.md for complete rules.

Load references based on current task:

| Task | Reference |

|------|-----------|

| Architecture design | references/ddd-fsd-fundamentals.md |

| Folder structure | references/fsd-layers-guide.md |

| Component creation | references/component-structure.md |

| API/Data layer | references/data-layer-architecture.md |

| State management | references/state-management.md |

| Code conventions | references/typescript-conventions.md |

Create FSD Structure

```bash

python scripts/create_fsd_structure.py [--slices cart auth user]

```

Creates complete FSD folder structure with standard segments.

Create Component

```bash

python scripts/create_component.py

```

Generates Index/Types/Styles pattern component.

Create Service/Hook Pair

```bash

python scripts/create_service_hook.py

```

Generates Service Layer + Hook Layer with Query Key factory.

Create Zustand Store

```bash

python scripts/create_zustand_store.py

```

Generates Zustand store with selectors and actions.

1. Separation of Concerns: UI, logic, styles separated at filesystem level
2. Unidirectional Dependencies: Layers only depend on lower layers
3. Explicit Dependencies: No circular references
4. Type Safety: Strict TypeScript, no any
5. Single Responsibility: Each file/module has one clear purpose