Skip to content

Commit de11187

Browse files
whatsupsumitwhatsupsumit
committed
docs: Add implementation summary and flow diagrams for feedback feature
1 parent b8c7f86 commit de11187

2 files changed

Lines changed: 668 additions & 0 deletions

File tree

‎FEEDBACK_FLOW_DIAGRAM.md‎

Lines changed: 324 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,324 @@
1+
# User Feedback Flow Diagram
2+
3+
## Architecture Overview
4+
5+
```
6+
┌─────────────────────────────────────────────────────────────────┐
7+
│ USER INTERACTION │
8+
└─────────────────────────────────────────────────────────────────┘
9+
│
10+
▼
11+
┌──────────────────────────────────────────┐
12+
│ User selects code on webpage │
13+
│ Extension translates code │
14+
└──────────────────────────────────────────┘
15+
│
16+
▼
17+
┌──────────────────────────────────────────┐
18+
│ UI shows translated code with buttons: │
19+
│ ┌──────┐ ┌────┐ ┌────┐ │
20+
│ │ Copy │ │ 👍 │ │ 👎 │ │
21+
│ └──────┘ └────┘ └────┘ │
22+
└──────────────────────────────────────────┘
23+
│ │
24+
│ │
25+
┌───────────┘ └──────────┐
26+
▼ ▼
27+
┌───────────────┐ ┌──────────────────┐
28+
│ User clicks 👍│ │ User clicks 👎 │
29+
└───────────────┘ └──────────────────┘
30+
│ │
31+
▼ ▼
32+
┌───────────────┐ ┌──────────────────┐
33+
│ Instant │ │ Modal opens: │
34+
│ submission │ │ ┌──────────────┐ │
35+
│ │ │ │ "What was │ │
36+
│ │ │ │ wrong?" │ │
37+
│ │ │ │ │ │
38+
│ │ │ │ [Textarea] │ │
39+
│ │ │ │ │ │
40+
│ │ │ │ [Cancel][OK] │ │
41+
│ │ │ └──────────────┘ │
42+
└───────────────┘ └──────────────────┘
43+
│ │
44+
│ ▼
45+
│ ┌──────────────────┐
46+
│ │ User enters │
47+
│ │ optional comment │
48+
│ │ & clicks Submit │
49+
│ └──────────────────┘
50+
│ │
51+
└─────────────┬───────────────────────┘
52+
▼
53+
┌──────────────────────────────────────┐
54+
│ sendFeedback() called │
55+
│ - Collects data │
56+
│ - Sends to background.js │
57+
└──────────────────────────────────────┘
58+
│
59+
▼
60+
┌──────────────────────────────────────┐
61+
│ background.js │
62+
│ - Receives SUBMIT_FEEDBACK message │
63+
│ - POSTs to /v1/feedback endpoint │
64+
└──────────────────────────────────────┘
65+
│
66+
▼
67+
┌──────────────────────────────────────┐
68+
│ Backend (Cloudflare Worker) │
69+
│ POST /v1/feedback │
70+
│ - Validates data │
71+
│ - Generates unique ID │
72+
│ - Stores in KV with metadata │
73+
└──────────────────────────────────────┘
74+
│
75+
▼
76+
┌──────────────────────────────────────┐
77+
│ Cloudflare KV Storage │
78+
│ FEEDBACK_STORE │
79+
│ ┌────────────────────────────────┐ │
80+
│ │ Key: feedback_<timestamp>_<id> │ │
81+
│ │ Value: { │ │
82+
│ │ isPositive, │ │
83+
│ │ targetLanguage, │ │
84+
│ │ originalCode, │ │
85+
│ │ translatedCode, │ │
86+
│ │ comment, │ │
87+
│ │ timestamp │ │
88+
│ │ } │ │
89+
│ └────────────────────────────────┘ │
90+
└──────────────────────────────────────┘
91+
│
92+
▼
93+
┌──────────────────────────────────────┐
94+
│ Response to Extension │
95+
│ { success: true, feedbackId } │
96+
└──────────────────────────────────────┘
97+
│
98+
▼
99+
┌──────────────────────────────────────┐
100+
│ UI Visual Feedback │
101+
│ - Button highlights briefly │
102+
│ - Modal closes (if open) │
103+
└──────────────────────────────────────┘
104+
```
105+
106+
## Data Flow
107+
108+
### Positive Feedback (👍)
109+
```
110+
User Click → sendFeedback(true) → background.js → Backend → KV Store
111+
↓
112+
Button highlights for 2s
113+
```
114+
115+
### Negative Feedback (👎)
116+
```
117+
User Click → Modal Opens
118+
↓
119+
User enters comment (optional)
120+
↓
121+
Click Submit → sendFeedback(false, comment) → background.js → Backend → KV Store
122+
↓
123+
Modal closes + Button highlights for 2s
124+
```
125+
126+
## Component Interaction
127+
128+
```
129+
┌─────────────────────────────────────────────────────────────┐
130+
│ FRONTEND (Extension) │
131+
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
132+
│ │ ui.js │ │ content.js │ │ background.js │ │
133+
│ │ │ │ │ │ │ │
134+
│ │ - Buttons │◄─│ - Injects UI │ │ - Message │ │
135+
│ │ - Modal │ │ - Passes │ │ handler │ │
136+
│ │ - Feedback │ │ original │ │ - HTTP requests │ │
137+
│ │ logic │ │ code │ │ │ │
138+
│ └──────┬──────┘ └──────────────┘ └────────┬─────────┘ │
139+
│ │ │ │
140+
│ └─────────────────┬───────────────────┘ │
141+
│ │ │
142+
└───────────────────────────┼─────────────────────────────────┘
143+
│
144+
│ POST /v1/feedback
145+
│
146+
┌───────────────────────────▼─────────────────────────────────┐
147+
│ BACKEND (Cloudflare Worker) │
148+
│ ┌──────────────────────────────────────────────────────┐ │
149+
│ │ index.ts │ │
150+
│ │ ┌────────────────┐ ┌──────────────────────────┐ │ │
151+
│ │ │ handleFeedback │ │ FEEDBACK_STORE (KV) │ │ │
152+
│ │ │ │──┤ │ │ │
153+
│ │ │ - Validates │ │ Stores feedback data │ │ │
154+
│ │ │ - Creates ID │ │ with metadata │ │ │
155+
│ │ │ - Stores data │ │ │ │ │
156+
│ │ └────────────────┘ └──────────────────────────┘ │ │
157+
│ └──────────────────────────────────────────────────────┘ │
158+
└─────────────────────────────────────────────────────────────┘
159+
```
160+
161+
## State Diagram
162+
163+
```
164+
┌──────────────┐
165+
│ Code │
166+
│ Translated │
167+
└──────┬───────┘
168+
│
169+
▼
170+
┌──────────────┐
171+
│ Buttons │
172+
│ Visible │
173+
└───┬──────┬───┘
174+
│ │
175+
👍 │ │ 👎
176+
│ │
177+
│ ▼
178+
│ ┌────────────┐
179+
│ │ Modal │
180+
│ │ Open │
181+
│ └──┬─────┬───┘
182+
│ │ │
183+
│ Cancel Submit
184+
│ │ │
185+
│ ▼ │
186+
│ ┌────┐ │
187+
│ │Close│ │
188+
│ └────┘ │
189+
│ │
190+
└────┬─────┘
191+
│
192+
▼
193+
┌─────────────┐
194+
│ Sending │
195+
│ Feedback │
196+
└──────┬──────┘
197+
│
198+
▼
199+
┌─────────────┐ ┌──────────┐
200+
│ Success │ ───► │ Button │
201+
│ │ │ Highlight│
202+
└─────────────┘ └──────────┘
203+
```
204+
205+
## Files & Responsibilities
206+
207+
```
208+
frontend/
209+
│
210+
├── scripts/
211+
│ ├── ui.js
212+
│ │ ├── injectOrUpdateTranslations() [Creates UI with buttons]
213+
│ │ ├── sendFeedback() [Sends to background]
214+
│ │ └── showFeedbackModal() [Shows modal for 👎]
215+
│ │
216+
│ ├── content.js
217+
│ │ └── handleElementClick() [Passes originalCode]
218+
│ │
219+
│ └── background.js
220+
│ └── onMessage.listener [Handles SUBMIT_FEEDBACK]
221+
│ └── fetch(/v1/feedback) [POSTs to backend]
222+
│
223+
backend/
224+
│
225+
└── src/
226+
└── index.ts
227+
└── handleFeedback() [Validates & stores]
228+
└── FEEDBACK_STORE.put() [Saves to KV]
229+
```
230+
231+
## Error Handling
232+
233+
```
234+
┌──────────────┐
235+
│ User Action │
236+
└──────┬───────┘
237+
│
238+
▼
239+
┌──────────────────┐
240+
│ Try Submit │
241+
└──────┬───────────┘
242+
│
243+
├─ Success ──► Button highlights ──► Done
244+
│
245+
├─ Network Error ──► Console.error ──► Silent fail
246+
│
247+
└─ Backend Error ──► Console.error ──► Silent fail
248+
```
249+
250+
## Security Considerations
251+
252+
```
253+
Data Sanitization
254+
│
255+
├─ No PII collected
256+
├─ Code snippets only
257+
├─ Rate limiting applied
258+
└─ CORS configured
259+
│
260+
▼
261+
KV Storage
262+
│
263+
├─ Unique IDs
264+
├─ Metadata indexed
265+
└─ Timestamp tracked
266+
```
267+
268+
## Deployment Flow
269+
270+
```
271+
Development
272+
│
273+
├─ Create KV namespaces
274+
│ └─ wrangler kv:namespace create "FEEDBACK_STORE"
275+
│
276+
├─ Update wrangler.jsonc with IDs
277+
│
278+
├─ npm install
279+
│
280+
└─ npm run dev
281+
│
282+
▼
283+
Local Testing
284+
│
285+
▼
286+
Production
287+
│
288+
├─ npm run deploy (backend)
289+
│
290+
└─ Load extension (frontend)
291+
```
292+
293+
## Monitoring & Analysis
294+
295+
```
296+
Feedback Data
297+
│
298+
├─ Query by metadata
299+
│ ├─ isPositive: false (negative feedback)
300+
│ ├─ targetLanguage: "Python"
301+
│ └─ timestamp range
302+
│
303+
├─ Export for analysis
304+
│ └─ JSON/CSV format
305+
│
306+
└─ Identify patterns
307+
├─ Common issues
308+
├─ Language-specific problems
309+
└─ Improvement areas
310+
│
311+
▼
312+
Update AI Prompts
313+
│
314+
▼
315+
Improve Translation Quality
316+
```
317+
318+
---
319+
320+
**Legend:**
321+
- `│` : Flow direction
322+
- `┌─┐` : Components/Steps
323+
- `►` : Result/Output
324+
- `◄` : Input/Dependency

0 commit comments

Comments
 (0)