## AI Master Prompt for Dolphin Progress Tracker SPA
### 1. PROJECT OVERVIEW
The Dolphin Progress Tracker is a Single Page Application (SPA) designed to serve the retro gaming and emulation community. Its primary purpose is to aggregate, track, and analyze progress reports and release notes for the Dolphin Emulator, a popular GameCube and Wii emulator. The application aims to solve the problem of fragmented information dissemination within the emulation community, where significant technical advancements and bug fixes are often buried within lengthy blog posts or forum threads. The core value proposition is to provide a centralized, searchable, and filterable platform that highlights key improvements, community-reported issues, and developer efforts, making it easier for users and developers to stay informed about the emulator's evolution. It specifically addresses the need for a structured way to consume updates like the Dolphin Progress Report Release 2603, which introduced Triforce arcade emulation, MMU optimizations, and critical physics bug fixes.
### 2. TECH STACK
* **Frontend Framework:** React.js (v18+)
* **State Management:** Zustand (for global state management, simplicity, and performance)
* **Routing:** React Router DOM (for client-side navigation)
* **UI Styling:** Tailwind CSS (for rapid, utility-first styling and responsive design)
* **API/Data Fetching:** Axios (for HTTP requests) and React Query (for caching, background updates, and simplifying server state management)
* **Component Library (Optional but Recommended):** Headless UI or Radix UI (for accessible, unstyled UI primitives to build upon with Tailwind)
* **Date Handling:** date-fns (lightweight and modular date utility library)
* **Build Tool:** Vite (for fast development server and optimized builds)
* **Deployment Target:** Vercel or Netlify (for seamless SPA deployment)
### 3. CORE FEATURES & USER FLOWS
**A. Release Notes Aggregation & Display:**
* **Description:** Automatically fetches and displays Dolphin Emulator's official progress reports and release notes.
* **User Flow:** Upon loading the app, the latest release notes are fetched and displayed prominently. Users can scroll down to view older releases. Each release entry should show the title, author(s), publication date, and a concise summary. Clicking on a release title or a "Read More" button expands the entry to show the full content and potentially links to the original source (forum thread, blog post).
**B. Advanced Filtering & Search:**
* **Description:** Allows users to filter release notes by keywords (e.g., 'performance', 'MMU', 'physics', 'Triforce'), date range, and specific authors.
* **User Flow:** A dedicated filter/search bar is present at the top. Users can type keywords into the search input. Dropdown menus or tag-based selectors allow choosing filters for date ranges (e.g., 'Last Month', 'This Year', Custom Range) and authors. Applying filters dynamically updates the displayed list of release notes without a full page reload.
**C. Community Discussion & Commenting:**
* **Description:** Enables users to discuss specific release notes or emulator issues.
* **User Flow:** Each release note entry has a "Discussions" or "Comments" section. Users can view existing comments sorted by date or relevance. Authenticated users (basic email/password or OAuth) can post new comments, reply to existing ones, and potentially upvote/downvote comments. The discussion section should be threaded.
**D. Issue Tracking Integration (Conceptual MVP):**
* **Description:** Links community discussions to specific bug fixes mentioned in the release notes. MVP focuses on manual linking or keyword association.
* **User Flow:** Within a release note's discussion, users or moderators can tag comments or discussions with specific issues mentioned in the notes (e.g., "Fixes bug related to Rogue Squadron III physics"). This creates a connection, allowing users to see community sentiment or related discussions for specific fixes.
**E. Notification System:**
* **Description:** Notifies users about new releases or significant updates based on their preferences.
* **User Flow:** Users can opt-in to notifications. They can configure preferences, such as receiving alerts for releases containing specific keywords or only for major/major-type releases. Notifications appear as in-app alerts or can be configured for email delivery (future enhancement).
### 4. UI/UX DESIGN
* **Layout:** Single-column layout for main content on larger screens, stacking vertically on smaller screens. A persistent header contains the app title/logo, search bar, and navigation/user controls. A sidebar (collapsible on mobile) could house filters or secondary navigation.
* **Color Palette:** A dark theme primarily, evoking a sense of technical depth and focus. Primary colors: Deep blues (`#0A192F`), dark grays (`#1E2A3A`), with accent colors like a vibrant cyan (`#61DAFB` - for React association) or a subtle orange (`#F57C00`) for calls to action and highlights. White/light gray (`#E0E0E0`) for text.
* **Typography:** A clean, readable sans-serif font like Inter or Manrope for body text. A slightly more distinct font for headings (e.g., Poppins). Font sizes should be responsive.
* **Component Hierarchy:** Header -> Filter/Search Bar -> Release List (each item is a ReleaseCard) -> Release Detail View (modal or separate page).
* **Responsiveness:** Mobile-first approach. Use Tailwind's responsive modifiers (`sm:`, `md:`, `lg:`) extensively. Ensure elements reflow and resize gracefully across all device sizes. Main content should be max-width constrained on large screens for readability.
* **Accessibility (a11y):** Use semantic HTML5 elements. Ensure proper ARIA attributes where necessary. Keyboard navigability for all interactive elements. Sufficient color contrast.
### 5. DATA MODEL (Zustand Store & Mock Data)
* **State Structure (`useStore`):**
```javascript
// Example using Zustand
import { create } from 'zustand';
const useStore = create((set) => ({
// Release Data
releases: [],
isLoadingReleases: false,
errorReleases: null,
fetchReleases: async () => {
set({ isLoadingReleases: true });
try {
// Replace with actual API call
const response = await axios.get('/api/releases');
set({ releases: response.data, isLoadingReleases: false });
} catch (error) {
set({ errorReleases: error, isLoadingReleases: false });
}
},
// Filters
searchTerm: '',
setDateFilter: (filter) => set({ dateFilter: filter }),
setKeywordFilter: (term) => set({ searchTerm: term }),
// ... other filters
// Comments (for a specific release)
comments: {},
fetchComments: async (releaseId) => {
// Fetch comments for releaseId
},
addComment: async (releaseId, commentData) => {
// Add comment
}
// User Auth (simplified)
user: null,
login: (userData) => set({ user: userData }),
logout: () => set({ user: null }),
}));
```
* **Mock Data Format (Release):**
```json
{
"id": "release_2603",
"title": "Dolphin Progress Report: Release 2603",
"authors": ["JosJuice", "JMC47", "MayImilae"],
"publishedDate": "2026-03-12T00:00:00Z",
"summary": "Adds Triforce arcade emulation, significant MMU performance optimizations, and fixes a long-standing physics bug in Mario Strikers Charged.",
"fullContent": "Dolphin started out as a GameCube emulator in 2003. In 2008, experimental Wii support was added. And now in 2026, Dolphin enters the realm of arcade emulation with support for the Triforce... (full text)",
"url": "https://dolphin-emu.org/blog/2026/03/12/progress-report-2603/",
"tags": ["Triforce", "Arcade", "MMU", "Optimization", "Physics Bug", "Mario Strikers Charged"]
}
```
* **Mock Data Format (Comment):**
```json
{
"id": "comment_123",
"releaseId": "release_2603",
"userId": "user_abc",
"username": "RetroGamer99",
"timestamp": "2026-03-13T10:30:00Z",
"text": "Amazing to see Triforce emulation finally added! Hope it runs well.",
"parentId": null // for threading
}
```
### 6. COMPONENT BREAKDOWN
* **`App.jsx`:** Main application component. Sets up routing, global layout, and theme provider.
* `Props`: None
* `Responsibility`: Root component, routing setup.
* **`Header.jsx`:** Persistent header bar.
* `Props`: `appTitle` (string), `user` (object | null)
* `Responsibility`: Branding, global search, user auth status.
* **`SearchBar.jsx`:** Input component for filtering releases.
* `Props`: `onSearch` (function)
* `Responsibility`: Captures user search input and triggers search/filter action.
* **`FilterPanel.jsx`:** Contains various filter controls (date, author, tags).
* `Props`: `availableAuthors` (array), `onFilterChange` (function)
* `Responsibility`: Manages and applies complex filtering logic.
* **`ReleaseList.jsx`:** Displays a list of `ReleaseCard` components.
* `Props`: `releases` (array)
* `Responsibility`: Renders the list of releases, handles loading/empty states.
* **`ReleaseCard.jsx`:** Represents a single release note entry in the list.
* `Props`: `release` (object - see mock data format)
* `Responsibility`: Displays summary info, provides interaction for viewing details.
* **`ReleaseDetailModal.jsx`:** Modal or view for displaying the full release content and comments.
* `Props`: `release` (object), `isOpen` (boolean), `onClose` (function)
* `Responsibility`: Shows full content, comments section, comment input.
* **`CommentSection.jsx`:** Displays and manages comments for a specific release.
* `Props`: `releaseId` (string), `comments` (array)
* `Responsibility`: Renders comments, handles new comment submission.
* **`CommentInput.jsx`:** Form for adding a new comment.
* `Props`: `releaseId` (string), `onAddComment` (function)
* `Responsibility`: Text input and submit button for comments.
* **`NotificationIndicator.jsx`:** Shows notification count/status.
* `Props`: `count` (number)
* `Responsibility`: Visual indicator for new notifications.
* **`LoadingSpinner.jsx`:** Generic loading indicator.
* `Props`: None
* `Responsibility`: Visual feedback during data fetching.
* **`AuthButtons.jsx`:** Login/Logout buttons.
* `Props`: `user` (object | null)
* `Responsibility`: Handles user authentication state display and actions.
### 7. ANIMATIONS & INTERACTIONS
* **Page Transitions:** Subtle fade-in/fade-out transitions between major views (e.g., list to detail view) using `Framer Motion` or CSS transitions.
* **List Loading:** When fetching releases, display skeleton `ReleaseCard` components or a prominent `LoadingSpinner`. A shimmer effect on skeleton cards is ideal.
* **Hover Effects:** Subtle background color change or slight scale-up on `ReleaseCard` elements when hovered.
* **Button Interactions:** Slight press effect (scale down or color change) on buttons.
* **Comment Submission:** Show a temporary "Sending..." state and then fade in the new comment with a subtle animation upon successful submission.
* **Filter Application:** Smoothly animate the filtering process – cards can fade out and new ones fade in, or the list can reorder with a subtle animation.
* **Modal Transitions:** Smooth slide-in/fade-in for `ReleaseDetailModal`.
### 8. EDGE CASES & ERROR HANDLING
* **No Releases Found:** Display a clear message like "No release notes found matching your criteria." when the filtered list is empty.
* **API Errors:** Gracefully handle network errors during data fetching (releases, comments). Display user-friendly error messages (e.g., "Could not load release notes. Please check your connection or try again later.") and provide a "Retry" button.
* **Empty States:** For comments, display "Be the first to comment." when no comments exist for a release.
* **Validation:** If implementing user registration/login, validate email formats, password strength, etc. For comments, prevent empty submissions.
* **Accessibility:** Ensure all interactive elements are focusable and operable via keyboard. Use `aria-live` regions for dynamic content updates (like new comments appearing).
* **Long Content:** Implement ellipses (...) and a "Read More" button for excessively long `fullContent` fields in `ReleaseCard` to maintain list readability. Ensure the full content is accessible in the detail view.
* **Data Integrity:** Handle cases where release data might be malformed (missing fields). Use default values or skip rendering problematic fields.
### 9. SAMPLE DATA (Included in Data Model Section)
See the **Mock Data Format (Release)** and **Mock Data Format (Comment)** examples provided in the Data Model section above. Ensure the API response structure mirrors these formats. Include at least 5-10 diverse release entries in the initial mock data for testing filtering and display.
### 10. DEPLOYMENT NOTES
* **Build Command:** Use Vite's build command (`npm run build` or `yarn build`). Ensure the output directory is configured correctly for static hosting.
* **Environment Variables:** Utilize environment variables for API endpoints (`VITE_API_URL`), feature flags, etc. (`.env` files for local development, Vercel/Netlify environment variable settings for deployment).
* **Routing:** Configure the hosting provider for SPA routing. For Vercel, this is usually automatic or handled via `vercel.json`. For Netlify, use `_redirects` file or `netlify.toml` to redirect all non-file requests to `index.html`.
* **Performance Optimizations:**
* Code Splitting: Vite/React handles this well by default. Ensure dynamic imports for large components or routes not needed immediately.
* Image Optimization: If applicable, use optimized image formats and lazy loading.
* Memoization: Use `React.memo`, `useMemo`, `useCallback` judiciously to prevent unnecessary re-renders.
* Bundle Analysis: Use tools like `rollup-plugin-visualizer` to analyze bundle size and identify potential optimizations.
* **CORS:** Ensure the backend API (if separate) correctly handles Cross-Origin Resource Sharing (CORS) headers to allow requests from the deployed frontend domain.