# StayFree - Camping & Vanlife Discovery Platform

## ABOUT

**Site Name:** StayFree
**URL:** https://www.stayfree.app
**Purpose:** Comprehensive platform for discovering camping, vanlife, and outdoor accommodation options across Europe and beyond

**Description:**
StayFree is a community-driven platform that helps travelers discover authentic camping and outdoor accommodation experiences. Whether you're looking for free camper parking, wild camping spots, unique microcamping hosts, RV parks, traditional campsites, or agritourism locations, StayFree provides curated information to help you plan your next adventure.

**Vision:**
To empower travelers with comprehensive, accurate, and accessible information about camping and vanlife locations, enabling authentic outdoor experiences and supporting sustainable tourism across Europe.

**Target Audience:**
- Vanlife enthusiasts and campervan travelers
- Budget-conscious outdoor adventurers
- Nature lovers seeking authentic camping experiences
- Families planning camping trips
- Digital nomads using vehicles for accommodation
- Environmental and sustainable tourism advocates

## UNIQUE VALUE PROPOSITION

1. **Comprehensive Coverage:** Aggregates multiple accommodation types (6 distinct camping/parking categories) across 8 European countries with regional granularity
2. **Multi-Language Support:** Fully localized in English and German to serve diverse European audiences
3. **Community-Focused:** Combines official data with community insights and experiences
4. **Free & Accessible:** Democratizes access to camping information without paywalls
5. **User-Friendly Discovery:** Intuitive navigation combining country, region, and spot-type filters
6. **Rich Content:** Integrated blog, guides, travel tracking features, and interactive mapping
7. **Sustainable Focus:** Promotes responsible tourism and environmental consciousness

## MAIN FEATURES & CAPABILITIES

### Core Features
- **Spot Discovery:** Browse 400+ camping and parking locations across Europe
- **Advanced Filtering:** Filter by country, region, spot type, and facilities
- **Interactive Map:** Visualize camping spots geographically
- **Multi-Language Content:** Complete English and German translations
- **Responsive Design:** Full mobile and desktop support
- **Accessibility:** WCAG-compliant with semantic HTML and proper ARIA labels

### Content Features
- **Travel Blog:** Curated articles about vanlife, camping destinations, and travel tips
- **Regional Guides:** Detailed guides for specific regions (Wildcamping in Germany, France, Austria, etc.)
- **FAQ Section:** Comprehensive answers to common camping and vanlife questions
- **Travel Tracker:** Feature to track and document your camping adventures
- **Featured Categories:** Specialized collections like "Sustainable Vanlife" and destination-specific content

### Technical Features
- **API Integration:** Real-time spot data from upstream API (api.stayfree.app)
- **Structured Search:** Parameter-based querying with validation
- **Caching:** Intelligent response caching for performance
- **Rate Limiting:** Crawler-friendly rate limits with sitemap exclusion
- **SEO Optimization:** Complete SEO metadata, structured data, Open Graph images
- **Error Handling:** Comprehensive error handling with user-friendly messages

## SPOT TYPES & CATEGORIES

### 6 Primary Spot Types

1. **Camper Parking Areas** (camper-parking / camper-stellplaetze)
   - Free or low-cost overnight parking for campervans
   - Safe, convenient stopover locations
   - Ideal for budget travelers
   - API Value: PARKING_FREE

2. **Wildcamping** (wildcamping / freistehen)
   - Wild camping in nature (forests, meadows, mountains)
   - Remote, natural locations
   - Freedom and authentic outdoor experiences
   - API Value: WILD_SPOT

3. **Microcamping** (microcamping / mikrocamping)
   - Unique stays with local hosts (vineyards, farms, gardens)
   - Connection with local communities
   - Intimate, authentic experiences
   - API Values: CAMPSPACE, VANLIFE_LOCATION, CAMPING_PRIVATE

4. **RV Parks** (rv-park / stellplaetze)
   - Professional motorhome facilities
   - Amenities (electricity, water, waste disposal)
   - Convenient and comfortable camping
   - API Value: PARKING_CAMPER

5. **Campsites** (campsite / campingplaetze)
   - Traditional camping facilities
   - Full amenities and recreational options
   - Family-friendly infrastructure
   - API Values: CAMPING, CAMPING_ACS

