PROJECT OVERVIEW:
The project is to develop a single-page React application named 'Doğa Gözlemci' (Nature Observer). This application aims to be a mobile-first, AI-powered platform for identifying species through photos, suggesting personalized nature exploration routes, and maximizing scientific data contribution. It's inspired by iNaturalist but focuses on a streamlined, user-friendly mobile experience, leveraging AI for faster and more accurate species identification. The core value proposition is making nature observation and scientific contribution accessible and engaging for everyone, anytime, anywhere.
TECH STACK:
- Frontend Framework: React (using Vite for fast development setup)
- Styling: Tailwind CSS for utility-first styling and rapid UI development.
- State Management: Zustand for efficient and simple global state management.
- Routing: React Router DOM for client-side routing within the SPA.
- API Calls: Axios for making HTTP requests.
- Icons: React Icons for a comprehensive set of icons.
- Animations: Framer Motion for declarative animations and transitions.
- Form Handling: React Hook Form for efficient form validation and submission.
- Image Upload/Processing: Potentially Cloudinary or a similar service for image handling and AI integration.
- AI Integration: Placeholder for a backend API (e.g., a Python Flask/FastAPI backend with a pre-trained image recognition model like ResNet or a Vision Transformer) that handles species identification.
CORE FEATURES:
1. **AI Species Identification:**
* User flow: User taps 'Identify Species' button. Camera or photo library access is requested. User takes/selects a photo. Photo is uploaded to the backend AI model. The model returns top N potential species with confidence scores. User reviews suggestions, selects the correct one, and confirms.
* Details: Frontend captures image, sends base64 or URL to backend. Backend processes image, returns JSON with species names, scientific names, confidence scores, and potentially links to more information. UI displays results in a clear, ranked list. "Add Observation" button is prominent.
2. **Observation Logging & Mapping:**
* User flow: After identification or manual entry, user adds details (date, time, location (auto-detected or manual), notes, additional photos). User saves the observation. The observation is added to the user's personal list and plotted on a map.
* Details: Form for observation details. Location services integration (navigator.geolocation). Map component (e.g., Leaflet or Mapbox GL JS) displays user's observations as markers. Clicking a marker shows a summary and link to the full observation detail page.
3. **Personal Observation Dashboard:**
* User flow: User navigates to 'My Observations' or 'Dashboard' section. A list or grid of their past observations is displayed, sortable and filterable by date, species, or location. Users can view detailed observation pages, edit, or delete entries.
* Details: Displays a chronologically sorted list of observations. Includes thumbnails, species name, date, and location snippet. Detail view shows all information, notes, images, map location, and edit/delete options. Supports life lists (e.g., 'Birds I've Seen').
4. **Community Exploration:**
* User flow: User navigates to 'Explore' or 'Community' section. A map view shows recent observations from other users (anonymized or with permission). Users can filter by species, location, or time. Tapping an observation shows details and allows interaction (e.g., comments, verification).
* Details: Public feed of observations. Map-based browsing. Filtering options. User profiles (minimal: username, observation count). Ability to 'like' or comment on observations.
5. **Scientific Contribution:**
* User flow: During observation saving, the user is prompted if they consent to share their anonymized data for scientific research. If agreed, data is sent to a designated scientific repository API (simulated in MVP).
* Details: Clear opt-in mechanism. Data shared includes species, location (generalized if requested), date/time. No personally identifiable information beyond basic user ID if required for tracking contributions.
UI/UX DESIGN:
- Layout: Mobile-first, single-column layout adapting to larger screens. Bottom navigation bar for core sections (Identify, Explore, My Observations, Profile/Settings). Clear headers and intuitive iconography.
- Color Palette: Primary: Earthy greens (#4CAF50, #8BC34A) and blues (#2196F3, #03A9F4) evoking nature. Secondary: Neutral grays (#F5F5F5 for backgrounds, #757575 for text) and a warm accent color (e.g., orange #FF9800) for calls-to-action.
- Typography: Clean, readable sans-serif font (e.g., Inter or Roboto). Clear hierarchy using font sizes and weights.
- Responsive Design: Utilizes Tailwind CSS's responsive modifiers (sm:, md:, lg:) to ensure seamless experience on devices from small smartphones to desktops.
- Interactivity: Smooth transitions between views, subtle hover effects on buttons and cards, clear loading indicators.
COMPONENT BREAKDOWN:
- `App.js`: Main application component, sets up routing and global layout.
- `Navbar.js`: Bottom navigation bar component.
- `IdentifyScreen.js`: Main screen for AI identification. Contains `CameraComponent` and `ResultDisplayComponent`.
- `CameraComponent.js`: Handles camera access, photo capture, and image upload.
- `ResultDisplayComponent.js`: Shows AI identification suggestions.
- `ObservationForm.js`: Form for adding/editing observation details.
- `MapComponent.js`: Displays a map with observation markers (e.g., using Leaflet).
- `ObservationList.js`: Displays a list of observations.
- `ObservationCard.js`: Represents a single observation in a list or grid.
- `ExploreScreen.js`: Screen for browsing community observations.
- `ProfileScreen.js`: User profile and settings.
- `Button.js`: Reusable button component with variants.
- `Input.js`: Reusable input field component.
- `LoadingSpinner.js`: Generic loading indicator.
- `Modal.js`: Reusable modal component.
Props examples:
- `ObservationCard` might receive `observation` object (id, speciesName, date, location, thumbnailUrl) and `onClick` handler.
- `CameraComponent` might receive `onPhotoCapture` callback.
- `ResultDisplayComponent` might receive `suggestions` array and `onSelectSuggestion` handler.
DATA MODEL (using Zustand for state management):
- `userStore`: { id, username, email, observationCount, settings }
- `observationsStore`: { list: [], currentObservation: null, loading: false, error: null }
- `identificationStore`: { suggestions: [], selectedSpecies: null, loading: false, error: null }
- `mapStore`: { center, zoom, markers: [] }
Mock Data Format (for `observationsStore.list`):
```json
[
{
"id": "obs_123",
"userId": "user_abc",
"speciesName": "Kırmızı Karıncayiyen",
"scientificName": "Myrmecophaga tridactyla",
"timestamp": "2023-10-27T10:00:00Z",
"location": {
"latitude": -12.3456,
"longitude": -67.8901,
"accuracy": 15
},
"notes": "Ormanlık alanda görüldü.",
"imageUrls": ["/images/obs_123_thumb.jpg"],
"aiConfidence": 0.92,
"tags": ["memeli", "tehlikedeki tür"]
},
{
"id": "obs_456",
"userId": "user_xyz",
"speciesName": "Sarı Kanatlı Kelebek",
"scientificName": "Gonepteryx rhamni",
"timestamp": "2023-10-26T15:30:00Z",
"location": {
"latitude": -10.1111,
"longitude": -55.2222,
"accuracy": 5
},
"notes": "Parkta çiçeklerin üzerinde.",
"imageUrls": ["/images/obs_456_thumb.jpg"],
"aiConfidence": 0.88,
"tags": ["kelebek", "böcek"]
}
]
```
Mock Data Format (for `identificationStore.suggestions`):
```json
[
{
"speciesName": "Kırmızı Karıncayiyen",
"scientificName": "Myrmecophaga tridactyla",
"confidence": 0.92,
"imageUrl": "/images/suggestion1.jpg"
},
{
"speciesName": "Dev Karıncayiyen",
"scientificName": "Myrmecophaga gigantea",
"confidence": 0.75,
"imageUrl": "/images/suggestion2.jpg"
}
]
```
ANIMATIONS & INTERACTIONS:
- **Page Transitions:** Use Framer Motion's `AnimatePresence` and `motion.div` for smooth fade-in/fade-out transitions between screens.
- **Button Hovers:** Subtle background color change or slight scale-up effect on button hover using Tailwind CSS hover states and Framer Motion.
- **Card Interactions:** Slight shadow lift or scale effect on `ObservationCard` hover.
- **Loading States:** `LoadingSpinner` component displayed during data fetching (API calls for identification, observations). Overlay or inline loading indicators.
- **Image Upload:** Visual feedback during upload (progress bar or pulsing animation).
- **Map Pin Animations:** Subtle bounce or pulse animation for new markers appearing on the map.
- **Micro-interactions:** Animated checkmark upon successful observation save.
EDGE CASES:
- **No Camera/Geolocation Permission:** Gracefully degrade functionality. Prompt user to enable permissions in settings. Provide manual input options.
- **AI Identification Fails:** Display a clear error message. Suggest retrying or manual identification. Handle empty suggestions array from API.
- **No Network Connection:** Inform the user. Cache observations locally using `localStorage` or `IndexedDB` for later sync.
- **Empty States:** Display user-friendly messages and illustrations for empty observation lists, no search results, or empty explore feeds. Guide users on how to add their first observation.
- **Form Validation:** Implement client-side validation (using `react-hook-form`) for required fields (species, location, date). Provide clear error messages next to fields.
- **Accessibility (a11y):** Use semantic HTML5 elements. Ensure sufficient color contrast. Add ARIA attributes where necessary (e.g., for dynamic content). Ensure keyboard navigability for all interactive elements.
- **Large Data Sets:** Implement pagination or infinite scrolling for `ObservationList` and community feeds.
- **Duplicate Observations:** Basic check for duplicate entries based on species, location, and time.
SAMPLE DATA (Beyond the Data Model examples):
1. **User Profile:**
```json
{ "id": "user_abc", "username": "NatureLover123", "email": "user@example.com", "observationCount": 52, "settings": { "receiveNotifications": true, "shareDataAnonymously": true } }
```
2. **Species Info (for detailed view):
```json
{ "scientificName": "Quercus robur", "commonNames": ["Sapsan Meşesi", "Adi Meşe"], "description": "Geniş yapraklı, dayanıklı bir meşe türü...", "habitat": "Avrupa genelinde yaygındır...", "conservationStatus": "LC (Least Concern)", "imageUrl": "/images/quercus_robur.jpg" }
```
3. **Community Observation (for Explore screen):
```json
{ "id": "obs_789", "speciesName": "Boz Ayı", "scientificName": "Ursus arctos", "timestamp": "2023-10-27T08:15:00Z", "location": {"latitude": 40.1234, "longitude": 29.5678}, "username": "WildExplorer", "observationThumbnailUrl": "/images/obs_789_thumb.jpg", "isVerified": true }
```
4. **Error Message Object:
```json
{ "code": "API_ERROR", "message": "Tür tanımlanamadı. Lütfen tekrar deneyin veya manuel giriş yapın." }
```
5. **Settings for a specific observation:
```json
{ "isPublic": true, "allowDataSharing": true, "notes": "Sabah yürüyüşünde fark edildi.", "tags": ["memeli", "yaban hayatı"] }
```
6. **Project Data (for potential future feature):
```json
{ "projectId": "proj_bio_atlas", "name": "Türkiye Biyoçeşitlilik Atlası", "description": "Türkiye'deki kuş türlerinin dağılımını haritalama...", "goal": "100000 gözlem", "contributors": 580 }
```
7. **User Interaction Data:
```json
{ "observationId": "obs_789", "userId": "user_abc", "type": "comment", "text": "Harika bir gözlem!", "timestamp": "2023-10-27T11:00:00Z" }
```
8. **Map Marker Data:
```json
{ "lat": 40.1234, "lng": 29.5678, "observationId": "obs_789", "speciesName": "Boz Ayı", "thumbnailUrl": "/images/obs_789_thumb.jpg" }
```
DEPLOYMENT NOTES:
- **Build Tool:** Vite. Run `npm run build` for production build.
- **Environment Variables:** Use `.env` files for API keys (e.g., `VITE_AI_API_ENDPOINT`, `VITE_MAPBOX_TOKEN`). Ensure sensitive variables are not exposed client-side.
- **Static Assets:** Optimize images (`.jpg`, `.png`, `.webp`). Use a CDN for faster delivery if deployed on a large scale.
- **Performance:** Code splitting with React Lazy and Suspense. Memoization using `React.memo` and `useMemo`/`useCallback` where appropriate. Tree shaking through Vite.
- **PWA Considerations:** Implement a `manifest.json` and service worker for offline capabilities and 'add to home screen' functionality, making it feel more like a native app.
- **HTTPS:** Ensure deployment uses HTTPS for secure data transmission.
- **Error Tracking:** Integrate a service like Sentry for client-side error monitoring.
- **Testing:** Consider unit tests (Jest, Vitest) and integration tests for core components and features.