1+ ---
2+ description: Frontend Architecture (Feature-Based Approach with Container/Presentational Pattern)
3+ globs: *.ts,*.tsx
4+ alwaysApply: true
5+ ---
6+
7+ ## Overview
8+
9+ The frontend architecture follows a feature-based approach, organizing code by domain features rather than technical layers. This structure aligns with Domain-Driven Design (DDD) principles while adapting them for frontend development. Within each feature, we implement the Container/Presentational pattern (Container 1st design) to separate business logic from UI presentation.
10+
11+ ## Directory Structure
12+
13+ Example directory structure is as follows:
14+
15+ ```
16+ src/
17+ ├── features/ # Feature modules
18+ │ ├── users/ # Users feature
19+ │ │ ├── api/ # API services for users
20+ │ │ ├── components/ # Components specific to users
21+ │ │ │ ├── containers/ # Container components with logic
22+ │ │ │ └── presenters/ # Presentational components (UI only)
23+ │ │ ├── domain/ # Domain models and logic
24+ │ │ ├── hooks/ # Custom hooks for users
25+ │ │ ├── pages/ # Page components
26+ │ │ │ ├── UserProfile/ # User profile page
27+ │ │ │ │ ├── container.tsx # Logic container
28+ │ │ │ │ └── presenter.tsx # UI presentation
29+ │ │ │ └── ...
30+ │ │ └── utils/ # Utilities for users
31+ │ ├── products/ # Products feature
32+ │ ├── notifications/ # Notifications feature
33+ │ └── ...
34+ ├── shared/ # Shared code across features
35+ │ ├── components/ # Reusable UI components
36+ │ │ ├── containers/ # Shared container components
37+ │ │ └── presenters/ # Shared presentational components
38+ │ ├── hooks/ # Custom React hooks
39+ │ ├── utils/ # Utility functions
40+ │ └── api/ # API client code
41+ └── common/ # Application-wide code
42+ ├── layouts/ # Page layouts
43+ ├── providers/ # Context providers
44+ ├── styles/ # Global styles
45+ └── types/ # Global TypeScript types
46+ ```
47+
48+ ## Container/Presentational Pattern
49+
50+ We adopt the Container 1st approach to separate concerns within components:
51+
52+ ### Container Components
53+ - Responsible for "what to do":
54+ - Data fetching and state management
55+ - Business logic
56+ - Event handling
57+ - Data transformation
58+ - Pass data and callbacks to presentational components
59+ - Don't contain significant markup or styling
60+
61+ ### Presentational Components
62+ - Responsible for "how to look":
63+ - UI rendering
64+ - Styling
65+ - Animation
66+ - Accessibility
67+ - Receive data and callbacks via props
68+ - Typically pure functional components
69+ - Reusable across different containers
70+
71+ ## Component Organization
72+
73+ Components are organized in two ways:
74+
75+ 1. **Feature-specific components**: Located within each feature module, used only within that feature
76+ ```
77+ features/users/components/
78+ ├── containers/
79+ │ ├── UserCard.tsx
80+ │ ├── UserList.tsx
81+ │ └── ...
82+ └── presenters/
83+ ├── UserCardPresenter.tsx
84+ ├── UserListPresenter.tsx
85+ └── ...
86+ ```
87+
88+ 2. **Shared components**: Located in the shared directory, reused across features
89+ ```
90+ shared/components/
91+ ├── containers/
92+ │ ├── Modal.tsx
93+ │ ├── Pagination.tsx
94+ │ └── ...
95+ └── presenters/
96+ ├── Button.tsx
97+ ├── Card.tsx
98+ └── ...
99+ ```
100+
101+ ## Page Structure
102+
103+ Pages follow the same Container/Presentational pattern:
104+
105+ ```
106+ features/users/pages/UserProfile/
107+ ├── container.tsx # Contains data fetching, state, and logic
108+ ├── presenter.tsx # Renders the UI based on props
109+ ├── index.ts # Export the connected component
110+ └── serverSideProps.ts # Next.js data fetching (if applicable)
111+ ```
112+
113+ ## Principles
114+
115+ 1. **Feature Isolation**: Each feature should be self-contained with minimal dependencies on other features.
116+ 2. **Shared Components**: Common UI elements are placed in the shared directory for reuse.
117+ 3. **Domain-Driven**: Features should align with business domains rather than technical concerns.
118+ 4. **Container 1st Design**: Always start with containers that define what needs to be done, then create presenters.
119+ 5. **Separation of Concerns**:
120+ - Containers handle logic and data
121+ - Presenters handle UI and styling
122+ 6. **Layered Approach Within Features**:
123+ - UI Layer: Presenters
124+ - Application Layer: Containers, hooks
125+ - Domain Layer: Business logic, data transformation
126+ - Infrastructure Layer: API calls, external services integration
127+
128+ ## Data Flow
129+
130+ 1. Container components fetch and manage data
131+ 2. Data flows down to presentational components via props
132+ 3. User events in presentational components trigger callbacks defined in container components
133+ 4. Container components update state based on these events
134+
135+ ## Dependency Direction
136+
137+ Dependencies should flow from:
138+ - Features → Shared → Common
139+ - Never: Common → Features or Shared → Features
140+ - Within features: Container → Presenter (one-way)
141+
142+ ## Testing Strategy
143+
144+ - Container tests: Test business logic and state management
145+ - Presenter tests: Test UI rendering and interactions
146+ - Integration tests: Test container-presenter pairs working together
147+ - End-to-end tests: Test complete user flows
148+
149+ ## Implementation Guidelines
150+
151+ - Use TypeScript for type safety across the application
152+ - Follow consistent naming conventions for files and components
153+ - ContainerName.tsx and NamePresenter.tsx
154+ - Keep presenters as pure functions when possible
155+ - Document component APIs using JSDoc or Storybook
156+ - Use custom hooks to extract and reuse complex logic from containers
157+
158+ ## State Management
159+
160+ - Feature-specific state should be contained within the feature module
161+ - Cross-feature state should be managed through a central store or context
0 commit comments