6. **Agritourism** (agritourism / agrotourismus)
   - Farm-based accommodation and experiences
   - Rural and agricultural settings
   - Educational and cultural experiences
   - API Value: AGROTOURISM

## SUPPORTED REGIONS

### Countries Covered (8 Total)
- **Germany** (DE) - deutschland / germany
- **France** (FR) - frankreich / france
- **Great Britain** (GB) - vereinigtes-koenigreich / united-kingdom
- **Spain** (ES) - spanien / spain
- **Italy** (IT) - italien / italy
- **Norway** (NO) - norwegen / norway
- **Portugal** (PT) - portugal / portugal
- **Sweden** (SE) - schweden / sweden

### Regional Structure
Each country contains multiple regions (40+ total regions across all countries), enabling fine-grained location discovery. Users can browse by:
- Country level (8 countries)
- Region level (40+ regions across countries)
- Spot type level (6 types)
- Combination of country + spot type
- Combination of region + spot type

## LANGUAGES & LOCALIZATION

### Supported Languages
1. **English** (en)
   - Default/fallback language
   - Code: "en"

2. **German** (de)
   - Full German translation
   - Code: "de"

### Language Features
- URL routing with language segments (/en/, /de/)
- Language detection and persistence (localStorage: stayfree:language)
- Language-specific content and translations
- Translated UI elements, pages, and spot descriptions
- Language switching via LanguageSwitcher component
- Bilingual blog and guide content

## URL STRUCTURE & ROUTING

### Main Page Routes

**Home & Navigation**
- `/en` or `/en/` → English home page
- `/de` or `/de/` → German home page
- `/` → Redirects to `/en`
- `/blog` → Redirects to `/en/blog`

**Camping & Spot Discovery**
- `/en/campspots` → All camping categories (countries, types, regions)
- `/de/campspots` → German version
- `/en/campspots/{spot-type}` → Browse by spot type (e.g., /en/campspots/camper-parking)
- `/de/campspots/{region-de}` → Browse by region in German
- `/en/campspots/{country}/` → Browse country spots
- `/en/campspots/{country}/{region}` → Browse region within country
- `/en/campspots/camping-spots/{spot-id}` → Individual spot detail page

**Specialized Camping Categories**
- `/en/campspots/microcamping-spots` → Microcamping specialty page
- `/en/campsites` → Traditional campsites

**Blog & Content**
- `/en/blog` or `/en/magazine` → Blog index
- `/en/blog/{blog-slug}` → Individual blog post
- `/en/blog/vanlife-in-greece-lefkada-roaming-the-greek-island-paradise` → Example blog post

**Guides & Resources**
- `/en/guides` → Guides overview
- `/en/guides/wildcamping` → Wildcamping guide index
- `/en/guides/wildcamping/germany` → Country-specific wildcamping guide
- `/en/guides/wildcamping/austria` → Austrian wildcamping guide
- `/en/guides/wildcamping/france` → French wildcamping guide

**Tools & Features**
- `/en/map` → Interactive camping map
- `/en/features/travel-tracker` → Travel tracker tool
- `/en/categories` → Category browser (redirects to /campspots)

**Information**
- `/en/faq` → Frequently asked questions
- `/en/imprint` → Legal imprint (Impressum)
- `/en/privacy-policy` → Privacy policy (Datenschutzerklärung)

### Route Pattern Conventions
- Language prefix: `/{lang}` where lang = "en" or "de"
- Path segments use hyphens (kebab-case): `/camping-spots`, `/forest-spots`
- URL slugs are language-specific: `/freistehen` (de) vs `/wildcamping` (en)
- Slugs are derived from human-readable names (transliterated for special characters)

## API ENDPOINTS

### REST API Base
- **Base URL:** `https://www.stayfree.app/api`
- **Upstream Data API:** `https://api.stayfree.app/v1/public/spots`

### Endpoint Specifications

#### GET /api/spots - List Camping Spots
**Purpose:** Retrieve list of camping/parking spots with filters

**Query Parameters:**
- `spotType` (optional, string[]): Filter by spot type(s)
  - Values: PARKING_FREE, WILD_SPOT, CAMPSPACE, VANLIFE_LOCATION, CAMPING_PRIVATE, PARKING_CAMPER, CAMPING, CAMPING_ACS, AGROTOURISM
  - Example: `?spotType=PARKING_FREE,WILD_SPOT`
  
