PROJECT OVERVIEW:
**Application Name:** MinaScan
**Purpose:** To create a real-time, crowdsourced platform for mapping and raising awareness about landmine and explosive remnant of war (ERW) risks globally, inspired by heroic animal efforts like Magawa the mine-sniffing rat. It aims to empower communities, aid humanitarian demining efforts, and prevent accidental detonations.
**Problem Solved:** Landmine contamination is a persistent global threat, especially in post-conflict regions like Cambodia. Existing data is often outdated, fragmented, or inaccessible to the general public and smaller NGOs. MinaScan addresses this by providing a centralized, continuously updated, and user-friendly platform for risk identification, reporting, and education.
**Value Proposition:** MinaScan offers a unique blend of real-time risk visualization, community-driven data collection, and accessible educational content, creating a vital tool for safety, awareness, and humanitarian action in contaminated areas. It honors the spirit of creatures like Magawa by leveraging collective human intelligence and technology to mitigate similar dangers.
TECH STACK:
**Frontend:** React.js (using Vite for fast development setup)
**Styling:** Tailwind CSS for utility-first styling and rapid UI development.
**State Management:** Zustand for efficient global and local state management.
**Routing:** React Router DOM for client-side routing.
**Mapping Library:** Leaflet.js with `react-leaflet` for interactive map rendering.
**Icons:** Heroicons for clean, scalable SVG icons.
**Forms:** React Hook Form for efficient form handling and validation.
**API Interaction:** Axios for making HTTP requests.
**Utilities:** Date-fns for date manipulation.
CORE FEATURES:
1. **Interactive Landmine Risk Map:**
* **User Flow:** Upon loading the app, the user sees a world map centered on their location or a default view. Map markers indicate areas with reported risks (color-coded by severity/recency). Users can pan, zoom, and click on markers to view details (report date, type of risk, user notes, photos if available). A search bar allows users to find specific locations. A "Report Risk" button is prominently displayed.
* **Details:** Uses Leaflet.js. Markers represent reported incidents. Clicking a marker opens a modal with report details.
2. **Risk Reporting System:**
* **User Flow:** User clicks the "Report Risk" button. A modal or dedicated form appears. User selects the type of risk (suspected mine, visible ERW, cleared area, safe zone, etc.), optionally uploads photos/videos, adds descriptive notes, and confirms the location (auto-detected or manually placed on map). Submission triggers data creation.
* **Details:** Utilizes React Hook Form for validation (e.g., location required, notes optional but encouraged). Photo upload handled via a standard input, potentially with a preview.
3. **Educational Content Module:**
* **User Flow:** User navigates to the "Learn" section via the main menu. They see a list of articles/sections (e.g., "Understanding Landmines", "Safety Procedures", "Magawa's Story", "What to Do If You Find a Device"). Clicking a section displays the content.
* **Details:** Simple content display pages. Content should be concise, factual, and easy to understand. Could include images or embedded videos.
4. **User Profile & Contributions:**
* **User Flow:** Logged-in users can access their profile. They see a summary of their reported risks, educational content read, and potentially a reputation score. This encourages engagement and provides a sense of accomplishment.
* **Details:** Basic profile view. For MVP, authentication might be simplified (e.g., anonymous reporting with optional basic signup).
UI/UX DESIGN:
**Layout:** Single Page Application (SPA) structure. A persistent header with the app logo and navigation (Map, Report, Learn, Profile). The main content area dynamically changes based on the selected route. A footer with copyright and essential links.
**Color Palette:** Primary: A calming but serious blue (#3B82F6). Secondary: Alert/Warning orange/red for high-risk markers (#EF4444). Accent: A neutral gray for text and backgrounds (#E5E7EB). Tertiary: Green for safe/cleared zones (#10B981).
**Typography:** Use a clean, readable sans-serif font like Inter or Roboto for all text. Ensure good contrast ratios.
**Responsiveness:** Mobile-first design. Use Tailwind CSS's responsive prefixes (sm:, md:, lg:) to ensure the map, forms, and content adapt seamlessly to various screen sizes. Map controls should be easily accessible on touch devices.
**Interactions:** Smooth transitions between pages/sections. Clear visual feedback on button clicks and form submissions. Loading spinners for asynchronous operations (map data loading, form submission).
COMPONENT BREAKDOWN:
* **`App.js`:** Main application component, sets up routing and global layout.
* **`Header.js`:** Contains the logo and navigation links.
* **`MapComponent.js`:** Renders the Leaflet map, handles map interactions, fetches and displays risk markers. Props: `riskData` (array of risk objects).
* **`RiskMarker.js`:** Represents a single risk marker on the map. Receives `position` (lat/lng) and `details` (object with report info) as props.
* **`ReportFormModal.js`:** Modal for submitting new risk reports. Manages form state, validation, and submission logic. Props: `isOpen` (boolean), `onClose` (function), `onSubmit` (function).
* **`FormField.js`:** Reusable form input component (text, textarea, file upload). Props: `label`, `type`, `name`, `control`, `errors`.
* **`ContentPage.js`:** Displays educational articles. Props: `contentTitle`, `contentBody`.
* **`LearnNav.js`:** Sidebar or list for navigating educational content sections.
* **`ProfilePage.js`:** Displays user profile information and contribution history.
* **`LoadingSpinner.js`:** Reusable loading indicator.
DATA MODEL:
* **`RiskReport` Object:**
```json
{
"id": "string (uuid)",
"latitude": number,
"longitude": number,
"type": "string (mine|erw|suspected|cleared|safe_zone)",
"severity": "string (low|medium|high)",
"notes": "string (optional)",
"imageUrl": "string (optional)",
"timestamp": "string (ISO 8601 date-time)",
"reporterId": "string (user id or null for anonymous)"
}
```
* **`UserProfile` Object:**
```json
{
"id": "string (uuid)",
"username": "string (optional)",
"reportCount": number,
"educationProgress": "array (list of completed content IDs)"
}
```
* **State Structure (Zustand):**
* `mapStore`: `bearsStore(set) => ({
markers: [],
fetchMarkers: async () => { /* API call */ },
addMarker: (newMarker) => set(state => ({ markers: [...state.markers, newMarker] }))
})`
* `reportStore`: `bearsStore(set) => ({
isReporting: false,
formData: { lat: null, lng: null, type: '', notes: '' },
setFormData: (data) => set({ formData: data }),
submitReport: async () => { /* API call */ }
})`
* `contentStore`: `bearsStore(set) => ({ contents: [], fetchContents: async () => {} })`
ANIMATIONS:
* **Map Markers:** Subtle pulse animation for high-severity markers to draw attention.
* **Transitions:** Fade-in/fade-out transitions for modals and page content using `react-transition-group` or CSS transitions.
* **Loading States:** Implement `react-loader-spinner` or custom SVG spinners for map data loading and form submissions. Button states should indicate loading.
* **Hover Effects:** Slight scale-up or shadow effect on map markers and navigation links on hover.
EDGE CASES:
* **No Risk Data:** If no reports exist for an area, the map should display a default message or state rather than being empty.
* **Offline Mode:** Consider basic caching of map tiles and previously viewed content for limited offline access (future enhancement).
* **Error Handling:** Gracefully handle API errors (network issues, server errors) by displaying user-friendly messages. Implement form validation errors clearly.
* **Location Permissions:** Prompt users for location access when needed, with clear explanations. Handle denied permissions gracefully.
* **Accessibility (a11y):** Ensure proper ARIA attributes, keyboard navigation support, sufficient color contrast, and semantic HTML structure.
* **Data Validation:** Implement robust server-side validation in addition to client-side validation for all submitted reports.
SAMPLE DATA:
1. **`RiskReport` Example 1 (Mine):**
```json
{
"id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"latitude": 11.5567,
"longitude": 104.9211,
"type": "mine",
"severity": "high",
"notes": "Suspected anti-personnel mine spotted near the old rice paddy. Looks metallic, about 4 inches across.",
"imageUrl": "https://example.com/images/mine1.jpg",
"timestamp": "2023-10-27T10:30:00Z",
"reporterId": "user123"
}
```
2. **`RiskReport` Example 2 (ERW):**
```json
{
"id": "b2c3d4e5-f6a7-8901-2345-67890abcdef1",
"latitude": 11.5600,
"longitude": 104.9250,
"type": "erw",
"severity": "medium",
"notes": "Unidentified explosive device found on the roadside. Possibly a mortar round. Keep distance.",
"imageUrl": null,
"timestamp": "2023-10-26T15:00:00Z",
"reporterId": null
}
```
3. **`RiskReport` Example 3 (Cleared Area):**
```json
{
"id": "c3d4e5f6-a7b8-9012-3456-7890abcdef12",
"latitude": 11.5500,
"longitude": 104.9100,
"type": "cleared",
"severity": "low",
"notes": "Area north of the market confirmed cleared by local EOD team on 2023-10-25.",
"imageUrl": null,
"timestamp": "2023-10-25T09:00:00Z",
"reporterId": "ngo_agent_007"
}
```
4. **`UserProfile` Example 1:**
```json
{
"id": "user123",
"username": "MineHunter",
"reportCount": 15,
"educationProgress": ["understanding_mines", "safety_procedures"]
}
```
5. **`EducationalContent` Mock Data:**
```json
{
"id": "understanding_mines",
"title": "Understanding Landmines",
"summary": "Learn about different types of landmines and their dangers.",
"body": "Landmines are buried explosive devices... [Full content here]..."
}
```
6. **`EducationalContent` Mock Data:**
```json
{
"id": "magawas_story",
"title": "The Heroism of Magawa",
"summary": "Read about the incredible life and work of Magawa, the heroic rat.",
"body": "Magawa, an African giant pouched rat, became a hero... [Full content here]..."
}
```
DEPLOYMENT NOTES:
* **Build Command:** `npm run build` or `yarn build`.
* **Environment Variables:** Use `.env` files for API keys (e.g., `REACT_APP_MAPBOX_TOKEN` if using Mapbox, or Leaflet tile layers). Define `NODE_ENV=production` for the build.
* **Performance:** Optimize React components using `React.memo` and `useCallback` where appropriate. Lazy load components and map data. Ensure efficient state management updates. Optimize image loading.
* **Hosting:** Deploy to static hosting platforms like Vercel, Netlify, or GitHub Pages for SPA.
* **API:** Assumes a backend API exists for data persistence (e.g., Node.js/Express, Python/Django). The prompt focuses on the frontend implementation.