PROJECT OVERVIEW:
This project aims to build a single-page application (SPA) called 'E-posta Bağımsızlık Platformu' (Email Independence Platform). The core purpose of this platform is to facilitate micro-donations from users to privacy-focused, non-ad-supported, and non-data-selling email clients, with an initial focus on Thunderbird. The problem statement stems from the realization that many valuable, user-centric open-source projects rely on user contributions due to a lack of corporate funding or aggressive advertising. This platform provides a streamlined, secure, and transparent way for users who value these principles to contribute financially, ensuring the continued development and maintenance of essential software like Thunderbird. The value proposition lies in empowering users to actively support the software they use and depend on, fostering a sustainable ecosystem for privacy-respecting digital tools.
TECH STACK:
- Frontend Framework: React (using Create React App or Vite for scaffolding)
- Styling: Tailwind CSS for rapid UI development and utility-first styling.
- State Management: Zustand or React Context API for managing application state.
- Routing: React Router DOM for navigation within the SPA.
- Payment Gateway Integration: Stripe SDK (or a similar service like PayPal API) for secure donation processing.
- Icons: Heroicons or Font Awesome for UI elements.
- Forms: React Hook Form for efficient form handling and validation.
- Animations: Framer Motion for smooth transitions and micro-interactions.
- Utility Libraries: Lodash (optional) for utility functions, date-fns for date formatting.
CORE FEATURES:
1. **Project Selection & Information Display:**
* **User Flow:** Upon landing on the page, users see a prominent section showcasing the primary supported project (e.g., Thunderbird). This section displays the project's logo, a brief mission statement emphasizing privacy and user control, and a clear call-to-action to donate. If multiple projects are supported in the future, a project selection carousel or list would be available.
* **Details:** Each project card will display its name, a short description, its current funding goal (if applicable), and a visual progress bar indicating the percentage of the goal achieved.
2. **Donation Form:**
* **User Flow:** Clicking the 'Donate' button on a project card/section leads to a donation form. The form allows users to choose between a one-time donation or a recurring monthly donation. They can select a predefined amount (e.g., $5, $10, $25) or enter a custom amount. Users then enter their payment information (handled securely via Stripe Elements).
* **Details:** The form will include input fields for amount, recurrence (one-time/monthly), and a secure payment input integrated with Stripe Elements (Card Number, Expiry, CVC). A confirmation step before final submission is crucial.
3. **Payment Processing:**
* **User Flow:** After the user submits the donation form, the application securely sends the payment details to the Stripe API (using a backend proxy or directly if configured for client-side integration). Upon successful payment confirmation from Stripe, the user sees a success message, and the donation is recorded. If payment fails, an appropriate error message is displayed.
* **Details:** This involves setting up Stripe API keys (publishable and secret), integrating Stripe Elements for PCI compliance, and handling success/error callbacks.
4. **Donation Confirmation & Thank You:**
* **User Flow:** Upon successful donation, the user is redirected to a thank-you page or shown a success modal. This page reiterates the donation amount, the project supported, and expresses gratitude. It might also include a brief message about the impact of their contribution.
* **Details:** This screen should be visually appealing and reinforce the positive action taken by the user. It could also offer social sharing options.
5. **Progress Tracking (Project Dashboard):**
* **User Flow:** A dedicated section (or integrated into the main project display) shows the real-time progress of funding goals for each supported project. This includes total amount raised, percentage of goal achieved, and potentially the number of active recurring donors.
* **Details:** This requires fetching funding data (either mock data for MVP or real data via an API if available/developed) and updating the UI dynamically.
UI/UX DESIGN:
- **Layout:** A clean, single-page layout. A fixed header with the app logo and navigation (if needed later). The main content area will display the project(s) and donation form. A footer with essential links (About, Privacy Policy, Contact).
- **Color Palette:** A calming and trustworthy color scheme. Primary colors: A deep, professional blue (#1e3a8a) or a dark teal (#0e7490) for accents and calls-to-action. Secondary colors: Light grays (#f3f4f6) for backgrounds, white (#ffffff) for text and cards. Accent color: A slightly brighter, encouraging color like a soft green (#10b981) or orange (#f97316) for progress bars and success indicators.
- **Typography:** Clean, readable sans-serif fonts. 'Inter' or 'Roboto' for body text and UI elements. A slightly more distinct font for headings (e.g., 'Poppins' or 'Montserrat'). Ensure good contrast ratios.
- **Responsive Design:** Mobile-first approach. Components should adapt fluidly to different screen sizes. Use Tailwind CSS's responsive modifiers (sm:, md:, lg:, xl:). Ensure touch targets are adequately sized on mobile devices.
- **Component Hierarchy:** Header -> MainContent (ProjectDisplay -> DonationForm) -> Footer. DonationForm will contain inputs, recurrence selector, and payment elements.
COMPONENT BREAKDOWN:
1. `App.js` (or `main.jsx`): Root component, sets up routing and global layout.
* Props: None
* Responsibility: Main application container, routing setup.
2. `Header.js`:
* Props: `logoUrl`, `title`
* Responsibility: Displays the application logo and title.
3. `ProjectDisplay.js`:
* Props: `project` (object containing name, description, imageUrl, fundingGoal, currentFunding)
* Responsibility: Shows information about the supported project, including progress bar.
4. `ProgressBar.js`:
* Props: `percentage` (number), `color` (string)
* Responsibility: Visualizes the funding progress.
5. `DonationForm.js`:
* Props: `projectId` (string), `onDonationSuccess` (function)
* Responsibility: Contains the donation input fields, recurrence options, and submit button. Integrates with Stripe Elements.
6. `Input.js` (or `TextField.js`): Reusable input component.
* Props: `label`, `type`, `name`, `value`, `onChange`, `error`
* Responsibility: Styled input field with label and error handling.
7. `Button.js`:
* Props: `children`, `onClick`, `variant` (primary, secondary), `isLoading` (boolean)
* Responsibility: Reusable button component with different styles and loading state.
8. `PaymentForm.js`:
* Props: `stripe` (Stripe object), `elements` (Stripe Elements object), `onSubmit` (function), `isLoading` (boolean)
* Responsibility: Renders Stripe's card input elements and handles submission logic.
9. `SuccessMessage.js`:
* Props: `donationDetails` (object containing amount, project name)
* Responsibility: Displays a confirmation message after a successful donation.
10. `Footer.js`:
* Props: None
* Responsibility: Displays footer links and copyright information.
DATA MODEL:
- **`Project` Interface/Type:**
```typescript
interface Project {
id: string;
name: string;
description: string;
imageUrl: string;
fundingGoal: number;
currentFunding: number;
isRecurringSupported: boolean;
}
```
- **`Donation` Interface/Type:**
```typescript
interface Donation {
id: string;
projectId: string;
amount: number;
currency: string;
isRecurring: boolean;
timestamp: Date;
status: 'pending' | 'success' | 'failed';
}
```
- **State Management:**
* `projectsState`: An array of `Project` objects. Initialized with mock data. Fetchable from an API in a real scenario.
* `selectedProjectId`: String, the ID of the project the user is currently interacting with.
* `donationState`: Object to hold form data (amount, recurrence) and payment status.
* `isLoading`: Boolean, for global loading indicators.
* `error`: String or null, for displaying error messages.
- **Local Storage:** Could be used to store user preferences or past donation summaries (optional for MVP).
ANIMATIONS & INTERACTIONS:
- **Page Transitions:** Subtle fade-in/fade-out transitions using Framer Motion when navigating between sections or displaying modals.
- **Button Hovers:** Slight scale-up or color change on button hover states.
- **Progress Bar Animation:** Animate the filling of the progress bar as funding increases (or upon initial load).
- **Form Element Interactions:** Subtle focus styling on input fields.
- **Loading States:** Use skeletons or spinners (`Button` component's `isLoading` prop) when fetching data or processing payments.
- **Micro-interactions:** A small animation on the 'Donate' button click to provide visual feedback.
EDGE CASES:
- **Empty State:** If no projects are available or loaded, display a user-friendly message (e.g., "No projects available for support at the moment.").
- **Error Handling:** Gracefully handle API errors (e.g., network issues, payment gateway failures) by displaying informative messages to the user. Implement retry mechanisms where appropriate.
- **Validation:** Client-side and server-side validation for donation amounts (e.g., minimum amount, positive numbers only). Email format validation if email capture is implemented.
- **Payment Failures:** Clearly communicate payment failures to the user, providing reasons if possible (e.g., insufficient funds, incorrect card details), and guide them on how to retry or use a different payment method.
- **Accessibility (a11y):** Use semantic HTML5 elements. Ensure proper ARIA attributes, keyboard navigation, focus management, and sufficient color contrast. All interactive elements should be focusable and usable via keyboard.
- **Security:** Never store raw payment details on the client or server. Rely entirely on the payment gateway's secure elements and tokenization process. Sanitize all user inputs.
SAMPLE DATA:
1. **`mockProjects` Array:**
```javascript
[
{
id: 'thunderbird',
name: 'Thunderbird E-posta İstemcisi',
description: 'Gizlilik odaklı, özgür ve açık kaynaklı e-posta istemcisi. Verilerinizi asla satmayız veya reklam göstermeyiz.',
imageUrl: 'https://example.com/thunderbird-logo.png', // Placeholder
fundingGoal: 50000,
currentFunding: 22500,
isRecurringSupported: true
},
{
id: 'other-client',
name: 'Gizli İletişim Aracı',
description: 'Uçtan uca şifrelemeli, güvenli mesajlaşma ve dosya paylaşım platformu.',
imageUrl: 'https://example.com/other-logo.png', // Placeholder
fundingGoal: 75000,
currentFunding: 15000,
isRecurringSupported: true
}
]
```
2. **`mockDonationSuccess` Object:**
```json
{
"donationId": "txn_123abc456def",
"projectId": "thunderbird",
"amount": 15.00,
"currency": "USD",
"isRecurring": false,
"timestamp": "2023-10-27T10:30:00Z",
"status": "success"
}
```
3. **`mockPaymentError` Object:**
```json
{
"code": "card_declined",
"message": "Your card was declined. Please try a different card or contact your bank.",
"status": "failed"
}
```
4. **`mockEmptyStateMessage`:**
`"No projects currently available for donations. Please check back later."`
5. **`mockRecurringDonationSetup` Object:**
```json
{
"subscriptionId": "sub_789xyz123uvw",
"projectId": "thunderbird",
"amount": 10.00,
"currency": "USD",
"interval": "month",
"status": "active"
}
```
DEPLOYMENT NOTES:
- **Build:** Use `npm run build` or `yarn build` for production build.
- **Environment Variables:** Store sensitive keys like `STRIPE_PUBLISHABLE_KEY` and `STRIPE_SECRET_KEY` (for backend communication) in `.env` files. Ensure these are set correctly in the deployment environment (e.g., Vercel, Netlify).
- **Performance Optimizations:** Code splitting with React.lazy and Suspense. Optimize images. Use memoization (React.memo, useMemo, useCallback) where appropriate. Ensure efficient state management to prevent unnecessary re-renders.
- **HTTPS:** Always serve the application over HTTPS.
- **CORS:** If using a separate backend for Stripe secret key handling, configure CORS correctly.
- **Stripe Webhooks:** Implement webhook handlers on a backend service to securely manage subscription events and payment confirmations.