Technigo Final Project: BADA - Real-time beach water quality web app with maps & favorites

.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  backend:
+    name: Backend (typecheck + tests)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: backend/package-lock.json
+
+      - name: Install
+        run: npm ci
+        working-directory: backend
+
+      - name: Typecheck
+        run: npx tsc --noEmit
+        working-directory: backend
+
+      - name: Test
+        run: npm test
+        working-directory: backend
+
+  frontend:
+    name: Frontend (typecheck + build)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install
+        run: npm ci
+        working-directory: frontend
+
+      - name: Typecheck
+        run: npx tsc --noEmit
+        working-directory: frontend
+
+      - name: Build
+        run: npx vite build
+        working-directory: frontend

.github/workflows/refresh-beaches.yml

@@ -0,0 +1,38 @@
+name: Refresh beaches snapshot
+
+# The beach list changes only a few times a year, so a daily refresh of the
+# static snapshot (frontend/public/beaches.json) is plenty. Runs on a schedule
+# and on demand; commits only when the data or sitemap actually changed.
+
+on:
+  schedule:
+    - cron: "0 4 * * *" # daily at 04:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24
+
+      - name: Build snapshot
+        run: node scripts/build-beaches.mjs
+
+      - name: Commit if changed
+        run: |
+          if [[ -n "$(git status --porcelain frontend/public/beaches.json frontend/public/sitemap.xml)" ]]; then
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git add frontend/public/beaches.json frontend/public/sitemap.xml
+            git commit -m "chore: refresh beaches snapshot and sitemap"
+            git push
+          else
+            echo "Snapshot and sitemap unchanged — nothing to commit."
+          fi

.gitignore

@@ -7,9 +7,18 @@ node_modules
 .env.production.local
 
 build
+dist
 
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 
-package-lock.json
+package-lock.json
+!frontend/package-lock.json
+!backend/package-lock.json
+
+CLAUDE.md
+.claude/
+.skills/
+# Local Netlify folder
+.netlify

README.md

@@ -1,13 +1,241 @@
-# Final Project
+# 🏖️ Badlistan – Koll på badvattnet i hela Sverige
 
