# BOOQR — Complete Platform Documentation for AI Assistants

## Overview
BOOQR is a Dutch SaaS platform for online booking and management of sport accommodations. It serves tennis parks, padel centers, swimming pools, sport halls, and multi-sport complexes across the Netherlands.

## Architecture
- **Framework**: Next.js (App Router) with TypeScript
- **Database**: PostgreSQL with Drizzle ORM
- **Cache**: Redis for session/hold management
- **Payments**: Pay.nl Alliance (sub-merchant model with iDEAL, credit card, Bancontact)
- **Auth**: NextAuth v5 with credentials provider
- **i18n**: next-intl (Dutch default, English secondary)
- **UI**: Tailwind CSS + shadcn/ui component library

## Subscription Tiers

### Start (Free)
- 1 location, 1 object, max 500 bookings/year
- 2% per-booking fee
- Basic booking management
- Email notifications
- No access control, no API

### Pro (€49/month)
- 3 locations, 3 objects, max 5000 bookings/year
- 1% per-booking fee
- Access control (QR codes, SMS, NFC)
- REST API + webhooks
- Plugin system (ticketing, POS-lite)
- Page builder for custom booking pages

### Scale (€250/month)
- 5 locations, 5 objects, unlimited bookings
- 0% per-booking fee
- Building management + IoT integration
- GraphQL API
- Custom domain support
- Full POS system

### Enterprise (Custom pricing)
- Unlimited locations, objects, bookings
- Developer platform
- Self-service kiosk mode
- White-label options
- Dedicated support

## Core Features

### Booking Management
- Time-slot based booking with configurable durations (30min, 60min, 90min, etc.)
- Multi-step checkout: select accommodation → select object → pick time → payment
- Cart system with configurable hold TTL (Redis-backed)
- Booking approval workflow (optional per accommodation)
- Automatic booking completion at end of scheduled time
- No-show tracking

### Payment Processing
- Pay.nl Alliance model: each tenant is a sub-merchant
- Supported methods: iDEAL, credit card, Bancontact
- Automatic invoicing with configurable VAT rates
- Platform fee (1.5%) deducted automatically
- Payout engine with configurable clearing frequency
- Mandate-based recurring billing for subscriptions

### Access Control
- QR code generation per booking
- SMS verification codes
- NFC card support (customer cards)
- HMAC-SHA256 signed JWT tokens
- Integration with physical door controllers (Salto KS, generic GPIO)

### Building Management & IoT
- Device registration and health monitoring
- Door control automation (open/close based on booking times)
- Climate zone management
- Raspberry Pi API integration
- Automation rules engine

### API & Integrations
- REST API v1 with 20+ endpoints
- GraphQL endpoint
- OAuth 2.0 provider
- Webhook system with retry logic
- API key management with rate limiting
- Calendar feed export (iCal)

### AI Assistant
- GPT-4.1-mini powered tenant assistant
- 13 function calling tools (check availability, create bookings, manage customers, etc.)
- SSE streaming chat panel in admin dashboard

### Customer Management
- Customer database with booking history
- NFC card assignment
- Organization management (companies, clubs)
- Customer groups and segmentation
- CRM with pipeline, quotations, activities

### Point of Sale
- Cash terminal management
- Ticket scanning
- On-site booking creation
- Daily settlement reports

## Comparison with Competitors

### vs Planyo
- BOOQR: Free tier available, built for Dutch sport market
- Planyo: General-purpose, no free tier, not sport-specific

### vs AllUnited
- BOOQR: Modern web platform, API-first, free tier
- AllUnited: Legacy system, no public API, club-management focused

### vs ClubCollect
- BOOQR: Full booking + payment, integrated access control
- ClubCollect: Payment collection only, no booking management

## FAQ

**Is BOOQR free?**
Yes, BOOQR has a free Start tier with 1 location, 1 object, and up to 500 bookings per year. The only cost is a 2% per-booking fee.

**Does BOOQR work for non-sport venues?**
BOOQR is optimized for sport accommodations but the booking system is flexible enough for any venue with time-slot based reservations.

**What payment methods does BOOQR support?**
iDEAL (most popular in the Netherlands), credit card (Visa, Mastercard), and Bancontact, all via Pay.nl.

**Can I use my own domain?**
Yes, custom domains are available on Scale and Enterprise tiers.

**Is there an API?**
Yes, BOOQR offers a REST API v1 and GraphQL endpoint. Documentation at booqr.nl/developers.

**How does access control work?**
Guests receive a QR code or SMS verification code after booking. These codes are verified at the venue entrance via a scanner or keypad. NFC card support is also available.

**Can I integrate BOOQR with my existing systems?**
Yes, via the REST API, GraphQL, webhooks, and OAuth 2.0. Calendar feeds (iCal) are also supported.

## Technical Details for Developers
- OpenAPI spec: https://booqr.nl/api/openapi.json
- API base URL: https://booqr.nl/api/v1
- Authentication: Bearer token (API key from admin dashboard)
- Rate limits: 100 requests/minute (Start), 1000/minute (Pro+)
- Webhook format: JSON POST with HMAC signature verification
- GraphQL endpoint: https://booqr.nl/api/graphql (Pro+ tiers)