You are tasked with creating a cutting-edge, single-page SaaS application called 'Global Gözlem Paneli' (Global Observation Dashboard). This application aims to aggregate and visualize real-time global data feeds, providing users with a unified and insightful view of international events, geographical movements, and potential conflict zones. The core problem it solves is the fragmentation of critical real-time information across multiple disparate platforms, making it difficult and time-consuming for users to gain a comprehensive understanding of global happenings. The primary value proposition is to deliver a seamless, intuitive, and powerful dashboard that centralizes and visualizes key data streams like aircraft (ADS-B), ship (AIS) traffic, satellite telemetry, and conflict data (GDELT), enabling faster and more informed decision-making.
**1. PROJECT OVERVIEW:**
Global Gözlem Paneli is a real-time Open Source Intelligence (OSINT) dashboard. It addresses the user's pain point of constantly switching between various live feeds (e.g., Flightradar, MarineTraffic, Twitter, satellite trackers) during significant global events. The application will aggregate commercial/military ADS-B data, AIS WebSocket streams, N2YO satellite telemetry, and GDELT conflict data into a single, interactive MapLibre map instance. A key innovative feature is the 'signal layer' which calculates live GPS jamming zones by aggregating real-time navigation degradation (NAC-P) from commercial flights. The goal is to provide a cohesive and actionable intelligence picture, moving beyond scattered data points to a synthesized understanding of global activity. The 'movie hacker' aesthetic from the original concept will be adapted into a clean, modern, and professional UI with subtle, sophisticated dark-themed elements, focusing on clarity and performance.
**2. TECH STACK:**
- **Frontend Framework:** React (using Vite for a fast development experience)
- **State Management:** Zustand (lightweight, efficient, and easy to integrate for global state)
- **UI Library/Styling:** Tailwind CSS (for rapid, utility-first styling and customizability)
- **Mapping Library:** MapLibre GL JS (for powerful, vector-based map rendering)
- **Data Fetching:** Axios (for making HTTP requests to the backend API) and native WebSocket API for real-time streams.
- **Charting Library (Optional for MVP, but good for future):** Chart.js or Recharts
- **Icons:** Heroicons or similar SVG icon library
- **Build Tool:** Vite
- **Deployment:** Vercel or Netlify (for easy static site deployment and CI/CD)
**3. CORE FEATURES:**
- **Real-time Data Aggregation & Visualization:**
- **User Flow:** Upon loading the application, the user is presented with the main dashboard. Real-time data streams for ADS-B, AIS, and GDELT are automatically connected via WebSockets. Data points appear on the MapLibre map as they are received.
- **Details:** The backend (assumed to be a separate Python/FastAPI service, details not required for frontend prompt but contextually relevant) processes and pushes GeoJSON updates. The frontend must efficiently handle these updates, potentially thousands per minute, applying viewport culling and state debouncing to maintain performance.
- **Interactive Map Interface:**
- **User Flow:** Users can pan, zoom, and interact with the map. Clicking on an aircraft, ship, or conflict marker displays a tooltip or sidebar with key information (e.g., flight number, ship name, conflict details, NAC-P value).
- **Details:** MapLibre GL JS will be configured with appropriate layers for base maps, vector tiles, and real-time data overlays. Markers will be dynamically added, removed, and updated. Tooltips will be implemented as React components, positioned relative to map features.
- **Signal Layer (GPS Jamming Zones):**
- **User Flow:** A dedicated map layer can be toggled on/off. When active, it visually represents calculated GPS jamming zones based on aggregated NAC-P data from nearby flights. This layer updates in real-time.
- **Details:** This requires specific data processing (either on the backend or potentially optimized frontend logic if feasible) to translate NAC-P readings into geographical jamming zone polygons. The visualization will use MapLibre's polygon rendering capabilities.
- **Data Filtering and Search:**
- **User Flow:** A search bar allows users to find specific flights, ships, or locations. Filter controls (e.g., by data type, region, time range) are available, enabling users to narrow down the displayed information.
- **Details:** Frontend state management (Zustand) will handle filter parameters. Map markers will be filtered based on these parameters, and potentially backend queries will be optimized if necessary for large datasets.
- **Customizable Watchlists & Notifications:**
- **User Flow:** Users can select specific assets (flights, ships) or areas of interest to add to a personal watchlist. The system provides notifications for significant events related to these items (e.g., an aircraft entering a jamming zone, a new conflict reported in a watched area).
- **Details:** Watchlist items will be stored in local state or potentially synced to a backend if user accounts are implemented later. Notifications will be handled via UI elements (e.g., toast messages, badge counts) and potentially browser notifications.
**4. UI/UX DESIGN:**
- **Layout:** Single-page application. A main map view occupies the largest portion of the screen. A collapsible sidebar or top bar will house search, filters, layer toggles, and watchlist. A small status indicator will show connection status to data streams.
- **Color Palette:** Primarily dark theme (deep blues, grays, blacks) for a professional, focused feel, reminiscent of the 'movie hacker' aesthetic but refined. Accent colors (e.g., vibrant blues for aircraft, greens for ships, reds for conflicts, pulsating oranges/yellows for jamming zones) will be used sparingly for data visualization and alerts. White or light gray for text and essential UI elements.
- **Typography:** Clean, modern sans-serif font (e.g., Inter, Roboto, or Tailwind's default). Clear hierarchy with distinct heading and body text styles.
- **Responsive Design:** Mobile-first approach. The map should be fully usable on smaller screens, perhaps with a simplified control overlay. Sidebar/controls should adapt gracefully. Ensure touch interactions are smooth.
- **Aesthetic:** Blend the 'movie hacker' vibe with a professional, high-performance tool. Subtle animations, clean lines, and clear data presentation are key.
**5. DATA MODEL (Frontend State using Zustand):**
- **`mapState`:** `{ zoom: number, center: [number, number], bounds: [[number, number], [number, number]] }`
- **`dataStreams`:** `{ adsb: { connected: boolean, lastUpdate: timestamp }, ais: { connected: boolean, lastUpdate: timestamp }, gdelt: { connected: boolean, lastUpdate: timestamp }, satellites: { connected: boolean, lastUpdate: timestamp } }`
- **`features`:** `{ aircraft: Feature[], ships: Feature[], satellites: Feature[], conflicts: Feature[], jammingZones: Feature[] }`
- `Feature` structure (GeoJSON-like):
`{ id: string, type: 'Point' | 'Polygon', geometry: { type: 'Point', coordinates: [number, number] } | { type: 'Polygon', coordinates: [Array<Array<[number, number]>>] }, properties: { name?: string, callsign?: string, mmsi?: string, satelliteName?: string, conflictType?: string, timestamp: number, nacP?: number, ...anyOtherRelevantData } }`
- **`filters`:** `{ type: 'all' | 'aircraft' | 'ships' | 'conflicts' | 'satellites', searchString: string, region: string | null }`
- **`uiState`:** `{ sidebarOpen: boolean, activeTooltip: { featureId: string | null, position: [number, number] }, notification: { message: string, type: 'info' | 'warning' | 'error' } | null }`
- **`watchlist`:** `{ items: string[] }` // Array of feature IDs
**Mock Data Example (`features.aircraft[0]`):**
```json
{
"id": "ADS-B-123456",
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-74.0060, 40.7128] // Longitude, Latitude
},
"properties": {
"callsign": "N123AA",
"origin": "KJFK",
"destination": "KLAX",
"altitude": 35000,
"speed": 500,
"track": 270,
"timestamp": 1678886400,
"nacP": 9.5 // Navigation Accuracy - Position
}
}
```
**Mock Data Example (`features.ships[0]`):**
```json
{
"id": "AIS-987654321",
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [2.3522, 48.8566] // Paris
},
"properties": {
"name": "MV TRADEWIND",
"mmsi": "256789012",
"imo": "1234567",
"speed": 15.5,
"course": 180,
"timestamp": 1678886460
}
}
```
**Mock Data Example (`features.conflicts[0]`):**
```json
{
"id": "GDELT-Conflict-XYZ",
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [34.7818, 31.5225] // Gaza Strip
},
"properties": {
"eventCode": "041", // Example GDELT event code
"eventType": "Conflict / Protest",
"intensity": 3,
"timestamp": 1678887000,
"description": "Reported skirmishes in southern Gaza."
}
}
```
**Mock Data Example (`features.satellites[0]`):**
```json
{
"id": "SAT-ISS-001",
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-118.2437, 34.0522] // Los Angeles
},
"properties": {
"satelliteName": "ISS (ZARYA)",
"tleLine1": "1 25544U 98067A 23085.50000000 .00002500 00000-0 49322-4 0 9993",
"tleLine2": "2 25544 51.6416 247.4624 0006700 130.5200 229.7400 15.49734877 39494",
"timestamp": 1678887100
}
}
```
**Mock Data Example (`features.jammingZones[0]`):**
```json
{
"id": "JAMMING-ZONE-ABC",
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [[[
[-75.0, 41.0],
[-73.0, 41.0],
[-73.0, 39.0],
[-75.0, 39.0],
[-75.0, 41.0] // Close the polygon
]]]
},
"properties": {
"sourceIds": ["ADS-B-123456", "ADS-B-789012"], // IDs of aircraft contributing
"avgNacP": 8.2,
"timestamp": 1678886400,
"radiusEstimate": 150 // Estimated radius in km
}
}
```
**6. COMPONENT BREAKDOWN:**
- **`App.jsx`:** Main application component. Sets up context/store, main layout, and routing (if any planned beyond SPA).
- Props: None
- Responsibility: Root component, initializes state management, renders main layout.
- **`MapComponent.jsx`:** Wrapper for MapLibre GL JS.
- Props: `features`, `mapState`, `onMapMove`, `onMarkerClick`
- Responsibility: Initializes and manages the MapLibre map instance, renders base map layers, dynamically adds/updates/removes data markers (aircraft, ships, etc.) and jamming zones based on props.
- **`Sidebar.jsx`:** Collapsible sidebar for controls.
- Props: `isOpen`, `onClose`, `onSearch`, `onFilterChange`, `watchlistItems`, `onAddToWatchlist`
- Responsibility: Contains search bar, filter controls, watchlist display, and layer toggles. Manages UI state for these controls.
- **`SearchBar.jsx`:** Input component for searching features.
- Props: `onSearch`
- Responsibility: Handles user input for search queries.
- **`FilterControls.jsx`:** UI elements for filtering data (e.g., checkboxes, dropdowns).
- Props: `currentFilters`, `onFilterChange`
- Responsibility: Renders and manages the state of various filter options.
- **`Watchlist.jsx`:** Displays the user's watchlist items.
- Props: `items`, `allFeatures`, `onRemoveFromWatchlist`
- Responsibility: Lists watched items, potentially showing their current status or location on the map.
- **`Marker.jsx`:** (Abstract concept, likely rendered within `MapComponent`)
- Props: `feature`, `onClick`, `isActive`
- Responsibility: Renders individual map markers (icons for planes, ships, etc.) with appropriate styling and click handlers.
- **`Tooltip.jsx`:** Displays information when a marker is hovered or clicked.
- Props: `feature`, `position`
- Responsibility: Dynamically renders and positions tooltips with feature details.
- **`Notification.jsx`:** Toast or banner for displaying messages/alerts.
- Props: `message`, `type`, `onClose`
- Responsibility: Manages the display and dismissal of user notifications.
- **`StatusIndicator.jsx`:** Shows connection status for data streams.
- Props: `streamStatus` (object containing connection status for each stream)
- Responsibility: Visually indicates if the real-time data feeds are active.
**7. ANIMATIONS & INTERACTIONS:**
- **Map Markers:** Smooth entry/exit animations when features are added/removed. Subtle pulsing for high-priority alerts or jamming zones. Smooth transitions for marker position updates.
- **Sidebar:** Smooth slide-in/slide-out animation for the sidebar.
- **Tooltips/Popups:** Fade-in/fade-out effect for tooltips appearing and disappearing.
- **Loading States:** Implement skeleton loaders or subtle spinners within the map or sidebar areas while data is initially loading or refreshing. Display connection status indicators clearly.
- **Hover Effects:** Subtle background highlight on interactive elements (buttons, list items) and markers on hover.
- **General Transitions:** Use Tailwind CSS transitions for smooth changes in UI element states (e.g., filter toggles, sidebar collapse/expand).
**8. EDGE CASES:**
- **No Data:** When no data feeds are connected or no features match the current filters, display clear messages (e.g., 'Connecting to data streams...', 'No aircraft found in this region.'). Avoid showing an empty, blank map.
- **API Errors:** Implement robust error handling for WebSocket disconnections or API request failures. Display user-friendly error messages and attempt reconnection logic.
- **Map Performance:** Aggressive viewport culling (only rendering markers within the current map view) is crucial. Debounce frequent state updates (e.g., marker position changes) to prevent performance degradation. Optimize GeoJSON payload processing. Consider using Mapbox GL Draw or similar for efficient polygon rendering if jamming zones become complex.
- **Validation:** Basic validation for any user input (e.g., search query length). Ensure data integrity on the frontend, although primary validation should be on the backend.
- **Accessibility (a11y):** Use semantic HTML elements. Ensure proper ARIA attributes for interactive elements. Provide keyboard navigation support for controls. Ensure sufficient color contrast, especially for text and important map data.
- **Browser Compatibility:** Test across modern browsers (Chrome, Firefox, Safari, Edge). Ensure MapLibre GL JS compatibility.
- **Data Gaps:** Handle potential gaps or inconsistencies in real-time data gracefully.
**9. DEPLOYMENT NOTES:**
- **Environment Variables:** Use `.env` files for API keys (if any external services are used), base URLs, and configuration settings. Ensure these are correctly managed in the deployment environment (e.g., Vercel environment variables).
- **Build Optimization:** Configure Vite for production builds (`vite build`). Optimize assets (images, CSS, JS) for performance. Implement code splitting if the application grows significantly.
- **HTTPS:** Ensure the application is served over HTTPS, especially if using WebSockets.
- **CORS:** If the frontend and backend are on different domains, configure CORS appropriately on the backend.
- **CDN:** Utilize a CDN for static assets to improve loading times.
- **Performance Monitoring:** Integrate basic performance monitoring tools or use platform-provided analytics to track load times and identify bottlenecks.
- **Error Reporting:** Set up a client-side error reporting service (e.g., Sentry) to capture and analyze runtime errors.