PROJECT OVERVIEW:
The application, tentatively named 'Digital Detox: Social Media Addiction Guide' (Dijital Detoks: Sosyal Medya Bağımlılığı Rehberi), aims to combat the growing problem of social media addiction. Inspired by recent news of Meta removing ads related to social media addiction litigation, this app provides users with tools to understand, monitor, and manage their social media usage. The core value proposition is empowering individuals to regain control over their digital lives, reduce screen time, and foster healthier online habits, ultimately improving mental well-being and productivity. This project will be developed as a single-page application (SPA) with a responsive design, accessible via both web browsers and mobile devices.
TECH STACK:
- Frontend Framework: React.js (v18+)
- Styling: Tailwind CSS (v3+) for utility-first styling and rapid UI development.
- State Management: Zustand for efficient global and local state management, suitable for SPAs.
- Routing: React Router DOM for navigation within the SPA.
- Charting Library: Recharts for creating interactive and visually appealing data visualizations.
- Date/Time Handling: date-fns for robust date and time manipulation.
- Form Handling: React Hook Form for efficient and performant form management.
- Icons: Heroicons for a clean and consistent icon set.
- Build Tool: Vite for fast development server and optimized builds.
- Deployment: Vercel or Netlify for seamless CI/CD and hosting.
CORE FEATURES:
1. **Usage Tracking Dashboard:**
* **User Flow:** Upon first launch, the app requests necessary permissions (if applicable on the platform, e.g., Screen Time API on iOS, Digital Wellbeing API on Android via a native wrapper, or manual input/browser extension for web). The dashboard displays a summary of the current day's social media usage, broken down by application. It shows total time spent, time on the top 3 most used apps, and a comparison to the user's set daily goals. It also includes a prominent visual representation (e.g., a progress ring or bar) of the remaining allowed time.
* **Details:** Includes daily, weekly, and monthly views. Users can toggle between these views. Data is fetched and updated periodically.
2. **Usage Analytics & Reports:**
* **User Flow:** Users navigate to the 'Analytics' section. They can view detailed reports on their social media consumption patterns over selected periods (week, month, year). Reports include average daily usage, peak usage times, most frequent apps, and trends over time.
* **Details:** Utilizes charts (bar charts for daily/weekly comparison, line charts for trends, pie charts for app distribution) to visualize data. Provides actionable insights based on the patterns observed (e.g., 'Your usage on Instagram increased by 15% this week. Consider setting a specific time limit for it.').
3. **Goal Setting & Limits:**
* **User Flow:** In the 'Goals' section, users can set daily time limits for individual social media apps or for overall social media usage. They can also set 'focus hours' during which certain apps are blocked or heavily restricted.
* **Details:** When a user approaches their limit, they receive a gentle notification. Upon exceeding the limit, the app can enforce the chosen action: a warning, temporary blocking of the app, or a full block until the next day/reset time. 'Focus Hours' can be scheduled for specific times (e.g., 9 AM - 12 PM on weekdays).
4. **Digital Detox Modes:**
* **User Flow:** Users can activate pre-defined 'Detox Modes' (e.g., 'Deep Work', 'Mindful Evening', 'Weekend Break') or create custom ones. These modes apply a combination of usage limits, app blocking, and notification silencing across selected applications for a set duration.
* **Details:** Provides a quick-access panel for activating/deactivating modes. Each mode can be customized to include specific apps, time durations, and notification settings. Offers a 'cool-down' period before a mode can be deactivated to prevent impulsive disabling.
5. **Tips & Resources:**
* **User Flow:** A dedicated 'Learn' or 'Resources' section offers curated articles, tips, and advice on managing digital habits, understanding social media's psychological impact, and practicing mindfulness.
* **Details:** Content is presented in a clean, readable format. Could include short videos, expert Q&As, or links to external reputable sources. Regularly updated content keeps users engaged.
UI/UX DESIGN:
- **Layout:** Single-page application with a persistent sidebar navigation for core sections (Dashboard, Analytics, Goals, Detox Modes, Resources, Settings). The main content area dynamically updates based on the selected section. A clean, minimalist aesthetic is prioritized.
- **Color Palette:** Primary colors: A calming blue (#4A90E2) for interactive elements and headers, a neutral dark grey (#282C34) for backgrounds, and lighter greys (#ABB2BF) for secondary text and borders. Accent colors: A vibrant green (#76D7C4) for progress indicators and success states, and a soft orange/red (#E57373) for warnings and exceeding limits.
- **Typography:** Modern, sans-serif fonts. 'Inter' for body text (readability) and 'Poppins' for headings (impact). Font sizes will be optimized for readability across devices (e.g., 16px base for body, 24-32px for headings).
- **Responsive Design:** Mobile-first approach. Sidebar collapses into a hamburger menu on smaller screens. Layout adjusts fluidly using Flexbox and Grid. Tailwind CSS responsive prefixes (sm:, md:, lg:) will be extensively used. All elements will be designed to function optimally on screen sizes from 320px to 1920px.
- **Interactions:** Smooth transitions between sections and data loading. Subtle hover effects on buttons and interactive elements. Visual feedback for user actions (e.g., button clicks, toggles).
COMPONENT BREAKDOWN:
- `App.js`: Main application component, sets up routing and global layout.
- `Layout.js`: Contains the persistent sidebar/header and the main content area wrapper.
- `Sidebar.js`: Navigation menu component. Displays links to different sections. Handles active link styling. Props: `navItems` (array of objects with `label` and `path`).
- `DashboardPage.js`: Main dashboard view. Fetches and displays usage data. Composes `UsageSummary`, `AppBreakdownChart`, `GoalProgress`.
- `UsageSummary.js`: Displays total usage time and remaining time for the day. Props: `totalTime`, `timeUsed`, `dailyLimit`.
- `AppBreakdownChart.js`: Chart showing usage per app. Uses Recharts. Props: `data` (array of { name: string, time: number }).
- `GoalProgress.js`: Visual indicator of progress towards daily goals. Props: `progress` (number 0-100).
- `AnalyticsPage.js`: Displays detailed usage reports and trends. Composes `DateRangePicker`, `TrendChart`, `AppDistributionPieChart`.
- `TrendChart.js`: Line or bar chart showing usage over time. Props: `data`, `chartType`.
- `AppDistributionPieChart.js`: Pie chart showing the distribution of usage among apps. Props: `data`.
- `GoalsPage.js`: Interface for setting and managing usage limits and focus hours. Composes `AppLimitSetter`, `FocusHoursScheduler`.
- `AppLimitSetter.js`: Component to set/edit time limits for individual apps. Props: `appName`, `currentLimit`, `onLimitChange`.
- `FocusHoursScheduler.js`: Component to define focus periods. Props: `schedule` (array of objects), `onScheduleChange`.
- `DetoxModesPage.js`: Interface for activating and customizing detox modes. Composes `ModeSelector`, `ModeConfigurator`.
- `ModeSelector.js`: Lists available detox modes. Props: `modes` (array), `onSelectMode`.
- `ResourcesPage.js`: Displays educational content. Props: `articles` (array of objects).
- `SettingsPage.js`: User settings (profile, permissions, notifications). Props: `userSettings`, `onSettingsChange`.
- `LoadingSpinner.js`: Reusable loading indicator component.
- `NotificationBanner.js`: Displays user notifications and alerts.
DATA MODEL:
- **State Structure (Zustand Store):**
```javascript
// usageStore.js
{
dailyUsage: { // Usage data for the current day
totalTime: 0, // in seconds
apps: [
{ name: 'Instagram', time: 1200 },
{ name: 'TikTok', time: 1800 },
// ... other apps
]
},
weeklyUsage: [ // Array of { date: string, totalTime: number } for the last 7 days
{ date: '2024-04-15', totalTime: 7200 },
// ...
],
monthlyUsage: [ // Array of { month: string, totalTime: number } for the last 12 months
{ month: '2024-03', totalTime: 250000 },
// ...
],
goals: {
dailyLimit: 7200, // seconds
appLimits: { // seconds per app
'Instagram': 3600,
'TikTok': 1800
},
focusHours: [
{ day: 'Mon-Fri', start: '09:00', end: '12:00' }
]
},
detoxModes: {
activeMode: null, // 'Deep Work', 'Mindful Evening', etc.
config: { // Configuration for each mode
'Deep Work': { appsToBlock: ['Instagram', 'TikTok'], duration: 180, notifications: 'silent' }
}
},
isLoading: false,
error: null
}
```
- **Mock Data Format (for initial loading and testing):**
```json
// Example for Dashboard
{
"dailyUsage": {
"totalTime": 5400, // 1.5 hours
"apps": [
{ "name": "Instagram", "time": 1800 },
{ "name": "YouTube", "time": 1200 },
{ "name": "Twitter", "time": 900 },
{ "name": "Facebook", "time": 600 },
{ "name": "Other", "time": 900 }
]
},
"goals": {
"dailyLimit": 7200, // 2 hours
"appLimits": {
"Instagram": 3600,
"TikTok": 0 // Not set
},
"focusHours": []
}
}
// Example for Analytics (Weekly)
"weeklyUsage": [
{ "date": "2024-04-10", "totalTime": 7500 },
{ "date": "2024-04-11", "totalTime": 6800 },
{ "date": "2024-04-12", "totalTime": 8100 },
{ "date": "2024-04-13", "totalTime": 9500 },
{ "date": "2024-04-14", "totalTime": 7200 },
{ "date": "2024-04-15", "totalTime": 6500 },
{ "date": "2024-04-16", "totalTime": 7000 }
]
```
ANIMATIONS & INTERACTIONS:
- **Page Transitions:** Subtle fade-in/fade-out or slide transitions between different sections using `Framer Motion` or CSS transitions managed by React Router.
- **Chart Interactions:** Hover effects on chart elements (bars, points, pie slices) to display specific data values. Tooltips will appear smoothly.
- **Loading States:** Skeletons or `LoadingSpinner` components will be displayed while data is being fetched. These will have a subtle opacity transition.
- **Button/Interactive Elements:** Gentle scaling or background color change on hover and click states.
- **Notification Banners:** Smooth slide-down animation for appearing and slide-up for disappearing.
- **Toggles/Switches:** Smooth animation for state changes (on/off).
EDGE CASES:
- **No Usage Data:** Display friendly messages and illustrations (e.g., 'Start using social media to see your data here!') on the Dashboard and Analytics pages if no usage data is available or permissions are denied.
- **API Errors:** Gracefully handle errors during data fetching. Display informative error messages using `NotificationBanner` and potentially offer a 'Retry' option.
- **Permission Denied:** Clearly guide the user on how to grant necessary permissions if they were initially denied. Provide links to relevant device settings.
- **Invalid Input:** Implement form validation using `React Hook Form` for all user inputs (goals, limits, focus hours). Provide inline error messages and prevent form submission if validation fails.
- **Zero Limits/Goals:** Handle cases where users set limits to 0 or very small values. Ensure the app logic correctly enforces these boundaries.
- **Accessibility (a11y):** Ensure proper semantic HTML structure, ARIA attributes where necessary, keyboard navigability, sufficient color contrast, and focus management for all interactive elements.
- **App Name Changes:** If the underlying platform API provides app data with varying names for the same service (e.g., 'Insta', 'Instagram'), implement a mapping or normalization logic.
SAMPLE DATA (Beyond Mock Data Model Examples):
1. **`ResourceArticle` Object:**
```json
{
"id": "res-001",
"title": "5 Simple Steps to Reduce Your Screen Time Today",
"slug": "5-simple-steps-reduce-screen-time",
"content": "<p>Start by disabling non-essential notifications...</p>",
"author": "Dr. Jane Smith",
"publishedDate": "2024-01-15"
}
```
2. **`DetoxModeConfig` Object:**
```json
{
"name": "Weekend Unplug",
"description": "Minimize distractions during the weekend for quality time.",
"icon": "weekend",
"settings": {
"durationMinutes": 1440, // 24 hours
"appsToBlock": ["Instagram", "Facebook", "Twitter", "TikTok"],
"notificationStrategy": "silentAll"
}
}
```
3. **`AppUsageRecord` (for detailed history if needed):**
```json
{
"timestamp": "2024-04-16T10:30:00Z",
"appName": "LinkedIn",
"duration": 600, // seconds
"eventType": "foreground"
}
```
4. **`User` Profile Snippet (for Settings):**
```json
{
"userId": "user-123",
"email": "user@example.com",
"preferences": {
"theme": "dark",
"notificationsEnabled": true
}
}
```
5. **Error Object:**
```json
{
"code": "FETCH_ERROR",
"message": "Failed to retrieve usage data. Please check your connection and permissions."
}
```
DEPLOYMENT NOTES:
- **Build Configuration:** Configure Vite for production builds (`vite build`). Ensure output is optimized for size and performance. Include necessary environment variables.
- **Environment Variables:** Use `.env` files for managing API keys (if any external APIs are used later), base URLs, and other configuration settings. Prefix variables with `VITE_` (e.g., `VITE_API_URL`).
- **Performance Optimizations:** Code splitting with React Lazy and Suspense for route-based or component-based loading. Image optimization (if applicable). Memoization of expensive computations using `React.memo` or `useMemo`.
- **SEO:** Implement basic SEO for the landing page (if applicable) using `react-helmet-async`. Ensure meta tags are correctly set.
- **CI/CD:** Set up a CI/CD pipeline using Vercel or Netlify. Configure automated builds, tests (if added), and deployments on code pushes to the main branch.
- **Cross-Origin Resource Sharing (CORS):** If a backend API is introduced later, ensure proper CORS configuration on the server.
- **Testing:** While not strictly MVP, plan for unit and integration tests using Jest and React Testing Library. This prompt focuses on generating the initial SPA structure.