PROJECT OVERVIEW:
The application, tentatively named 'Nature Discoveries: Unusual Trees Guide' (Doğa Keşifleri: Sıradışı Ağaçlar Rehberi), is a mobile-first SaaS platform designed to allow users to discover, learn about, and locate unusual and remarkable tree species around the world. Inspired by a Hacker News post about intriguing trees like mangroves and banyan trees, the platform aims to foster a deeper appreciation for nature's diversity. Users can explore a curated database of unique trees, view their geographical distribution on an interactive map, access detailed information about their characteristics and significance, and save trees they've 'discovered' or are interested in. The core value proposition is to provide an engaging, educational, and visually rich experience for nature enthusiasts, travelers, and anyone curious about the natural world, making botanical knowledge accessible and discoverable.
TECH STACK:
- Frontend Framework: React (using Vite for a fast development experience)
- Styling: Tailwind CSS for rapid and utility-first styling.
- State Management: Zustand for simple and scalable global state management.
- Routing: React Router DOM for navigation within the single-page application.
- Mapping Library: Leaflet with react-leaflet for interactive map display.
- Icons: React Icons for a variety of icons.
- Data Fetching: Axios for HTTP requests (if an API is implemented later, otherwise mock data from JSON).
- Build Tool: Vite
- Target Environment: Web (SPA), potentially to be wrapped as a mobile app using Capacitor/React Native later.
CORE FEATURES:
1. **Tree Discovery Hub (Main Page):
* User Flow: Upon opening the app, the user lands on the main discovery page. This page features a visually appealing grid or list of featured unusual trees. Each tree card displays a thumbnail image, its common name, and a brief descriptor. Users can scroll infinitely through a feed of trees or use a prominent search bar at the top to find specific trees by name or characteristic. Filters (e.g., by continent, tree type, notable feature) are accessible via a dedicated button.
* Details: Infinite scroll for a dynamic browsing experience. Search functionality allows keyword-based queries. Filter options refine the tree selection based on user criteria.
2. **Tree Detail View:
* User Flow: Tapping on a tree card from the discovery hub or search results navigates the user to the Tree Detail View. This screen displays comprehensive information about the selected tree. It includes high-resolution images, scientific and common names, a detailed description of its unique characteristics (e.g., root system, size, lifespan, ecological role), geographical distribution summary, and fascinating facts. A button to 'Add to My Discoveries' is prominently placed.
* Details: Rich media display (galleries/carousels). Structured information sections. Clear call-to-action for saving trees.
3. **Interactive World Map:
* User Flow: Accessible via a tab or navigation link, this feature presents a world map. Pins on the map represent the locations of known unusual trees. Users can pan, zoom, and tap on pins to see a preview of the tree (name and small image) and click through to its full detail view.
* Details: Utilizes a mapping library to display geographically tagged tree data. Cluster markers for densely populated areas. Clickable popups for quick info and navigation.
4. **My Discoveries (Personal List):
* User Flow: A dedicated section where users can view a list of trees they have saved. Each item in the list links back to the Tree Detail View. Users can also remove trees from this list.
* Details: Simple list view, possibly with sorting or filtering options. Allows personalization and tracking of user interests.
UI/UX DESIGN:
- **Layout:** Mobile-first design. A clean, single-column layout for content on smaller screens, expanding to two or three columns on larger screens. A persistent bottom navigation bar for core sections (Discover, Map, My Discoveries, Settings - for future expansion). A fixed header for search and branding.
- **Color Palette:** Earthy tones inspired by nature: deep greens, rich browns, muted blues, with pops of vibrant accent colors (e.g., a bright floral or sunset orange) for calls-to-action and highlights. Primarily uses `bg-green-50` to `bg-green-900`, `text-brown-700`, `border-green-300`. Accent color: `bg-orange-500`, `text-white`.
- **Typography:** Use a clean, readable sans-serif font like 'Inter' or 'Lato'. Headings should be clear and distinct from body text. Ensure good contrast for readability.
- **Responsive Design:** Utilize Tailwind CSS's responsive modifiers (e.g., `sm:`, `md:`, `lg:`) extensively. Ensure fluid layouts that adapt gracefully from small mobile screens to large desktop monitors. Navigation might collapse into a hamburger menu on very small screens if necessary, but a bottom tab bar is preferred for mobile.
- **Components:** Card-based design for tree listings. Clear visual hierarchy. Generous use of whitespace.
COMPONENT BREAKDOWN:
- `App.jsx`: Main application component, sets up routing.
- `Layout.jsx`: Wraps all pages, includes header and bottom navigation.
- `Header.jsx`: Contains the app logo/title and the search bar.
- `BottomNav.jsx`: Navigation component with links to Discover, Map, and My Discoveries.
- `DiscoverPage.jsx`: Main landing page. Fetches and displays the list of trees using `TreeList.jsx`. Includes filter controls.
- `TreeList.jsx`: Renders a list or grid of `TreeCard` components. Handles infinite scrolling logic.
- `TreeCard.jsx`: Displays a single tree's summary information (image, name, description). Accepts `tree` object as prop.
- `TreeDetailPage.jsx`: Displays full details for a single tree. Fetches data based on ID from URL params. Includes image gallery, description, map link, and 'Add to Discoveries' button.
- `ImageGallery.jsx`: Component for displaying multiple images of a tree, potentially with carousel functionality.
- `MapView.jsx`: Integrates the Leaflet map. Fetches tree locations and displays markers. Accepts `trees` array as prop.
- `MarkerPopup.jsx`: Small component displayed when a map marker is clicked, showing tree name and a link.
- `MyDiscoveriesPage.jsx`: Displays the user's saved trees using `TreeList.jsx` (filtered for saved items). Includes 'Remove' functionality.
- `SearchBar.jsx`: Input component for tree search.
- `FilterDropdown.jsx`: Component for selection filters.
- `LoadingSpinner.jsx`: Basic spinner component for loading states.
- `EmptyState.jsx`: Component to display when lists or search results are empty.
DATA MODEL:
- **`Tree` Object Structure:**
```json
{
"id": "string", // Unique identifier (e.g., 'mangrove_001')
"commonName": "string", // e.g., 'Mangrove'
"scientificName": "string", // e.g., 'Rhizophora mangle'
"description": "string", // Detailed botanical and ecological description
"funFacts": ["string"], // Array of interesting facts
"imageUrl": "string", // URL to a primary image
"galleryImages": ["string"], // URLs for additional images
"distribution": {
"summary": "string", // e.g., 'Coastal regions worldwide'
"continents": ["string"], // e.g., ['Asia', 'Africa', 'Americas']
"coordinates": {
"lat": "number", // Example latitude
"lng": "number" // Example longitude
}
},
"tags": ["string"] // e.g., ['coastal', 'salt-tolerant', 'unique roots']
}
```
- **State Management (Zustand):**
* `useTreeStore`: Manages the list of all trees (`allTrees`), filtered trees (`filteredTrees`), loading state (`isLoading`), and error state (`error`). Functions for fetching trees, filtering trees.
* `useDiscoveryStore`: Manages the user's saved discoveries (`savedTrees` - array of tree IDs or full tree objects). Functions for adding, removing, and retrieving saved trees.
- **Local Storage:** Use `localStorage` to persist the `savedTrees` state across sessions for the 'My Discoveries' feature.
ANIMATIONS & INTERACTIONS:
- **Page Transitions:** Subtle fade-in/fade-out transitions between pages using libraries like `Framer Motion` or CSS transitions managed by React Router.
- **Element Transitions:** Smooth transitions for showing/hiding filter menus or loading states.
- **Hover Effects:** Subtle scaling or shadow effects on `TreeCard` components when hovered over. Interactive elements like buttons should have clear hover states (e.g., slight color change, slight lift).
- **Loading States:** Use `LoadingSpinner.jsx` component with skeleton loaders for `TreeCard` and `ImageGallery` placeholders while data is being fetched. Spinner should be centered.
- **Micro-interactions:** Smooth animations for adding/removing trees from 'My Discoveries' (e.g., a small heart icon filling or emptying). Parallax effect on background images if used.
- **Map Interactions:** Smooth zooming and panning. Popups appear with a gentle fade-in.
EDGE CASES:
- **No Trees Found:** Display `EmptyState.jsx` with a clear message (e.g., 'No trees match your search criteria. Try broadening your search.').
- **API Errors:** If fetching data fails, display an error message using `EmptyState.jsx` or a dedicated modal, with an option to retry. Log errors for debugging.
- **No Internet Connection:** Gracefully handle offline states, potentially showing cached data if available and a notification.
- **Empty Discovery List:** `MyDiscoveriesPage.jsx` should show an `EmptyState.jsx` message (e.g., 'You haven't discovered any trees yet. Start exploring!').
- **Image Loading Errors:** Individual images in the gallery should have fallback states or be hidden if they fail to load.
- **Accessibility (a11y):** Ensure proper ARIA attributes, keyboard navigation support, sufficient color contrast, and semantic HTML structure. Alt text for all meaningful images.
- **Data Validation:** Although using mock data initially, plan for validation if an API is introduced. Ensure incoming data conforms to the defined `Tree` object structure.
SAMPLE DATA (Mock Data Format - `allTrees` array):
```json
[
{
"id": "mangrove_001",
"commonName": "Mangrove",
"scientificName": "Rhizophoraceae family",
"description": "Mangroves are a group of salt-tolerant trees and shrubs found in coastal intertidal zones. They play a crucial role in coastal protection, acting as natural barriers against erosion and storm surges. Their unique prop roots help stabilize shorelines and create vital habitats for diverse marine life.",
"funFacts": [
"Mangrove seeds can germinate while still on the parent tree.",
"They filter salt from the water, allowing them to thrive in saline environments.",
"Mangrove forests are often called 'coastal rainforests'."
],
"imageUrl": "https://example.com/images/mangrove_main.jpg",
"galleryImages": [
"https://example.com/images/mangrove_roots.jpg",
"https://example.com/images/mangrove_aerial.jpg"
],
"distribution": {
"summary": "Tropical and subtropical coastlines worldwide.",
"continents": ["Asia", "Africa", "Australia", "Americas"],
"coordinates": {"lat": 15.0, "lng": 100.0} // Example central coordinate
},
"tags": ["coastal", "salt-tolerant", "roots", "ecosystem"]
},
{
"id": "banyan_002",
"commonName": "Banyan Tree",
"scientificName": "Ficus benghalensis",
"description": "The Banyan tree is known for its remarkable growth habit, where aerial roots drop from its branches, take root in the ground, and develop into new, thick trunks. A single Banyan can thus spread over a vast area, appearing like a small forest. It holds cultural and religious significance in many parts of India.",
"funFacts": [
"Some Banyan trees can cover several acres of land.",
"They can live for hundreds, sometimes thousands, of years.",
"The aerial roots are essential for the tree's massive spread and support."
],
"imageUrl": "https://example.com/images/banyan_main.jpg",
"galleryImages": [
"https://example.com/images/banyan_aerial_roots.jpg",
"https://example.com/images/banyan_vast.jpg"
],
"distribution": {
"summary": "Primarily native to the Indian subcontinent.",
"continents": ["Asia"],
"coordinates": {"lat": 20.5, "lng": 78.0}
},
"tags": ["unique growth", "large spread", "long-lived", "cultural"]
},
{
"id": "baobab_003",
"commonName": "Baobab Tree",
"scientificName": "Adansonia",
"description": "Baobab trees are iconic for their massive, swollen trunks that store water, allowing them to survive in arid climates. Native to Madagascar, mainland Africa, and Australia, they are often called the 'Tree of Life' due to their ability to provide sustenance and shelter.",
"funFacts": [
"Their trunks can store thousands of liters of water.",
"Baobab fruit is edible and highly nutritious.",
"They have a distinctive silhouette, often leafless for much of the year."
],
"imageUrl": "https://example.com/images/baobab_main.jpg",
"galleryImages": [
"https://example.com/images/baobab_trunk.jpg",
"https://example.com/images/baobab_savanna.jpg"
],
"distribution": {
"summary": "Dry regions of Africa, Madagascar, and Australia.",
"continents": ["Africa", "Asia", "Australia"], // Assuming Madagascar is broadly Asia/Africa contextually
"coordinates": {"lat": -20.0, "lng": 45.0} // Madagascar example
},
"tags": ["water storage", "arid climate", "iconic", "fruit"]
}
]
```
DEPLOYMENT NOTES:
- **Build Command:** `npm run build` or `yarn build` using Vite.
- **Environment Variables:** Use `.env` files for variables like API keys (if applicable later) or feature flags. Vite uses `VITE_` prefix by default. Example: `VITE_MAPBOX_API_KEY=your_key_here`.
- **Performance Optimizations:**
* Code splitting with Vite for efficient loading.
* Image optimization: Use optimized image formats (WebP) and consider a lazy loading strategy for images in lists and galleries.
* Memoization: Use `React.memo` for components that re-render unnecessarily.
* Tree shaking: Ensure the build process removes unused code.
- **Hosting:** Deploy to static hosting platforms like Vercel, Netlify, or GitHub Pages for optimal performance and cost-effectiveness.
- **PWA Considerations:** Configure Vite PWA plugin for offline capabilities and add-to-homescreen functionality for a better mobile-like experience.