cartflows / docs / wiki / Frontend-Architecture.md

Frontend-Architecture.md in CartFlows – Funnel Builder & Checkout Plugin for WooCommerce 3.0.1, at docs/wiki/Frontend-Architecture.md

157 lines 5.0 KB

Raw Download Zip

1	# Frontend Architecture
2
3	CartFlows ships two independent React 18 admin applications — the Editor App and the Settings App — compiled with `@wordpress/scripts` and styled with Tailwind CSS.
4
5	## Overview
6
7	```
8	admin-core/assets/src/
9	├── EditorApp.js ← Editor app entry (React root)
10	├── SettingsApp.js ← Settings app entry (React root)
11	├── common/ ← Shared components + utilities
12	├── fields/ ← Reusable form field components
13	├── flow-editor/ ← Canvas, nodes, analytics (editor)
14	├── step-editor/ ← Step settings panels (editor)
15	├── settings-app/ ← Dashboard, analytics, flows list
16	├── importer/ ← Template import UI
17	├── store-importer/ ← Store import UI
18	└── utils/ ← SettingsProvider, helpers
19	```
20
21	## Technology Stack
22
23	\| Library \| Version \| Purpose \|
24	\|---------\|---------\|---------\|
25	\| React \| 18.3.1 \| UI rendering \|
26	\| React DOM \| 18.2.0 \| DOM mounting \|
27	\| React Router DOM \| 5.2.0 \| In-app routing \|
28	\| Redux \| 4.1.0 \| Global state management \|
29	\| React Redux \| 7.2.4 \| Redux bindings \|
30	\| `@wordpress/api-fetch` \| 5.x \| Authenticated REST API calls \|
31	\| `@wordpress/components` \| 27.x \| WP UI component library \|
32	\| `@wordpress/data` \| 9.x \| WP data store integration \|
33	\| `@wordpress/hooks` \| 3.x \| WordPress hook system in JS \|
34	\| `@wordpress/i18n` \| 4.x \| Internationalisation \|
35	\| Tailwind CSS \| 3.0 \| Utility-first styling \|
36	\| react-flow-renderer \| 10.3.17 \| Flow canvas / node editor \|
37	\| ApexCharts \| 4.x \| Analytics charts \|
38	\| react-select \| 5.x \| Enhanced select inputs \|
39	\| dayjs \| 1.x \| Date handling \|
40	\| SortableJS \| 1.14 \| Drag-and-drop sorting \|
41
42	## Editor App
43
44	Entry: `EditorApp.js`
45
46	```jsx
47	const WcfEditorAppRoot = createRoot( document.getElementById( 'wcf-editor-app' ) );
48	WcfEditorAppRoot.render(
49	<SettingsProvider>
50	<ConfirmDialogProvider>
51	<MainEditor />
52	<LoaderPopup />
53	</ConfirmDialogProvider>
54	</SettingsProvider>
55	);
56	```
57
58	The editor app mounts on the `#wcf-editor-app` DOM element rendered by WordPress admin pages. It provides the visual flow canvas and step configuration panels.
59
60	See [](Editor-AppEditor-App](Editor-App](Editor-App) for component details.
61
62	## Settings App
63
64	Entry: `SettingsApp.js`
65
66	The settings app powers the CartFlows dashboard, analytics views, flows list, and global settings panel.
67
68	See [](Settings-AppSettings-App](Settings-App](Settings-App) for component details.
69
70	## State Management
71
72	State is managed through two complementary systems:
73
74	1. Redux — Global application state (flows, steps, settings data)
75	2. `SettingsProvider` — React Context wrapper providing initial server-side data injected via `wp_localize_script`
76
77	See [](State-ManagementState-Management](State-Management](State-Management) for details.
78
79	## Routing
80
81	React Router DOM v5 handles in-app navigation without full page reloads:
82
83	```
84	/ → Home / Dashboard
85	/flows → Flows list
86	/flow/:id → Flow editor (canvas)
87	/flow/:id/step/:sid → Step editor
88	/analytics → Analytics dashboard
89	/settings → Global settings
90	```
91
92	## API Communication
93
94	All REST API calls use `@wordpress/api-fetch`, which automatically:
95	- Attaches the WordPress nonce header (`X-WP-Nonce`)
96	- Handles authentication
97	- Follows the `cartflows/v1` namespace
98
99	```js
100	import apiFetch from '@wordpress/api-fetch';
101
102	const flows = await apiFetch( {
103	path: '/cartflows/v1/flows',
104	method: 'POST',
105	data: { /* payload */ },
106	} );
107	```
108
109	## Data Injection
110
111	Server-side data is passed to JavaScript via `wp_localize_script` and `wp_add_inline_script`. The global objects include:
112
113	\| Global \| Contents \|
114	\|--------\|---------\|
115	\| `wcfEditorAppData` \| Flow/step data, nonce, admin URL, feature flags \|
116	\| `wcfSettingsAppData` \| Dashboard data, settings, feature flags \|
117
118	## Shared Components (`common/`)
119
120	\| Component \| Purpose \|
121	\|-----------\|---------\|
122	\| `global-settings/SettingsPage` \| Global settings form \|
123	\| `global-settings/SettingsContent` \| Settings content renderer \|
124	\| `main-navigation/NavMenu` \| Admin sidebar navigation \|
125	\| `confirm-popup/ConfirmPopup` \| Reusable confirmation dialog \|
126	\| `processing-popup/LoaderPopup` \| Loading overlay \|
127
128	## Field Components (`fields/`)
129
130	\| Component \| Purpose \|
131	\|-----------\|---------\|
132	\| `RenderFields.js` \| Field factory — renders the correct field type \|
133	\| `TextField` \| Text input \|
134	\| `Select2Field` \| Enhanced select (react-select) \|
135	\| `Tooltip` \| Tooltip wrapper \|
136	\| Product repeater \| Product search + select for offers \|
137
138	## Build Output
139
140	```
141	admin-core/assets/build/
142	├── editor-app.js # Bundled editor app
143	├── editor-app.css # Editor app styles
144	├── editor-app.asset.php # Dependency + version manifest
145	├── settings-app.js # Bundled settings app
146	├── settings-app.css # Settings app styles
147	└── settings-app.asset.php # Dependency + version manifest
148	```
149
150	## Related Pages
151
152	- [](Editor-AppEditor-App](Editor-App](Editor-App)
153	- [](Settings-AppSettings-App](Settings-App](Settings-App)
154	- [](State-ManagementState-Management](State-Management](State-Management)
155	- [](Build-SystemBuild-System](Build-System](Build-System)
156	- [](Architecture-OverviewArchitecture-Overview](Architecture-Overview](Architecture-Overview)
157