PROJECT OVERVIEW:
Develop a single-page application (SPA) called "Change Detective" (Değişiklik Dedektifi) that acts as a smart web monitoring and notification tool. The core problem it solves is users missing critical, time-sensitive information on webpages due to manual checking or delayed notifications. This application automates the process of watching specific elements on any webpage, detecting changes, providing a clear diff view of what changed, storing historical snapshots, and notifying users via multiple channels like RSS, browser push notifications, email, and Telegram. The primary value proposition is to save users time and prevent missed opportunities (e.g., visa appointments, product stock, price drops, news updates) by delivering targeted information changes directly to them.
TECH STACK:
- Frontend Framework: React (using Create React App or Vite for a streamlined setup)
- State Management: Zustand (lightweight and efficient for SPA state management)
- Styling: Tailwind CSS (for rapid UI development and a utility-first approach)
- Routing: React Router DOM (for navigating between different views within the SPA)
- Icons: Heroicons (or similar for clean, accessible SVG icons)
- Notifications: Browser Push API (for Chrome/Firefox extensions), potentially a service worker for background updates. For email/Telegram, backend integration will be needed (out of scope for MVP frontend, but planned).
- Web Scraping/Monitoring Logic: This will involve a combination of frontend JavaScript for the browser extension and potentially a backend service for more robust, always-on monitoring (MVP focuses on browser extension capabilities).
- API Communication: Axios (for making HTTP requests if a backend API is introduced later).
CORE FEATURES:
1. **Element Watching & Picker:**
* **User Flow:** User navigates to a webpage, clicks a browser extension icon. An "Element Picker" mode is activated. The user hovers over different elements on the page; these elements are visually highlighted. Clicking an element selects it. The user can then name this "watch" and specify a trigger (e.g., "any change", "text contains X", "text does not contain Y").
* **Detail:** The extension injects a script to identify the selected element's unique selector (e.g., CSS selector, XPath). This selector, along with the URL and watch name, is stored.
2. **Change Detection & Diff View:**
* **User Flow:** The extension periodically re-scrapes the target element on the watched page. It compares the current content with the previously stored content. If a difference is detected, it flags the watch as "changed". The user can click on a changed watch in the extension popup or dashboard to view a "Diff View".
* **Detail:** The Diff View will use a library like `diff-match-patch` or a similar visual diffing tool to highlight added/removed text within the element's content. It will also provide access to a timeline of historical snapshots.
3. **Snapshot Timeline:**
* **User Flow:** Within the Diff View or a dedicated "History" section for a watch, the user can see a list of past states/snapshots. Selecting a snapshot shows the exact content of the element at that specific time.
* **Detail:** Stores a history of element content (or full page/relevant DOM structure) associated with each watch.
4. **RSS Feed Generation:**
* **User Flow:** Users can generate an RSS feed URL for individual watches, tags, or all their watches combined. Subscribing to this feed in any RSS reader will provide updates whenever a change is detected.
* **Detail:** This primarily requires a backend component to generate valid RSS XML. For the MVP frontend, we can simulate this by displaying the recent changes in a list format that resembles an RSS feed.
5. **Notification System (MVP Focus: Browser Push):**
* **User Flow:** When a change is detected, the browser extension triggers a push notification to the user's desktop (if permission is granted).
* **Detail:** Utilizes the browser's Push API. For email/Telegram, this would require backend hooks.
6. **Web Dashboard:**
* **User Flow:** A separate web interface (accessible via a unique URL) where users can view all their watches, manage them (edit, delete, add tags), view diffs, access the snapshot timeline, and manage notification settings.
* **Detail:** This SPA will serve as the central management hub.
UI/UX DESIGN:
- **Layout:** Single Page Application structure. Main views include: Dashboard (list of watches), Watch Detail (diff, history, settings), Add/Edit Watch form. The browser extension will have a popup view for quick actions (add watch, view recent changes).
- **Color Palette:** Primary: A calming, trustworthy blue (e.g., `#3b82f6`). Secondary: A neutral gray for backgrounds and borders (e.g., `#f3f4f6`). Accent: A warning/attention color like orange or yellow for detected changes (e.g., `#f97316`). Text: Dark gray or black for readability (e.g., `#1f2937`).
- **Typography:** Clean, sans-serif font like Inter or Roboto for excellent readability on screens. Use varying weights for hierarchy.
- **Responsive Design:** The web dashboard must be fully responsive, adapting seamlessly to desktop, tablet, and mobile screen sizes. Use Tailwind's responsive modifiers (sm:, md:, lg:).
- **Extension UI:** Clean, minimal popup and options/popup pages within the browser extension framework.
COMPONENT BREAKDOWN:
- `App.js`: Main application component, sets up routing.
- `DashboardPage.js`: Displays the list of all watches. Fetches watch data. Includes `WatchList.js` and `AddWatchButton.js`.
- `WatchList.js`: Renders a list of `WatchListItem` components.
- `WatchListItem.js`: Displays a single watch summary (name, URL, last change, status). Handles tag display/filtering. Links to `WatchDetailPage`.
- `AddWatchButton.js`: Button to initiate the watch creation process (opens extension picker or form).
- `AddEditWatchForm.js`: Form for adding/editing watch details (URL, selector, name, tags, notification prefs). Includes `ElementPickerTrigger.js`.
- `ElementPickerTrigger.js`: Button/component to activate the element picker in the browser extension.
- `WatchDetailPage.js`: Displays detailed information for a single watch. Includes `DiffViewer.js`, `SnapshotTimeline.js`, `NotificationSettings.js`.
- `DiffViewer.js`: Component to display the differences between two versions of content. Takes `oldContent` and `newContent` as props.
- `SnapshotTimeline.js`: Displays a chronological list of past snapshots for a watch. Allows selection to view content.
- `NotificationSettings.js`: UI for configuring notification preferences (browser push, email, Telegram - placeholder for MVP).
- `ExtensionPopup.js`: The UI for the browser extension popup.
- `ExtensionElementPicker.js`: The UI and logic for the element picker within the extension.
- `Layout.js`: Wrapper component for consistent header/footer/sidebar.
- `LoadingSpinner.js`: Reusable loading indicator.
- `ErrorMessage.js`: Component for displaying errors.
DATA MODEL:
- `Watch` object:
```json
{
"id": "unique_watch_id",
"url": "https://example.com/page",
"selector": ".product-price", // CSS Selector
"name": "Product Price",
"tags": ["ecommerce", "price-alert"],
"lastChanged": "2023-10-27T10:30:00Z",
"status": "changed" | "no_change" | "error",
"notificationSettings": {
"browserPush": true,
"email": false,
"telegram": false
}
}
```
- `Snapshot` object:
```json
{
"id": "unique_snapshot_id",
"watchId": "unique_watch_id",
"timestamp": "2023-10-27T10:30:00Z",
"content": "<p>$19.99</p>" // HTML content of the selected element
}
```
- **State Management (Zustand):** A central store `useWatchStore` will manage the array of `Watch` objects and the array of `Snapshot` objects. Actions will include `addWatch`, `removeWatch`, `updateWatch`, `fetchWatches`, `addSnapshot`, `fetchSnapshotsForWatch`.
- **Local Storage:** The browser extension will use `chrome.storage.local` or `browser.storage.local` to persist the list of watches and recent snapshots, enabling functionality even when the dashboard is closed. The web app might use its own state or a simple local storage for initial setup.
ANIMATIONS & INTERACTIONS:
- **Hover Effects:** Subtle background color changes or slight scaling on list items (`WatchListItem`) and buttons for interactive feedback.
- **Transitions:** Smooth transitions for opening/closing the extension popup, expanding/collapsing sections in the dashboard, and route changes within the SPA.
- **Loading States:** Display `LoadingSpinner.js` components while fetching data (watches, snapshots). Disable buttons or show a loading state during actions like saving a watch.
- **Micro-interactions:** Visual feedback when an element is successfully picked, a watch is saved, or a notification is sent.
- **Diff View:** Highlight changes with distinct background colors (e.g., green for additions, red for deletions) within the diff.
EDGE CASES:
- **No Watches:** The dashboard should display a helpful message and a clear call-to-action (e.g., "You have no watches yet. Click here to add one!").
- **Element Not Found:** If the selected element selector becomes invalid on the target page, the watch status should update to "error", and an informative message should be displayed.
- **Website Blocking Scrapers:** Some websites may implement measures against scraping. The tool should handle potential errors gracefully, perhaps with retry logic or by informing the user.
- **Empty Content:** If the watched element is empty, handle this state appropriately in the diff view and history.
- **Error Handling:** Implement try-catch blocks for all asynchronous operations (API calls, storage access). Display user-friendly error messages using `ErrorMessage.js`.
- **Validation:** Validate URL formats, ensure selectors are not excessively broad, and check for required fields in forms.
- **Accessibility (a11y):** Ensure proper semantic HTML, ARIA attributes where necessary, keyboard navigability for all interactive elements, and sufficient color contrast.
- **Extension Permissions:** Clearly request only necessary permissions and explain why they are needed.
SAMPLE DATA:
1. **Watch List (Dashboard):**
```json
[
{
"id": "w1",
"url": "https://www.example.com/product/123",
"selector": ".price-tag",
"name": "Example Product Price",
"tags": ["ecommerce", "price"],
"lastChanged": "2023-10-26T15:00:00Z",
"status": "changed"
},
{
"id": "w2",
"url": "https://www.gov.nl/visa-appointment",
"selector": "#appointment-status",
"name": "Visa Appointment Slot",
"tags": ["important", "travel"],
"lastChanged": null,
"status": "no_change"
},
{
"id": "w3",
"url": "https://news.example.com/latest",
"selector": "h1.headline",
"name": "Latest News Headline",
"tags": ["news"],
"lastChanged": "2023-10-27T09:15:00Z",
"status": "changed"
}
]
```
2. **Snapshots for Watch `w1`:**
```json
[
{
"id": "s1-1",
"watchId": "w1",
"timestamp": "2023-10-26T14:00:00Z",
"content": "<span class=\"price-tag\">$24.99</span>"
},
{
"id": "s1-2",
"watchId": "w1",
"timestamp": "2023-10-26T15:00:00Z",
"content": "<span class=\"price-tag\">$19.99</span>"
}
]
```
3. **Single Watch (for Edit Form):**
```json
{
"id": "w1",
"url": "https://www.example.com/product/123",
"selector": ".price-tag",
"name": "Example Product Price",
"tags": ["ecommerce", "price"],
"notificationSettings": {
"browserPush": true,
"email": false,
"telegram": false
}
}
```
DEPLOYMENT NOTES:
- **Build:** Use `npm run build` (or `yarn build`) for production builds. Configure environment variables for API endpoints if a backend is introduced.
- **Environment Variables:** For the browser extension, API keys or base URLs might be needed. For the web app, manage API endpoints or feature flags.
- **Performance Optimizations:** Code splitting for React Router, memoization (React.memo, useMemo, useCallback) where appropriate, image optimization, and efficient state management updates.
- **Extension Packaging:** Follow Chrome/Firefox extension development guidelines for packaging and publishing.
- **CORS:** Ensure backend API (if used) handles Cross-Origin Resource Sharing correctly.
- **Hosting:** The SPA can be hosted on Netlify, Vercel, or similar static hosting platforms. The browser extension is published on the respective web stores.