PROJECT OVERVIEW:
The application, 'HaberAnaliz: Jeopolitik Olay Takip', aims to provide a centralized and insightful platform for tracking and analyzing geopolitical events. In a world saturated with information, users struggle to synthesize news from disparate sources and understand the nuances of complex global incidents. HaberAnaliz solves this by automatically ingesting news articles, identifying key geopolitical events, extracting crucial details, and presenting them in an easily digestible format through timelines and visualizations. The core value proposition is to transform raw news data into actionable geopolitical intelligence, saving users time and enhancing their understanding of world affairs.
TECH STACK:
- Frontend: React.js (using Vite for fast development)
- Styling: Tailwind CSS for rapid UI development and utility-first styling.
- State Management: Zustand for efficient and scalable global state management.
- Routing: React Router DOM for client-side navigation.
- Data Fetching: Axios for making HTTP requests.
- UI Components: Headless UI for accessible and customizable components (modals, dropdowns, etc.).
- Charting Library: Recharts for data visualization (charts, graphs).
- Mapping Library: Leaflet with React-Leaflet for interactive maps.
- Text Analysis (Conceptual): Integration with a hypothetical NLP API or library for entity recognition, event detection, and sentiment analysis. For the MVP, this will be simulated with mock data extraction logic.
CORE FEATURES:
1. **URL Ingestion & Content Extraction:**
* **User Flow:** User inputs a news article URL into a designated input field. Upon submission, the system fetches the article content. A loading indicator is shown during fetching and processing.
* **Details:** The system scrapes the main article text, title, and publication date from the provided URL. Error handling for invalid URLs or inaccessible content is implemented.
2. **Event Detection & Categorization:**
* **User Flow:** After content extraction, the system analyzes the text to identify the primary event (e.g., 'Military Conflict', 'Diplomatic Tension', 'Economic Sanction').
* **Details:** This uses simulated NLP logic for the MVP. It identifies keywords, phrases, and sentence structures indicative of specific geopolitical event types. The identified category is stored with the event data.
3. **Key Information Extraction:**
* **User Flow:** Concurrently with categorization, the system extracts specific entities related to the event.
* **Details:** Extracts: Location (country, city), Involved Parties (countries, organizations), Key Figures (if prominent), Military Assets (if mentioned, e.g., 'F-15E jet'). This is simulated for MVP.
4. **Timeline Generation:**
* **User Flow:** Once an event and its details are processed, they are added to a chronological timeline view.
* **Details:** Events are sorted by their detected or implied date. The timeline displays the event category, a brief summary, and the date. Clicking an event item might show more details.
5. **Data Visualization:**
* **User Flow:** A dedicated 'Visualizations' or 'Map' section displays the extracted data geographically and relationally.
* **Details:** A map highlights event locations. A simple relationship graph could show connections between involved parties. For the F-15E example, the map would show Iran, and a simple node graph could show 'USA' and 'Iran' as involved parties.
UI/UX DESIGN:
- **Layout:** Single Page Application (SPA) layout. A clean sidebar for navigation (Dashboard, Timeline, Map, Settings) and a main content area. Responsive design ensuring usability on desktops, tablets, and mobile devices.
- **Color Palette:** Primary: Deep Blue (#1A202C), Secondary: Cool Gray (#4A5568), Accent: Teal (#4FD1C5), Alert/Error: Red (#F56565), Success: Green (#48BB78). White (#FFFFFF) and light gray (#F7FAFC) for backgrounds and text.
- **Typography:** Sans-serif fonts like Inter or Poppins for readability. Clear hierarchy using font weights and sizes. Headings: Bold, larger sizes. Body text: Regular weight, comfortable line height.
- **Responsive Rules:** Mobile-first approach. Sidebar collapses into a hamburger menu on smaller screens. Content adjusts fluidly. Maps and charts are optimized for touch interaction.
- **Components:** Input forms, buttons, cards for event summaries, modals for detailed views, interactive maps, charts, timeline components, loading spinners, error message banners.
COMPONENT BREAKDOWN:
1. `App.jsx`: Main application component, sets up routing and global layout.
* Props: None
* Responsibility: Main layout, routing.
2. `Sidebar.jsx`: Navigation component.
* Props: `activeLink` (string), `onLinkClick` (function)
* Responsibility: Displays navigation links, manages active state.
3. `Header.jsx`: Top bar, perhaps with search or user profile (future).
* Props: None
* Responsibility: Application header.
4. `UrlInputForm.jsx`: Form for submitting article URLs.
* Props: `onSubmitUrl` (function), `isLoading` (boolean)
* Responsibility: Handles URL input and submission logic.
5. `EventCard.jsx`: Displays a summary of a detected geopolitical event.
* Props: `eventData` (object: { title, category, date, location, involvedParties })
* Responsibility: Renders individual event summaries in lists or timelines.
6. `TimelineView.jsx`: Displays events chronologically.
* Props: `events` (array of eventData objects)
* Responsibility: Renders the event timeline component.
7. `MapView.jsx`: Displays events on an interactive map.
* Props: `events` (array of eventData objects with location data)
* Responsibility: Renders the map and event markers.
8. `LoadingSpinner.jsx`: Reusable loading indicator.
* Props: None
* Responsibility: Visual feedback during data processing.
9. `ErrorMessage.jsx`: Displays error messages.
* Props: `message` (string)
* Responsibility: User-friendly error display.
10. `ContentExtractor.js` (Utility): Handles URL fetching and text extraction.
11. `EventAnalyzer.js` (Utility): Simulates NLP for event/entity extraction.
12. `DataStore.js` (Zustand Store): Manages application state (events list, loading status, errors).
DATA MODEL:
- **State Structure (Zustand Store):**
```javascript
{
events: [], // Array of event objects
isLoading: false,
error: null,
// future: user settings, active filters, etc.
}
```
- **Event Object Structure:**
```javascript
{
id: 'unique_event_id',
sourceUrl: 'original_url.com',
title: 'F-15E jet shot down over Iran',
category: 'Military Conflict',
detectedDate: '2026-04-03', // or inferred date
timestamp: 1649059200000, // for sorting
summary: 'An F-15E Strike Eagle fighter jet was reportedly shot down over Iranian territory near the Afghanistan border.',
location: { name: 'Iran', coordinates: [lat, lon] }, // Simplified for MVP
involvedParties: ['USA', 'Iran'],
militaryAssets: ['F-15E'],
// future: sentimentScore, relatedEvents, etc.
}
```
- **Mock Data:** Mock data will be used initially to simulate the output of the `ContentExtractor` and `EventAnalyzer` utility functions. This ensures frontend components can be developed and tested.
ANIMATIONS & INTERACTIONS:
- **Loading States:** `LoadingSpinner` component displayed when fetching data or processing. Tailwind CSS transitions for smooth appearance/disappearance.
- **Hover Effects:** Subtle background color changes or slight scaling on `EventCard` components and navigation links on hover using Tailwind's `hover:` variants.
- **Transitions:** Smooth transitions for route changes (if using React Router). Smooth appearance of new events in the timeline or map using CSS transitions or libraries like Framer Motion (optional for MVP).
- **Micro-interactions:** Button click feedback (slight press effect), form input focus states.
- **Map Interactions:** Zooming, panning, marker popups on click.
EDGE CASES:
- **Invalid URL:** `UrlInputForm` displays an error message via `ErrorMessage` component. `error` state is updated.
- **Content Extraction Failure:** If the URL is valid but content cannot be scraped (e.g., paywall, JS-heavy site), an appropriate error message is shown.
- **No Event Detected:** If the extracted text doesn't contain clear geopolitical event indicators, display a message like 'No significant geopolitical event detected in this article'.
- **Missing Data:** If specific details (like location or involved parties) cannot be extracted, gracefully handle by not displaying that piece of information or showing a placeholder (e.g., 'Location: Unknown').
- **Empty States:** Timeline and Map views show informative messages when no events are loaded yet (e.g., 'Submit a URL to start analyzing events.').
- **Accessibility (a11y):** Use semantic HTML5 elements. Ensure keyboard navigability for all interactive elements. Provide ARIA attributes where necessary. Ensure sufficient color contrast.
- **Rate Limiting/Blocking:** If using external APIs, implement proper error handling for rate limits or blocks.
SAMPLE DATA:
1. **Input URL:** `https://theaviationist.com/2026/04/03/iran-f-15e-debris/`
* **Output Event Object:**
```json
{
"id": "hn_event_1",
"sourceUrl": "https://theaviationist.com/2026/04/03/iran-f-15e-debris/",
"title": "F-15E jet shot down over Iran",
"category": "Military Conflict",
"detectedDate": "2026-04-03",
"timestamp": 1775308800000,
"summary": "An F-15E Strike Eagle fighter jet was reportedly shot down by Iranian air defenses over Iranian territory, near the Afghanistan border. Debris has been recovered.",
"location": { "name": "Iran", "coordinates": [33.8869, 55.3415] }, // Approximate center of Iran
"involvedParties": ["USA", "Iran"],
"militaryAssets": ["F-15E"]
}
```
2. **Input URL:** `https://www.reuters.com/world/middle-east/iran-says-it-seized-israeli-linked-ship-strait-hormuz-2024-04-13/`
* **Output Event Object:**
```json
{
"id": "reuters_event_2",
"sourceUrl": "https://www.reuters.com/world/middle-east/iran-says-it-seized-israeli-linked-ship-strait-hormuz-2024-04-13/",
"title": "Iran seizes Israeli-linked ship in Strait of Hormuz",
"category": "Maritime Incident / Political Tension",
"detectedDate": "2024-04-13",
"timestamp": 1712947200000,
"summary": "Iran's Revolutionary Guard seized a container ship they said was linked to Israel sailing through the Strait of Hormuz.",
"location": { "name": "Strait of Hormuz", "coordinates": [26.8206, 54.3667] },
"involvedParties": ["Iran", "Israel"],
"militaryAssets": ["IRGC Navy Vessels"]
}
```
3. **Input URL:** `https://www.bbc.com/news/world-asia-68787878` (Hypothetical news about Russia-China talks)
* **Output Event Object:**
```json
{
"id": "bbc_event_3",
"sourceUrl": "https://www.bbc.com/news/world-asia-68787878",
"title": "Russia and China strengthen ties amid Western sanctions",
"category": "Diplomatic Relations",
"detectedDate": "2024-04-01", // Assuming article date
"timestamp": 1711910400000,
"summary": "Leaders of Russia and China held talks reaffirming strategic partnership and economic cooperation, amidst ongoing international pressure.",
"location": { "name": "Moscow", "coordinates": [55.7558, 37.6173] }, // Or Beijing
"involvedParties": ["Russia", "China"],
"militaryAssets": []
}
```
4. **Input URL:** `https://apnews.com/article/ukraine-war-russia-politics-country-reports-europe-555555555555` (Hypothetical aid package announcement)
* **Output Event Object:**
```json
{
"id": "ap_event_4",
"sourceUrl": "https://apnews.com/article/ukraine-war-russia-politics-country-reports-europe-555555555555",
"title": "US announces new military aid package for Ukraine",
"category": "Military Aid / International Relations",
"detectedDate": "2024-04-15", // Assuming article date
"timestamp": 1713120000000,
"summary": "The United States has unveiled a new multi-billion dollar military aid package for Ukraine, including advanced weaponry.",
"location": { "name": "Washington D.C.", "coordinates": [38.9072, -77.0369] }, // Announcement location
"involvedParties": ["USA", "Ukraine", "Russia"],
"militaryAssets": ["Advanced Weaponry"]
}
```
5. **Input URL:** `https://www.aljazeera.com/economy/2024/4/10/oil-prices-surge-amid-middle-east-tensions` (Hypothetical oil price surge)
* **Output Event Object:**
```json
{
"id": "aljazeera_event_5",
"sourceUrl": "https://www.aljazeera.com/economy/2024/4/10/oil-prices-surge-amid-middle-east-tensions",
"title": "Oil prices surge amid Middle East tensions",
"category": "Economic Impact",
"detectedDate": "2024-04-10",
"timestamp": 1712707200000,
"summary": "Global oil prices experienced a significant increase due to escalating geopolitical tensions in the Middle East, impacting energy markets worldwide.",
"location": { "name": "Middle East", "coordinates": [25.0, 55.0] }, // General region
"involvedParties": ["Global Markets", "Middle Eastern Producers"],
"militaryAssets": []
}
```
DEPLOYMENT NOTES:
- **Build Command:** `npm run build` (or `yarn build` if using Yarn).
- **Environment Variables:** Use `.env` file for API keys (e.g., hypothetical NLP service key, mapping service keys if needed). Prefix variables with `VITE_` for Vite projects (e.g., `VITE_NLP_API_KEY`).
- **Static Hosting:** The build output (typically in a `dist/` folder) can be deployed to any static hosting provider (Netlify, Vercel, GitHub Pages).
- **Performance Optimizations:** Code splitting (handled by Vite/React Router), image optimization (if applicable), efficient state management, lazy loading components where appropriate.
- **HTTPS:** Ensure deployment uses HTTPS for security. Leaflet might require HTTPS if using external tile layers.
- **CORS:** Be mindful of Cross-Origin Resource Sharing if the frontend needs to call APIs directly from a different domain. Consider a simple backend proxy if CORS becomes an issue.
- **SSR/SSG:** For a purely frontend SPA, this is not strictly necessary, but Next.js could be considered for future SEO improvements or server-side rendering if needed.