-Replace this readme with your own information about your project.
+![React](https://img.shields.io/badge/Frontend-React_18-61DAFB?logo=react&logoColor=white)
+![Express](https://img.shields.io/badge/Backend-Express_5-000000?logo=express&logoColor=white)
+![MongoDB](https://img.shields.io/badge/Database-MongoDB-47A248?logo=mongodb&logoColor=white)
+![TypeScript](https://img.shields.io/badge/Code-TypeScript-3178C6?logo=typescript&logoColor=white)
+![TailwindCSS](https://img.shields.io/badge/UI-Tailwind_CSS_v4-38B2AC?logo=tailwind-css&logoColor=white)
+![Three.js](https://img.shields.io/badge/3D-Three.js-000000?logo=three.js&logoColor=white)
+![MapLibre](https://img.shields.io/badge/Maps-MapLibre-4264FB?logo=openstreetmap&logoColor=white)
+![i18next](https://img.shields.io/badge/Translations-i18next-26A69A?logo=i18next&logoColor=white)
+![TanStack Query](https://img.shields.io/badge/State-TanStack_Query-FF4154?logo=reactquery&logoColor=white)
+![Deployed](https://img.shields.io/badge/Deployed-Netlify-00C7B7?logo=netlify&logoColor=white)
 
-Start by briefly describing the assignment in a sentence or two. Keep it short and to the point.
+**Badlistan** helps beachgoers and families in Sweden find safe, EU-classified bathing waters with real-time quality updates.  
+It replaces outdated or clunky websites with a **clean, mobile-friendly experience** where you can browse nearby beaches on a map, check water quality, and save your favourites.
 
-## The problem
+[Try it out here](https://badaweb.netlify.app/) (deployed on Netlify)
 
-Describe how you approached to problem, and what tools and techniques you used to solve it. How did you plan? What technologies did you use? If you had more time, what would be next?
+---
 
-## View it live
+## ✨ Features
 
-Every project should be deployed somewhere. Be sure to include the link to the deployed project so that the viewer can click around and see what it's all about.
+- 🗺 **Map of all EU-classified beaches in Sweden** (MapLibre + OpenStreetMap)
+- 📍 **Find the nearest beach** using your device's location
+- 🔬 **View water quality, classification, and recent test results** (data from HaV)
+- 🔍 **Real-time beach search** with autocomplete dropdown
+- ❤️ **Create an account and save favourite beaches** to your profile
+- 🔀 **Custom sorting for favorites** with pointer and keyboard controls
+- 🌊 **3D animated backgrounds** (WebGL water simulation in dark mode, sand texture in light mode)
+- 🎨 **Glassmorphism UI** with backdrop blur effects
+- 🌤️ **Weather & sun times panel** on each beach — air temp, feels like, UV index, water temperature, and a visual sun arc with golden hour, sunrise/sunset, and twilight phases
+- 🌗 **Dark mode** and responsive design (mobile → desktop)
+- 🌐 **Multi-language support** (Swedish / English)
+- 📚 **API Documentation** (Swagger UI at `/api/docs`)
+
+---
+
+## 🚀 Tech Stack
+
+**Frontend**
+
+- React 18 + Vite + TypeScript
+- React Router v7
+- Zustand (global state)
+- TanStack Query (server state & caching)
+- Tailwind CSS v4 (with CSS-based theme system)
+- i18next (translations)
+- MapLibre GL (maps)
+- Three.js ecosystem (@react-three/fiber, @react-three/drei) for 3D backgrounds
+- @dnd-kit (drag-and-drop)
+- react-hook-form + Zod (form validation)
+- react-hot-toast (notifications)
+
+**Custom React Hooks**
+
+- `useGeolocation` – Device location access
+- `useOutsideClose` – Close popovers on outside click/Escape key
+- `useToggleDarkMode` – Writes the `.dark` class (used in Header)
+- `useDarkModeObserver` – Reads/observes `.dark` class via MutationObserver (used in AmbientBackground)
+- `usePrefersReducedMotion` – Respect user's motion preferences
+- `useBeaches` – Beach data fetching
+- `useWeather` – Weather data with 30-min stale time
+- `useSunTimes` – Sun times keyed by date with 12-hr stale time
+
+**Backend**
+
+- Node.js + Express 5
+- MongoDB + Mongoose
+- Cookie-based JWT sessions
+- Zod (validation)
+- In-memory caching for HaV API responses
+- Swagger UI (API documentation)
+
+**External APIs**
+
+- [HaV Bathing Waters API](https://badplatsen.havochvatten.se/) (official Swedish Agency for Marine and Water Management)
+- [MapTiler](https://www.maptiler.com/) (map styles)
+- [Open-Meteo](https://open-meteo.com/) (weather forecast + marine/water temperature)
+- [sunrise-sunset.org](https://sunrise-sunset.org/api) (sunrise, sunset, golden hour, and twilight times)
+
+---
+
+## ♿ Accessibility
+
+Badlistan is built with accessibility in mind:
+
+- **Skip navigation link** – Jump directly to main content
+- **ARIA labels** – Proper labeling of interactive elements
+- **ARIA live regions** – Screen reader announcements for dynamic content
+- **ARIA busy states** – Loading indicators for assistive technology
+- **Keyboard navigation** – Search is an ARIA combobox (arrow keys / Enter / Escape); menus, dialogs, and favorite reordering are keyboard-operable with focus management
+- **Escape key handling** – Close menus and return focus to trigger
+- **Focus visible rings** – Clear focus indicators
+- **Reduced motion support** – Respects `prefers-reduced-motion` (both CSS and JS)
+- **Semantic HTML** – Proper document structure with roles
+- **Dynamic lang attribute** – HTML lang updates with language selection
+- **Accessible notifications** – Toast messages with proper ARIA live regions
+
+---
+
+## 📸 Screenshots
+
+_(Coming soon)_
+
+---
+
+## 🛠 Installation & Setup
+
+Clone the repo and install dependencies:
+
+```bash
+git clone https://github.com/govargas/bada.git
+cd bada
+```
+
+**Backend**
+
+```bash
+cd backend
+cp .env.example .env.local # then fill in your values
+npm install
+npm run dev
+```
+
+Backend runs on http://localhost:3000
+
+API Documentation available at http://localhost:3000/api/docs
+
+Raw OpenAPI JSON is available at http://localhost:3000/api/docs/openapi.json
+
+**Frontend**
+
+```bash
+cd frontend
+cp .env.example .env.local # then fill in your values
+npm install
+npm run dev
+```
+
+Frontend runs on http://localhost:5173
+
+---
+
+## 🔑 Environment Variables
+
+- See .env.example in both backend/ and frontend/.
+- Fill in with your own values (MongoDB Atlas, JWT secret, MapTiler key).
+
+---
+
+## 🌍 Deployment
+
+- Frontend: Deployed on Netlify: https://badaweb.netlify.app/
+- Backend: Deployed on Vercel → https://bada-backend.vercel.app/api/health
+
+---
+
+## ✅ Requirements Checklist
+
+### Technical Requirements (Grade G)
+
+- ✅ React frontend
+- ✅ Node.js + Express backend
+- ✅ MongoDB database
+- ✅ Authentication (httpOnly cookie session with JWT)
+- ✅ React Router navigation
+- ✅ Global state management (Zustand)
+- ✅ ≥2 external libraries (TanStack Query, MapLibre, Three.js, react-hook-form, i18next, react-hot-toast, @dnd-kit)
+- ✅ Custom React hooks (useGeolocation, useOutsideClose, useToggleDarkMode, useDarkModeObserver, usePrefersReducedMotion, useBeaches, useWeather, useSunTimes)
+- ✅ Responsive (320px → 1600px+)
+- ✅ Accessibility features (comprehensive a11y implementation)
+- ✅ Clean Code practices
+
+### Visual Requirements
+
+- ✅ Clear structure using box model with consistent margins/paddings
+- ✅ Consistent typography across views and breakpoints
+- ✅ Cohesive color scheme with CSS design tokens
+- ✅ Mobile-first responsive design
+- ✅ Dark mode support with 3D backgrounds
+- ✅ Multi-language support (Swedish/English)
+- ✅ Glassmorphism UI design system
+
+### Grade VG Enhancements
+
+- ✅ Error Boundaries
+- ✅ Toast notifications with a11y
+- ✅ Reduced motion support
+- ✅ Comprehensive documentation
+- ✅ Meta tags for SEO (Open Graph, Twitter Cards)
+- ✅ API Documentation (Swagger UI)
+- ✅ Performance optimizations (lazy-loaded 3D backgrounds)
+
+---
+
+## ⚠️ Known Limitations
+
+These are conscious trade-offs for an MVP, documented rather than hidden:
+
+- **Backend cache is per-instance.** The HaV proxy cache is an in-memory `Map`. On Vercel serverless it does not survive cold starts or span instances, so it mainly de-dupes bursts within a warm instance. The beach _list_ sidesteps this entirely via a static CDN snapshot (`frontend/public/beaches.json`, refreshed daily by a GitHub Action); only per-beach detail still hits the proxy.
+- **Data is seasonal.** HaV samples bathing waters roughly June–August. Outside the season `latestSampleDate` and classification reflect the previous year.
+- **Golden hour is approximate.** It is computed as sunrise + 1h / sunset − 1h, and the sun arc degrades north of the Arctic Circle during the midnight sun (sunrise-sunset.org returns degenerate times there).
+- **Third-party APIs called from the client.** Open-Meteo and sunrise-sunset.org are called directly from the browser with no SLA — acceptable for an MVP, not for production traffic.
+- **Session cookie auth.** Login sets an httpOnly `bada_session` cookie through the Netlify `/api/*` proxy so the session stays first-party and unavailable to JavaScript.
+- **No SSR.** SEO is limited to per-route `<title>`, a generated `sitemap.xml`, and site-wide Open Graph tags. Per-beach Open Graph previews would require prerendering.
+
+---
+
+## 🧭 Roadmap
+
+### Completed
+
+- ✅ 3D animated backgrounds (WebGL water/sand)
+- ✅ Enhanced glassmorphism UI
+- ✅ Header search with autocomplete
+- ✅ Comprehensive accessibility implementation
+- ✅ API documentation with Swagger
+- ✅ Performance optimization (deferred 3D loading)
+- ✅ Focus management and keyboard navigation
+- ✅ Weather & sun times panel (Open-Meteo + sunrise-sunset.org) with visual sun arc, golden hour zones, and water temperature
+
+### Planned
+
+- 🔄 Filter beaches by classification
+- 🔄 Add user beach photos
+- 🔄 Allow notes/tips per beach (e.g. "good for kids")
+- 🔄 PWA support with offline capability
+
+---
+
+## 💡 Inspiration & Credits
+
+- Data from the Swedish Agency for Marine and Water Management (HaV)
+- Maps powered by OpenStreetMap + MapTiler
+- Built during the Technigo Fullstack JavaScript Bootcamp (2025)
+
+---
+
+## 👨‍💻 Author
+
+Created by Talo Vargas, 2025