# WikiBubbles

> A comprehensive platform for discovering and sharing snorkeling, diving, and freediving spots worldwide

## Project Overview

WikiBubbles is a community-driven platform that helps underwater enthusiasts discover the best dive sites around the world. The platform features an interactive map with thousands of dive sites, detailed site information, user reviews, dive logging capabilities, and real-time water conditions.

**Website**: https://wikibubbles.com
**Mission**: To unlock the wonder of the underwater world, making 75% of our planet easy and accessible for everyone to explore.

## Tech Stack

### Frontend
- **Framework**: SvelteKit (Svelte 5) with TypeScript
- **Styling**: Tailwind CSS with PostCSS
- **Rich Text**: TipTap editor (for descriptions and reviews)
- **Maps**: Mapbox GL and Leaflet
- **Search**: Algolia (InstantSearch.js)
- **Charts**: Chart.js
- **Image Handling**: browser-image-compression, heic2any

### Backend & Services
- **Database**: Firebase Firestore
- **Authentication**: Firebase Auth (Google, Apple sign-in)
- **Storage**: Firebase Storage (for photos)
- **Functions**: Firebase Cloud Functions (in `firebase_functions/`)
- **API**: SvelteKit server endpoints (`/src/routes/api/`)

### Deployment & Infrastructure
- **Hosting**: Netlify
- **Adapter**: @sveltejs/adapter-netlify
- **Build Tool**: Vite
- **SSR**: Server-side rendering with SvelteKit

### External APIs
- **Weather**: OpenMeteo API
- **Geolocation**: Geofire-common for geospatial queries

## Project Structure

```
WikiBubblesWeb2/
├── src/
│   ├── routes/              # SvelteKit routes and pages
│   │   ├── map/            # Interactive map view
│   │   ├── sites/          # Individual dive site pages
│   │   ├── dive-destinations/  # Dive destination pages
│   │   ├── profile/        # User profiles and dive logs
│   │   ├── auth/           # Authentication pages
│   │   ├── api/            # API endpoints
│   │   └── admin/          # Admin dashboard
│   ├── components/         # Reusable Svelte components
│   ├── lib/
│   │   ├── firebase/       # Firebase client initialization
│   │   ├── server/         # Server-side services
│   │   ├── services/       # Client-side services
│   │   ├── stores/         # Svelte stores (state management)
│   │   ├── types/          # TypeScript type definitions
│   │   └── utils/          # Utility functions
│   ├── app.html            # HTML template
│   └── app.css             # Global styles
├── firebase_functions/     # Firebase Cloud Functions
├── static/                 # Static assets (images, icons)
├── build/                  # Production build output
└── Configuration files
```

## Key Features

### 1. Interactive Map (`/map`)
- Browse thousands of dive sites on an interactive Mapbox map
- Filter by activity type (scuba, freediving, snorkeling, swimming)
- Search using Algolia
- Add new dive sites (authenticated users)
- View dive site details in panels/cards

### 2. Dive Sites (`/sites`)
- Detailed pages for each dive site
- User reviews and ratings
- Photo galleries
- Weather conditions (current and historical)
- GPS coordinates and entry/exit directions
- Nearby dive sites
- Breadcrumb navigation with destination paths

### 3. Dive Destinations (`/dive-destinations`)
- Hierarchical destination pages (country → region → area)
- List of dive sites in each destination
- Destination descriptions and summaries
- Interactive maps showing sites
- FAQ sections

### 4. User Profiles (`/profile`)
- Dive logs with statistics
- Favorite dive sites
- User reviews
- Contributed dive sites
- "Have been" / "Want to go" lists

### 5. Authentication (`/auth`)
- Firebase Auth integration
- Google and Apple sign-in
- Email/password authentication
- Password reset functionality

### 6. Community Features
- User-generated content (reviews, photos, dive logs)
- Rating system (visibility, wildlife, accessibility, etc.)
- Collaborative dive site information

## Data Models

### DiveSite
```typescript
interface DiveSite {
  id: string;
  name: string;
  country: string;
  coordinates: { lat: number; lng: number };
  activities: string[]; // 'scuba', 'freediving', 'snorkeling', 'swimming'
  description: string;
  depth?: { min?: number; max?: number };
  ratings?: {
    overall?: number;
    visibility?: number;
    wildlife?: number;
    accessibility?: number;
  };
  photos?: Photo[];
  // ... more fields
}
```

### DiveDestination
```typescript
interface DiveDestination {
  id: string;
  name: string;
  path: string[]; // Hierarchical path
  country: string;
  description: string;
  diveSites: string[]; // Array of site IDs
  // ... more fields
}
```

### User Profile
- Authentication via Firebase Auth
- User-generated content stored in Firestore
- Profile data includes dive logs, reviews, favorites

## API Endpoints

