PROJECT OVERVIEW:
The application, named 'Sosyal Yankı Analizi' (Social Echo Analysis), is a Software-as-a-Service (SaaS) platform designed to help organizations and individuals understand and address declining engagement and reach on social media platforms, particularly focusing on the trend observed with platforms like X (formerly Twitter). The core problem it solves is the difficulty users face in quantifying and diagnosing the reasons behind decreased visibility and interaction on social media, mirroring the EFF's experience of diminishing returns despite consistent posting. The value proposition is to provide actionable insights derived from data analysis, enabling users to adapt their social media strategies effectively and regain lost reach and engagement.
TECH STACK:
- Frontend Framework: React.js (using Vite for fast development)
- Styling: Tailwind CSS for rapid UI development and consistent design.
- State Management: Zustand for efficient and simple global state management.
- API Calls: Axios for making HTTP requests to the social media platform APIs (simulated for MVP).
- Charting Library: Chart.js or Recharts for data visualization.
- Authentication: Basic simulated authentication for MVP. For a production version, consider JWT or OAuth.
- Deployment: Vercel or Netlify for easy deployment of a static site/SPA.
CORE FEATURES:
1. **Platform Connection:**
* **User Flow:** User navigates to the 'Connect Account' section. They are presented with options to connect their 'X' (Twitter) account. For the MVP, this will be a simulated connection, likely involving inputting an API key (for demonstration) or a simple button click that triggers mock data loading. In a production scenario, this would involve OAuth 2.0 implementation.
* **Details:** The connection process must be secure and clearly communicate the permissions required. The MVP will simulate this, perhaps by asking the user to input a "mock API key" to proceed.
2. **Data Fetching & Analysis:**
* **User Flow:** Once an account is connected (or mock connection is established), the user is taken to the dashboard. The system automatically fetches historical and recent data (posts, impressions, engagement metrics like likes, retweets, replies) for the connected account. Data is processed to calculate key metrics like average impressions per post, engagement rate, and overall reach trends.
* **Details:** The MVP will fetch predefined mock data. Calculations include:
* Total Posts
* Total Impressions
* Average Impressions per Post
* Total Engagements (Likes + Retweets + Replies)
* Average Engagement Rate per Post
* Impressions Trend (e.g., monthly or weekly)
* Engagement Trend
3. **Data Visualization:**
* **User Flow:** The dashboard displays the fetched and analyzed data using interactive charts and graphs. Users can see their overall performance, trends over time, and potentially compare different periods.
* **Details:** Use Chart.js or Recharts to display:
* Line chart for Impressions Over Time.
* Line chart for Engagement Over Time.
* Bar chart comparing Average Impressions per Post (current period vs. historical period if available).
* Key metrics displayed prominently as KPIs (Key Performance Indicators).
4. **Decline Detection & Alerting (Basic):**
* **User Flow:** The system analyzes the fetched data for significant downward trends. If a sharp decline (e.g., >30% drop in monthly impressions compared to the previous month) is detected, a simple notification appears on the dashboard.
* **Details:** An algorithm checks the current period's key metrics against the previous period. A "Potential Decline Alert" banner is shown if a significant drop is detected. For MVP, this detection is based on predefined thresholds in the mock data.
5. **Comparative Insights (Basic):**
* **User Flow:** The platform presents a basic comparison, such as the user's current average impressions per post against a historical benchmark (e.g., "7 years ago" or a general industry average provided in mock data).
* **Details:** A simple text or card component showing a comparison, like: "Your average impressions per post are X% lower than the benchmark period of [Date/Period]."
UI/UX DESIGN:
- **Layout:** Single Page Application (SPA) layout. A clean, modern dashboard interface. Sidebar navigation (if needed for future expansion) or a top navigation bar. Main content area displays charts, KPIs, and alerts.
- **Color Palette:** Primarily dark theme for a professional, data-focused look. Use a vibrant accent color (e.g., a bright blue or green) for CTAs, highlights, and data points on charts. Background: Dark gray (#1F2937), Text: Light gray/White (#F3F4F6), Accent: Teal (#14B8A6).
- **Typography:** Use a clean, sans-serif font like Inter or Poppins for readability. Headings: Semibold/Bold, Body Text: Regular.
- **Responsive Design:** Mobile-first approach. The dashboard should be fully responsive, adapting gracefully to various screen sizes (mobile, tablet, desktop). Tailwind CSS's responsive modifiers (sm:, md:, lg:) will be crucial.
- **Component Hierarchy:** App Shell -> Dashboard Container -> KPI Cards -> Chart Components (Impressions, Engagement) -> Alert Banner -> Connection Status Indicator.
COMPONENT BREAKDOWN:
- `App.jsx`: Main application component, sets up routing (if any) and global layout.
- `Dashboard.jsx`: Main content area, fetches and orchestrates data display.
* `Props`: None (manages its own state or context).
* `Responsibility`: Fetches data, manages state via Zustand, renders other dashboard components.
- `KpiCard.jsx`: Displays a single Key Performance Indicator.
* `Props`: `title` (string), `value` (string/number), `trend` (string, optional, e.g., 'up'/'down').
* `Responsibility`: Renders a single metric nicely formatted.
- `ChartComponent.jsx`: Renders a specific chart (e.g., Impressions Over Time).
* `Props`: `chartData` (object), `chartOptions` (object), `title` (string).
* `Responsibility`: Configures and renders a chart using Chart.js or Recharts.
- `ConnectButton.jsx`: Button to initiate the (simulated) account connection.
* `Props`: `onClick` (function).
* `Responsibility`: Handles the connection button click event.
- `AlertBanner.jsx`: Displays notifications/alerts.
* `Props`: `message` (string), `type` (string, e.g., 'warning', 'info').
* `Responsibility`: Shows important messages to the user.
DATA MODEL (Zustand Store & Mock Data):**
- **Zustand Store (`store/dataStore.js`):**
```javascript
import create from 'zustand';
export const useDataStore = create((set) => ({
isConnected: false,
accountName: '',
metrics: {
totalPosts: 0,
totalImpressions: 0,
avgImpressionsPerPost: 0,
totalEngagements: 0,
avgEngagementRate: 0,
impressionsTrend: [], // [{ date: 'YYYY-MM-DD', value: number }]
engagementTrend: [], // [{ date: 'YYYY-MM-DD', value: number }]
},
comparisonData: {
previousPeriodImpressions: 0,
currentPeriodImpressions: 0,
percentageChange: 0
},
alert: null, // { message: string, type: 'warning' | 'info' }
setIsConnected: (connected) => set({ isConnected: connected }),
setAccountName: (name) => set({ accountName: name }),
setMetrics: (metrics) => set({ metrics }),
setComparisonData: (data) => set({ comparisonData: data }),
setAlert: (alert) => set({ alert }),
fetchMockData: async () => {
// Simulate API call
await new Promise(resolve => setTimeout(resolve, 1500));
const mockData = {
isConnected: true,
accountName: 'EFF_Mock',
metrics: {
totalPosts: 2500,
totalImpressions: 5000000, // Adjusted mock value
avgImpressionsPerPost: 2000,
totalEngagements: 150000,
avgEngagementRate: 3.0,
impressionsTrend: [
{ date: '2023-01-01', value: 150000 }, { date: '2023-02-01', value: 140000 },
{ date: '2023-03-01', value: 130000 }, { date: '2023-04-01', value: 120000 },
{ date: '2023-05-01', value: 110000 }, { date: '2023-06-01', value: 100000 },
{ date: '2023-07-01', value: 95000 }, { date: '2023-08-01', value: 90000 },
{ date: '2023-09-01', value: 85000 }, { date: '2023-10-01', value: 80000 },
{ date: '2023-11-01', value: 75000 }, { date: '2023-12-01', value: 70000 },
{ date: '2024-01-01', value: 65000 }, { date: '2024-02-01', value: 60000 },
{ date: '2024-03-01', value: 55000 }, { date: '2024-04-01', value: 50000 },
{ date: '2024-05-01', value: 45000 }, { date: '2024-06-01', value: 40000 },
],
engagementTrend: [
{ date: '2023-01-01', value: 5000 }, { date: '2023-02-01', value: 4800 },
{ date: '2023-03-01', value: 4500 }, { date: '2023-04-01', value: 4200 },
{ date: '2023-05-01', value: 4000 }, { date: '2023-06-01', value: 3800 },
{ date: '2023-07-01', value: 3600 }, { date: '2023-08-01', value: 3400 },
{ date: '2023-09-01', value: 3200 }, { date: '2023-10-01', value: 3000 },
{ date: '2023-11-01', value: 2800 }, { date: '2023-12-01', value: 2600 },
{ date: '2024-01-01', value: 2400 }, { date: '2024-02-01', value: 2200 },
{ date: '2024-03-01', value: 2000 }, { date: '2024-04-01', value: 1800 },
{ date: '2024-05-01', value: 1600 }, { date: '2024-06-01', value: 1400 },
]
},
comparisonData: {
previousPeriodImpressions: 13000000, // Approx. annual impressions from 2023
currentPeriodImpressions: 2000000, // Approx. annual impressions for recent period
percentageChange: -84.6 // Calculated based on mock values
},
alert: { message: 'Significant drop detected in monthly impressions compared to previous period.', type: 'warning' }
};
set(mockData);
}
}));
```
- **Mock Data Format:** The `mockData` object within the Zustand store provides the structure. Dates should be in `YYYY-MM-DD` format. Values are numbers. `impressionsTrend` and `engagementTrend` are arrays of objects, each representing a data point over time.
ANIMATIONS & INTERACTIONS:
- **Page Transitions:** Subtle fade-in/fade-out for route changes if using React Router (not strictly necessary for a single-page dashboard but good practice).
- **Loading States:** When fetching data, display a skeleton loader or a subtle spinner within the relevant components (e.g., inside KPI cards or chart containers). Use Tailwind CSS spinners or placeholder divs.
- **Hover Effects:** Slight scale-up or background color change on interactive elements like buttons and KPI cards.
- **Chart Interactions:** Tooltips on chart data points to show exact values and dates. Highlight data series on hover.
- **Micro-interactions:** Smooth transitions for number counters animating from 0 to their final value in KPI cards.
EDGE CASES:
- **No Connected Account:** Display a clear call-to-action to connect an account. The dashboard should show placeholder states or informative messages instead of charts.
- **No Data Available:** If an account is connected but has no posts or engagement data for the selected period, display a "No data available" message gracefully within the chart areas and KPI cards.
- **API Errors:** Implement error handling for API calls (simulated in MVP). Display user-friendly error messages (e.g., "Could not fetch data. Please try again later."). Use the `alert` state in Zustand for this.
- **Validation:** For a real connection, validate API keys or OAuth tokens. In MVP, the "connection" is mocked, so validation is minimal.
- **Accessibility (a11y):** Use semantic HTML elements. Ensure proper ARIA attributes for charts and interactive elements. Ensure sufficient color contrast, especially between text and background, and in chart elements. Keyboard navigability for all interactive components.
SAMPLE DATA (Included in `aiMasterPrompt`'s Data Model section):
- `metrics.impressionsTrend`: An array of 18 data points (monthly for 1.5 years), showing a declining trend.
- `metrics.engagementTrend`: Similar array for engagement.
- `comparisonData`: Mock values representing a drastic drop in annual impressions.
- `alert`: A sample warning alert object.
DEPLOYMENT NOTES:
- **Build Settings:** Configure Vite or your chosen build tool for production builds (`npm run build`).
- **Environment Variables:** For a production app, use environment variables for API endpoints and keys (e.g., `VITE_API_URL`). In the MVP, these can be hardcoded within the mock data fetching function.
- **Performance Optimizations:** Code splitting (if application grows), image optimization (if any), efficient state management. Ensure lazy loading for components if necessary. Minimize re-renders by optimizing React component structures and memoization.
- **HTTPS:** Always deploy using HTTPS for security, especially if handling any sensitive data or real API keys.