Frontend Design Patterns
Enterprise-grade React architecture combining Domain-Driven Design (DDD) and Feature-Sliced Design (FSD) with strict TypeScript conventions.
Core 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 -> SharedEach 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.
Workflow
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 |
Scripts
Create FSD Structure
python scripts/create_fsd_structure.py <project-root> [--slices cart auth user]Creates complete FSD folder structure with standard segments.
Create Component
python scripts/create_component.py <path> <ComponentName>Generates Index/Types/Styles pattern component.
Create Service/Hook Pair
python scripts/create_service_hook.py <feature-path> <service-name>Generates Service Layer + Hook Layer with Query Key factory.
Create Zustand Store
python scripts/create_zustand_store.py <feature-path> <store-name>Generates Zustand store with selectors and actions.
Key Principles
- Separation of Concerns: UI, logic, styles separated at filesystem level
- Unidirectional Dependencies: Layers only depend on lower layers
- Explicit Dependencies: No circular references
- Type Safety: Strict TypeScript, no
any - Single Responsibility: Each file/module has one clear purpose