Located in `src/routes/api/`:
- `/api/divesites/bounds` - Get dive sites within map bounds
- `/api/divesites/details` - Get detailed dive site information
- `/api/divesites/photos` - Handle photo uploads
- `/api/sites/[id]/weather` - Get weather data for a site
- `/api/sites/[id]/current-weather` - Get current weather
- `/api/dive-destinations/load-more` - Pagination for destinations
- `/api/auth/session` - User session management
- `/api/auth/logout` - User logout

## State Management

### Svelte Stores (`src/lib/stores/`)
- `userStore.ts` - User authentication state
- `mapStateStore.ts` - Map view state (bounds, zoom)
- `filterStore.ts` - Filter preferences (activities, etc.)
- `locationStore.ts` - User location
- `uiStore.ts` - UI state (modals, panels)
- `newDiveSiteStore.ts` - New dive site form state
- `placementModeStore.ts` - Map placement mode

## Development

### Setup
```bash
npm install
npm run dev
```

### Building
```bash
npm run build
npm run preview
```

### Type Checking
```bash
npm run check
npm run check:watch
```

## Firebase Configuration

### Firestore Collections
- `diveSites` - All dive sites
- `diveDestinations` - Hierarchical destinations
- `users` - User profiles
- `reviews` - User reviews
- `diveLogs` - User dive logs
- `photos` - Photo metadata

### Security Rules
- Defined in `firestore.rules` and `storage.rules`
- Authenticated users can contribute content
- Public read access for most data

### Cloud Functions (`firebase_functions/src/`)
- Handle backend logic
- Process user submissions
- Send notifications
- Data validation and processing

## SEO & Metadata

- Server-side rendering for SEO
- Dynamic meta tags and Open Graph data
- Structured data (JSON-LD) for organizations and locations
- Sitemap generation (`/sitemap.xml`)
- Canonical URLs
- Image optimization (WebP, AVIF formats)

## Mobile App Integration

- iOS and Android apps available
- App download banners on web
- Deep linking support (`apple-app-site-association`)
- Responsive design for mobile web

## Styling Conventions

- Tailwind CSS utility classes
- Component-scoped styles in `.svelte` files
- Global styles in `src/app.css`
- Responsive design with mobile-first approach
- Custom color schemes for underwater theme

## Key Dependencies

**Core:**
- `svelte@^5.43.2` - UI framework
- `@sveltejs/kit@^2.5.27` - Application framework
- `firebase@^11.4.0` - Firebase SDK
- `typescript@^5.8.3` - Type safety

**UI/UX:**
- `tailwindcss@^3.4.17` - Styling
- `lucide-svelte@^0.511.0` - Icons
- `svelte-sonner@^1.0.5` - Toast notifications

**Maps:**
- `mapbox-gl@^3.10.0` - Interactive maps
- `leaflet@^1.9.4` - Map library
- `geofire-common@^6.0.0` - Geospatial queries

**Content:**
- `@tiptap/core@^3.4.4` - Rich text editor
- `marked@^16.2.0` - Markdown parsing

## Common Tasks

### Adding a New Page
1. Create route in `src/routes/[page-name]/`
2. Add `+page.svelte` for UI
3. Add `+page.server.ts` for server-side logic (optional)
4. Add `+layout.svelte` for shared layout (optional)

### Adding a New API Endpoint
1. Create `+server.ts` in `src/routes/api/[endpoint]/`
2. Export `GET`, `POST`, etc. handlers
3. Use Firebase Admin SDK for server-side operations

### Working with Firestore
- Client-side: Use services in `src/lib/services/client/`
- Server-side: Use services in `src/lib/server/services/`
- Types: Define in `src/lib/types/`

### Adding Components
- Global components: `src/components/`
- Route-specific components: `src/routes/[route]/components/`
- Reusable logic components: `src/lib/components/`

## Environment Variables

Firebase configuration is currently hardcoded in `src/lib/firebase/client.ts` but should be moved to environment variables for production.

## Testing

Currently no automated testing framework configured. Manual testing in development and staging environments.

## Contributing Guidelines

1. Follow TypeScript best practices
2. Use Svelte 5 runes (`$props`, `$state`, `$derived`)
3. Maintain responsive design
4. Add proper TypeScript types
5. Follow existing code structure and naming conventions

## Performance Optimization

- Lazy loading of components and images
- Code splitting with SvelteKit
- Image optimization (WebP, AVIF)
- Server-side rendering for initial load
- Preloading critical assets

## Browser Support

- Modern browsers (Chrome, Firefox, Safari, Edge)
- Mobile browsers (iOS Safari, Chrome Android)
- Progressive Web App capabilities

## Known Issues & Limitations

- Firebase config should be in environment variables
- No automated testing setup
- Some components need refactoring for better reusability

---

*Last Updated: November 2, 2025*