You are a senior full-stack developer tasked with creating a single-page application (SPA) for 'Veri Etki: Lobicilik Analiz Platformu'. This platform aims to provide transparency into lobbying efforts, dark money influence, and political impact operations, leveraging publicly available data. The application should be a robust data analysis tool presented through an intuitive user interface.
**1. PROJECT OVERVIEW:**
The primary goal of Veri Etki is to empower journalists, researchers, NGOs, policymakers, and watchdog organizations by providing them with a comprehensive platform to analyze the intricate web of influence operations. It solves the problem of opaque political lobbying and funding by consolidating and visualizing data from diverse public sources. The core value proposition is to offer actionable intelligence on how organizations attempt to shape public policy, thereby fostering greater accountability and transparency in the political landscape. This investigation, inspired by the analysis of Meta's lobbying for the App Store Accountability Act, will serve as a foundational case study.
**2. TECH STACK:**
- **Frontend Framework:** React (using Vite for fast development)
- **Styling:** Tailwind CSS for rapid, utility-first styling.
- **State Management:** Zustand for efficient global state management, particularly for data fetching and UI state.
- **Data Fetching:** TanStack Query (React Query) for managing server state, caching, and asynchronous operations.
- **Charting Library:** Chart.js or Recharts for data visualization.
- **Routing:** React Router DOM for navigation within the SPA.
- **UI Components:** Radix UI or Headless UI for accessible and customizable components (e.g., modals, dropdowns, tooltips).
- **Form Handling:** React Hook Form for efficient and scalable form management.
- **Utilities:** Lodash for utility functions, date-fns for date manipulation.
- **Icons:** React Icons.
**3. CORE FEATURES:**
- **Dashboard Overview:** Upon login, users see a dashboard summarizing key metrics, recent investigations, and personalized alerts. It includes a search bar for immediate data lookup.
- **User Flow:** User logs in -> sees dashboard -> uses search bar to find a company/act -> navigates to detailed view.
- **Entity Deep Dive (Companies/Acts):** A dedicated page for each company or legislative act. Displays aggregated lobbying data, funding sources, related entities, and a timeline of key events.
- **User Flow:** User searches for 'Meta Platforms' -> clicks on result -> lands on Meta's profile page -> sees lobbying spend over time, list of associated acts, linked dark money groups.
- **Data Visualization:** Interactive charts and graphs displaying lobbying expenditure trends, campaign contributions by state/party, funding flow networks, and legislative impact.
- **User Flow:** On an entity page, user interacts with a chart (e.g., hovers over a bar in the 'Lobbying Spend by Quarter' chart) to see precise figures and details.
- **Source Tracking & Verification:** Each data point is linked back to its original public source (e.g., IRS 990 filing, Senate LD-2 disclosure). A 'Verification' status (e.g., 'Proven', 'Hypothesized', 'Pending FOIA') is displayed.
- **User Flow:** User views a data point -> clicks a 'Source' icon -> a modal appears showing the source document link, filing date, and verification status.
- **Alerts & Watchlists:** Users can add entities or acts to a watchlist and receive email or in-app notifications for significant new lobbying activity, funding changes, or legislative updates.
- **User Flow:** User navigates to 'Meta Platforms' page -> clicks 'Add to Watchlist' -> receives an email notification when Meta files a new LD-2 disclosure.
**4. UI/UX DESIGN:**
- **Layout:** A clean, professional, and data-forward single-page application. A persistent sidebar navigation for key sections (Dashboard, Search, Watchlist, Settings). The main content area displays detailed information and visualizations.
- **Color Palette:** A sophisticated palette emphasizing trust and clarity. Primary: Deep Navy Blue (`#0A192F`), Secondary: Slate Gray (`#8892B0`), Accent: Teal (`#64FFDA`), Background: Dark Charcoal (`#020C1B`). Use white/light gray for text on dark backgrounds.
- **Typography:** Sans-serif fonts for readability. Headings: Inter (Bold), Body Text: Inter (Regular). Ensure good contrast ratios.
- **Responsive Design:** Mobile-first approach. Sidebar collapses into a hamburger menu on smaller screens. Content reflows and optimizes for tablet and desktop viewing. Charts should be responsive and potentially simplify on mobile.
- **Interactions:** Subtle hover effects on interactive elements, smooth transitions for modal pop-ups and section expansions. Loading spinners or skeleton screens for data fetching.
**5. DATA MODEL:**
- **State Management (Zustand):**
```javascript
// store/searchStore.js
import { create } from 'zustand';
const useSearchStore = create((set) => ({
searchTerm: '',
setSearchTerm: (term) => set({ searchTerm: term }),
searchResults: [],
setSearchResults: (results) => set({ searchResults: results }),
isLoading: false,
setIsLoading: (loading) => set({ isLoading: loading }),
}));
// store/entityStore.js
const useEntityStore = create((set) => ({
selectedEntity: null,
setSelectedEntity: (entity) => set({ selectedEntity: entity }),
entityData: null,
setEntityData: (data) => set({ entityData: data }),
isEntityLoading: false,
setIsEntityLoading: (loading) => set({ isEntityLoading: loading }),
}));
```
- **Mock Data Formats:**
- **Entity Object:**
```json
{
"id": "meta-platforms-inc",
"name": "Meta Platforms, Inc.",
"type": "Company",
"aliases": ["Facebook", "Instagram"],
"description": "Technology conglomerate focused on social media and virtual reality.",
"profileUrl": "/entities/meta-platforms-inc",
"imageUrl": "/images/meta.png"
}
```
- **Lobbying Disclosure Object:**
```json
{
"id": "ld2-2023-q4-meta",
"entityId": "meta-platforms-inc",
"reportingPeriod": "2023-Q4",
"totalLobbyingSpend": 26300000,
"currency": "USD",
"filingDate": "2024-01-20",
"sourceUrl": "https://lda.senate.gov/filings/filing/?filing_id=12345",
"verificationStatus": "Proven",
"issues": ["Technology", "App Store Regulation", "Data Privacy"],
"lobbyists": ["John Doe", "Jane Smith"]
}
```
- **Funding Channel Object:**
```json
{
"id": "channel-dca-funding",
"sourceEntityId": "meta-platforms-inc",
"targetEntityId": "digital-childhood-alliance",
"amount": 500000,
"currency": "USD",
"date": "2023-06-15",
"type": "Grant",
"description": "Funding for child safety advocacy initiatives.",
"sourceUrl": "https://www.irs.gov/filings/990/abc-org/filing-id-67890",
"verificationStatus": "Proven"
}
```
**6. COMPONENT BREAKDOWN:**
- **`App.js`**: Main application component, sets up routing and global layout.
- Props: None
- Responsibilities: Initialize routing, manage global context/state providers.
- **`Layout.js`**: Contains the persistent sidebar navigation and the main content area.
- Props: `children` (the content to render)
- Responsibilities: Structure the overall page layout, handle sidebar toggle.
- **`Sidebar.js`**: Navigation menu component.
- Props: `isOpen` (boolean), `onClose` (function)
- Responsibilities: Display navigation links, handle mobile menu interaction.
- **`Header.js`**: Top bar, includes search input and user profile/settings access.
- Props: None
- Responsibilities: Primary search input, global actions.
- **`SearchBar.js`**: Input component for entity/act search.
- Props: `onSearch` (function), `isLoading` (boolean)
- Responsibilities: Capture user input, trigger search action, display loading state.
- **`SearchResultsList.js`**: Displays the list of entities/acts matching the search term.
- Props: `results` (array), `onResultClick` (function)
- Responsibilities: Render search results, handle click events to navigate.
- **`EntityProfile.js`**: Displays detailed information about a specific company or act.
- Props: `entityId` (string)
- Responsibilities: Fetch and display entity details, lobbying data, funding info.
- **`LobbyingChart.js`**: Renders interactive charts for lobbying data.
- Props: `data` (array of lobbying periods/spends), `title` (string)
- Responsibilities: Visualize lobbying trends using Chart.js/Recharts.
- **`FundingFlows.js`**: Displays information about funding channels and dark money.
- Props: `fundingData` (array)
- Responsibilities: Show sources and destinations of funds.
- **`DataTable.js`**: Generic reusable table component for displaying structured data.
- Props: `columns` (array of column definitions), `data` (array of rows)
- Responsibilities: Render data in a sortable, filterable table format.
- **`DataSourceBadge.js`**: Component to display source information and verification status.
- Props: `sourceUrl` (string), `verificationStatus` (string)
- Responsibilities: Link to source, indicate data reliability.
- **`WatchlistManager.js`**: Component for managing user's watchlist.
- Props: None
- Responsibilities: Add/remove entities, display watchlist items.
- **`AlertNotification.js`**: Displays user notifications and alerts.
- Props: `alerts` (array)
- Responsibilities: Show relevant updates and alerts to the user.
**7. ANIMATIONS & INTERACTIONS:**
- **Page Transitions:** Subtle fade-in/fade-out transitions between major sections using `Framer Motion` or CSS transitions.
- **Chart Interactions:** Hover effects on chart elements (bars, points) to display tooltips with precise data values. Smooth zooming/panning for complex charts.
- **Button/Link Hovers:** Slight scale-up or background color change on interactive elements.
- **Loading States:** Use `react-skeletons` or custom CSS spinners/shimmers when data is being fetched. Ensure loading states are visually distinct and informative.
- **Modal Animations:** Smooth slide-in/fade-in for modals and dropdowns.
- **Micro-interactions:** Subtle animations on adding items to watchlist, form submissions, or successful data loading confirmations.
**8. EDGE CASES:**
- **No Search Results:** Display a clear message like "No results found for '[searchTerm]'. Try a different query." instead of an empty list.
- **Empty State Data:** For entities with no recorded lobbying or funding data, display a message like "No lobbying data available for this period." or "This entity has no tracked funding channels."
- **Data Fetching Errors:** Implement robust error handling for API requests. Display user-friendly error messages (e.g., "Failed to load data. Please try again later.") and provide a retry option.
- **API Rate Limiting:** If using external APIs, implement strategies to handle rate limits gracefully (e.g., exponential backoff, caching).
- **Validation:** Client-side and server-side validation for any user input (e.g., search queries, watchlist additions if authenticated).
- **Accessibility (a11y):** Ensure all interactive elements are keyboard-navigable. Use ARIA attributes where necessary. Ensure sufficient color contrast. All images have alt text. Charts are accessible via keyboard and screen readers where possible.
- **Data Discrepancies:** Implement mechanisms to flag potential data inconsistencies or outdated information, perhaps allowing user feedback.
**9. SAMPLE DATA:**
- **Search Results (Companies):**
```json
[
{"id": "meta-platforms-inc", "name": "Meta Platforms, Inc.", "type": "Company"},
{"id": "apple-inc", "name": "Apple Inc.", "type": "Company"}
]
```
- **Search Results (Acts):**
```json
[
{"id": "asaa-2024", "name": "App Store Accountability Act (2024)", "type": "Legislation"}
]
```
- **Entity Profile Data (Meta Platforms):
```json
{
"id": "meta-platforms-inc",
"name": "Meta Platforms, Inc.",
"description": "Global technology company focused on connecting people.",
"totalLobbyingSpendLastYear": 26300000,
"topIssues": ["Technology", "Data Privacy", "App Store Regulation"],
"relatedEntities": ["digital-childhood-alliance"],
"recentFilings": [
{"id": "ld2-2023-q4-meta", "period": "2023-Q4", "spend": 6500000, "status": "Proven"},
{"id": "ld2-2023-q3-meta", "period": "2023-Q3", "spend": 6300000, "status": "Proven"}
]
}
```
- **Legislative Act Details (ASAA):
```json
{
"id": "asaa-2024",
"name": "App Store Accountability Act",
"status": "Active Investigation",
"summary": "Requires app stores to verify user ages before downloads, shifting burden to platforms.",
"keyProponents": ["meta-platforms-inc", "digital-childhood-alliance"],
"keyOpponents": ["apple-inc"],
"timeline": [
{"date": "2023-01-15", "event": "Bill Introduced", "source": "congress.gov"},
{"date": "2023-06-15", "event": "DCA Funding Confirmed", "source": "irs-990-abc-org"}
]
}
```
- **Funding Flow Network Node:**
```json
{
"id": "digital-childhood-alliance",
"label": "Digital Childhood Alliance",
"group": "Advocacy Group",
"totalInflow": 500000
}
```
**10. DEPLOYMENT NOTES:**
- **Build Tool:** Vite. Run `npm run build` for production build.
- **Environment Variables:** Use `.env` files for environment-specific configurations (e.g., `VITE_API_BASE_URL`). Ensure sensitive keys are managed securely, especially if deployed.
- **Performance Optimizations:**
- Code Splitting: Vite handles this automatically for routes and component lazy loading.
- Image Optimization: Use optimized image formats (e.g., WebP) and responsive images.
- Memoization: Use `React.memo`, `useMemo`, `useCallback` judiciously to prevent unnecessary re-renders.
- Data Fetching: Leverage TanStack Query's caching and background refetching capabilities. Implement pagination for large datasets.
- **Hosting:** Vercel, Netlify, or similar static hosting platforms are suitable. Ensure proper configuration for SPA routing (e.g., redirect all non-file requests to `index.html`).
- **HTTPS:** Always deploy using HTTPS.
- **CI/CD:** Set up a CI/CD pipeline (e.g., GitHub Actions, GitLab CI) for automated testing and deployment.