- `maxResults` (optional, number): Limit number of results (default: 20, max: varies)
  
- `locale` (optional, string): Language/locale for response
  - Values: "en", "de"
  
- `locationCountry` (optional, string): Filter by ISO country code
  - Values: "DE", "FR", "GB", "ES", "IT", "NO", "PT", "SE"
  
- `locationAdminArea` (optional, string): Filter by region/admin area
  - Must be used with locationCountry
  
- `sort` (optional, string): Sort results
  - Values: distance, rating, name, etc.

**Response Format:**

{
  "items": [
    {
      "_id": "string",
      "name": "string",
      "description": "string",
      "features": { "key": boolean },
      "photos": [{ "url": "string" }],
      "ratingScore": number,
      "ratingCount": number,
      "bookable": boolean
    }
  ]
}
```

**Example Calls:**
- `/api/spots?spotType=WILD_SPOT&locationCountry=DE&maxResults=50`
- `/api/spots?spotType=PARKING_CAMPER&locale=de`
- `/api/spots?maxResults=20&sort=rating`

#### GET /api/spots/{id} - Get Spot Details
**Purpose:** Retrieve detailed information about a specific camping spot

**Path Parameters:**
- `id` (required, string): Unique spot identifier

**Query Parameters:**
- `locale` (optional, string): Language for response ("en" or "de")

**Response Format:**
```json
{
  "_id": "string",
  "name": "string",
  "description": "string",
  "features": {
    "electricity": boolean,
    "freshWater": boolean,
    "wasteDisposal": boolean,
    "wifi": boolean,
    "showers": boolean,
    "toilets": boolean,
    "shop": boolean,
    "restaurant": boolean,
    "playground": boolean,
    "pets": boolean
  },
  "photos": [
    { "url": "string" },
    { "url": "string" }
  ],
  "reviews": [
    {
      "title": "string",
      "body": "string",
      "author": "string",
      "rating": number
    }
  ],
  "ratingScore": number,
  "ratingCount": number,
  "bookable": boolean,
  "location": {
    "lat": number,
    "lng": number,
    "address": "string",
    "city": "string",
    "country": "string",
    "region": "string"
  }
}
```

**Example Calls:**
- `/api/spots/ABC123?locale=en`
- `/api/spots/DE-BERLIN-001?locale=de`

#### GET /api/ping - Health Check
**Purpose:** Verify API server is running

**Response Format:**
```json
{
  "message": "Pong from Express server"
}
```

#### GET /api/demo - Demo Endpoint
**Purpose:** Simple demo API endpoint

**Response Format:**
```json
{
  "message": "Hello from Express server"
}
```

#### GET /sitemap.xml - Sitemap
**Purpose:** XML sitemap for search engine crawling
**Content-Type:** application/xml
**Cache:** 1 hour (3600 seconds)
**Coverage:** 400+ URLs across all languages and regions

#### GET /robots.txt - Robots Protocol
**Purpose:** Crawling instructions for search engines
**Content:** 
- Disallows: /private/
- Sitemap: https://www.stayfree.app/sitemap.xml

### Rate Limiting
- **General API Routes:** 100 requests per 15 minutes per IP
- **Sitemap:** Excluded from rate limiting (crawler-friendly)
- **Error Handling:** 429 status when rate limit exceeded

### Error Responses
All errors follow consistent format:
```json
{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "correlationId": "unique-trace-id",
  "details": { "field": "specific error details" }
}
```

**Common Error Codes:**
- VALIDATION_ERROR (400) - Invalid parameters
- NOT_FOUND_ERROR (404) - Resource not found
- RATE_LIMIT_ERROR (429) - Too many requests
- SERVICE_UNAVAILABLE_ERROR (503) - Upstream service down

## DATA MODEL & CONTENT TYPES

### Spot Entity
**Definition:** A camping or parking location

**Properties:**
- `_id` (string): Unique identifier
- `name` (string): Location name
- `description` (string): Location description
- `features` (object): Amenities and facilities (boolean flags)
- `photos` (array): Photo URLs and metadata
- `reviews` (array): User reviews and ratings
- `ratingScore` (number): Average rating (1-5)
- `ratingCount` (number): Number of ratings
- `bookable` (boolean): Can be booked online
- `location` (object): Coordinates and address
- `spotType` (string): Category (PARKING_FREE, WILD_SPOT, etc.)

### Blog Post Entity
**Definition:** Editorial content about camping and vanlife

**Properties:**
- `slug` (string): URL-safe identifier
- `title` (string): Post headline
- `summary` (string): Brief description
- `image` (string): Thumbnail image URL
- `heroImage` (string): Large header image
- `dateLabel` (string): Human-readable date
- `isoDate` (string): ISO 8601 date format
- `sections` (array): Content sections with heading and body
- `tags` (array): Content categorization tags
- `language` (string): "en" or "de"

### Guide Entity
**Definition:** Educational content about camping destinations

**Properties:**
- `slug` (string): URL identifier
- `title` (string): Guide title
- `description` (string): Guide overview
- `country` (string): Target country
- `region` (optional, string): Specific region
- `sections` (array): Guide sections with content
- `language` (string): "en" or "de"

### Regional Category Entity
**Definition:** Curated collection of camping spots by region

**Properties:**
- `slug` (string): URL identifier
- `name` (string): Category name
- `description` (string): Category description
- `countryCode` (string): Country code
- `regionName` (string): Region name
- `spotTypes` (array): Associated spot types
- `spotCount` (number): Number of spots in region

## CONTENT ORGANIZATION

### Content Hierarchy

**Level 1: Global Discovery**
- All spot types across all countries
- Blog index with all articles
- Guide index with all resources

**Level 2: Country-Level Discovery**
- All regions within a country
- All spot types within a country
- Country-specific guides
- Country statistics and overviews

**Level 3: Regional Discovery**
- All spot types within a region
- Region-specific information
- Regional guides and tips

**Level 4: Spot-Type Discovery**
- All spots of a type across countries
- Type-specific guides and features

**Level 5: Individual Resources**
- Specific spot details with reviews
- Individual blog post with full content
- Detailed guides and tutorials

### Content Categories

**Spot Type Content:**
- Description of spot type
- Features and amenities
- Best practices and tips
- Example locations
- Filtering and search capabilities

**Regional Content:**
- Region highlights
- Popular camping areas
- Local regulations and permits
- Seasonal information
- Travel tips

**Destination Content:**
- Country overviews
- Regional guides (Wildcamping in Germany, France, etc.)
- Travel guides and itineraries
- Local culture and attractions
- Practical travel information

**Educational Content:**
- Blog posts (vanlife tips, destination reviews, travel stories)
- FAQs (camping questions, regulations, equipment)
- Guides (wildcamping, sustainable travel, family camping)
- Features (travel tracker, interactive tools)

## CONTRIBUTION GUIDELINES

### Community Contributions

**Types of Contributions Welcome:**
1. **Spot Information:** New camping locations or updates to existing listings
2. **Blog Content:** Travel experiences and destination reviews
3. **Local Insights:** Regional camping tips and local knowledge
4. **Translations:** Help improve localization

**Submission Process:**
- Submit via contact form or email
- Include detailed information and photos
- Verify accuracy and relevance
- Respect community guidelines

**Community Guidelines:**
- Maintain factual accuracy
- Respect privacy and property rights
- Avoid promotional or commercial content
- Use respectful and inclusive language
- Follow environmental ethics (Leave No Trace)

### Feature Requests & Feedback
- Suggestions: Submit via feedback form or GitHub issues
- Bug Reports: Report through official channels with details
- Enhancement Ideas: Describe use case and expected behavior

## CONTACT & SUPPORT

**Website:** https://www.stayfree.app

**Support Channels:**
- Email: support@stayfree.app
- Contact Form: Available on website
- GitHub: Issues and discussions (if open source)

**Legal Pages:**
- Imprint: /en/imprint (legal information)
- Privacy Policy: /en/privacy-policy (data handling)
- Terms of Use: Available in legal section

**Social Media & Community:**
- Community Discord/Forum: Links available on site
- Twitter/Social: Follow for updates and news

## KEY PAGES & DOCUMENTATION

### User Documentation
- **Getting Started:** Homepage overview and navigation guide
- **Search Guide:** How to find camping spots by country/type/region
- **Map Tutorial:** Using interactive mapping features
- **FAQ:** Comprehensive question and answer section
- **Blog:** Educational articles and travel guides

### For Developers & AI
- **API Documentation:** `/api/*` endpoints with specifications
- **Sitemap:** `/sitemap.xml` for crawling and indexing
- **robots.txt:** `/robots.txt` for crawler directives
- **llms.txt:** This document for AI/LLM understanding
- **Open Graph Data:** Metadata for social sharing

### Important Pages
1. **Blog Index:** https://www.stayfree.app/en/blog
2. **Campspots Discovery:** https://www.stayfree.app/en/campspots
3. **Guides:** https://www.stayfree.app/en/guides
4. **FAQs:** https://www.stayfree.app/en/faq
5. **Travel Tracker:** https://www.stayfree.app/en/features/travel-tracker

## BROWSER & DEVICE SUPPORT

**Minimum Requirements:**
- Modern browser (Chrome, Firefox, Safari, Edge)
- Mobile responsive (320px and up)
- JavaScript enabled

**Accessibility:**
- WCAG 2.1 AA compliance
- Semantic HTML structure
- ARIA labels and live regions
- Keyboard navigation support
- Screen reader optimized

## SEO & DISCOVERABILITY

### Search Optimization
- Comprehensive meta tags (title, description, OG)
- Structured data (JSON-LD) for spots and content
- Optimized Open Graph images (1200x630px)
- Dynamic sitemap.xml with 400+ URLs
- robots.txt with sitemap declaration
- Canonical URLs for duplicate prevention
- Language alternates for bilingual content

### SEO Features
- Unique titles and descriptions per page
- Proper heading hierarchy (H1, H2, H3)
- Image alt text for accessibility and SEO
- Internal linking structure
- Fast page load times
- Mobile optimization
- Core Web Vitals optimization

## COMMON WORKFLOWS FOR LLMs

### Discovering Camping Spots
1. Start at `/en/campspots` for browsing interface
2. Use `/api/spots` endpoint with filters for programmatic access
3. Filter by spotType, locationCountry, or locationAdminArea
4. Get spot details via `/api/spots/{id}`
5. Parse structured data for ratings, features, and reviews

### Finding Regional Information
1. Browse `/en/campspots/{country}` for country overview
2. Explore `/en/campspots/{country}/{region}` for regional details
3. Use guides at `/en/guides/wildcamping/{country}` for expert advice
4. Check blog posts for destination experiences

### Understanding Site Structure
1. Homepage `/en` shows main categories and navigation
2. Categories page organizes by type and location
3. Individual spot pages show complete information
4. Blog and guides provide educational content
5. Map at `/en/map` shows geographic distribution

### Accessing Specific Content
1. Blog posts: `/en/blog/{slug}` (see blog index for available posts)
2. Country spots: `/en/campspots/{country-slug}`
3. Region spots: `/en/campspots/{country-slug}/{region-slug}`
4. Spot type pages: `/en/campspots/{type-slug}`
5. Guides: `/en/guides/wildcamping/{country}` or `/en/guides/{topic}`

## AI TRAINING & DATA USAGE

**Important Note:** This site uses `AI-Training: disallow` in robots.txt

Robots.txt Directive:
```
User-agent: *
Disallow: /private/

User-agent: SiteAuditBot
Allow: /

# AI training
AI-Training: disallow
```

**Meaning:** Automated AI training data collection is not permitted. Manual review for research or reference is acceptable, but systematic scraping for training datasets violates this directive.

## CHANGELOG & UPDATES

**Last Updated:** January 2026

### Recent Updates
- Implemented centralized error handling system
- Added comprehensive OG image optimization (1200x630px)
- Validated sitemap.xml generation and serving
- Enhanced API documentation and validation
- Improved correlation ID tracking for debugging
- Expanded SEO metadata across all pages

### Planned Features
- Dynamic OG image generation
- Sitemap index for scaling (40,000+ URLs)
- Advanced search filters
- User reviews and ratings
- Mobile app versions
- Community forum integration
- Booking integration with partners

## VERSION INFORMATION

**Site Version:** 1.0.0
**API Version:** v1
**Upstream API:** api.stayfree.app/v1/public/spots
**Documentation Version:** January 2024

---

## SUMMARY

StayFree is a comprehensive, multi-language camping discovery platform combining 400+ locations, curated guides, interactive tools, and community insights. With a well-structured REST API, SEO-optimized content organization, and full localization in English and German, it serves as both a user-friendly platform and a structured data source for AI understanding of European camping and vanlife resources.

For questions or clarifications about this documentation, please refer to the contact information above or visit the website directly.