unifi-access-airbnb/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Python automation tool that integrates UniFi Access with Airbnb/Hostex reservations, automatically creating and managing visitor access for Airbnb guests. The system fetches reservations from either Hostex API or Airbnb ICS feed, creates UniFi Access visitor accounts with PIN codes based on phone numbers, and provides cross-verification between multiple booking systems.

Core Commands

Development and Execution

• Run the application: python3 main.py
• Install dependencies: pip install -r requirements.txt
• Run with verbose logging: python3 main.py -v
• Specify custom log file: python3 main.py -l custom.log
• List available door groups: python3 main.py --list-door-groups

Configuration Setup

• Setup configuration: cp unifi.conf.example unifi.conf then edit with actual credentials
• Configuration file: unifi.conf (contains API tokens, URLs, and settings)

Architecture Overview

Core Components

1. main.py - Entry point and orchestration

   • Handles command-line arguments and logging setup
   • Coordinates all managers and performs cross-system verification
   • Implements verify_across_systems() for data consistency checks

2. unifi_access.py - UniFi Access API integration

   • UnifiAccessManager class handles all UniFi Access operations
   • Creates/deletes visitors, assigns PIN codes, manages door group access
   • Processes reservations and maintains visitor lifecycle

3. hostex_api.py - Hostex API integration

   • HostexManager fetches reservations from Hostex booking platform
   • Simple API wrapper for reservation data

4. ics_parser.py - Airbnb ICS calendar parsing

   • ICSParser processes Airbnb calendar feeds
   • Extracts reservation data and PIN codes from ICS events

5. notification.py - Simplepush notifications

   • NotificationManager sends status updates and alerts
   • Configurable notification system for operational updates

6. config.py - Configuration management

   • Centralizes configuration loading from unifi.conf
   • Handles API credentials, timing settings, and feature flags

7. utils.py - Shared utilities

   • Logging setup and configuration

Data Flow Architecture

Hostex API ──┐
             ├──► Cross-Verification ──► UniFi Access API
ICS Feed ────┘                          (Visitor Management)
                                              │
                                              ▼
                                        Simplepush Notifications

Key Integration Points

• Reservation Sources: Supports both Hostex API and Airbnb ICS feeds
• PIN Code Generation: Uses last N digits of guest phone numbers
• Cross-Verification: Matches reservations across systems to detect discrepancies
• Visitor Lifecycle: Automatically creates visitors for upcoming stays, deletes past/completed visits
• Door Access: Assigns visitors to configurable door groups in UniFi Access

Configuration Structure

The unifi.conf file contains these key sections:

• [UniFi]: Access controller API endpoint and authentication token
• [Hostex]: Hostex API credentials (optional if using ICS only)
• [Airbnb]: ICS calendar feed URL (optional if using Hostex only)
• [Door]: Default door group ID for visitor access
• [Visitor]: Check-in/out times and PIN code settings
• [Simplepush]: Notification service configuration
• [General]: Logging and PIN code digit count

Development Notes

Dependencies

• requests: HTTP API calls to UniFi Access and Hostex
• icalendar: Parsing Airbnb ICS calendar feeds
• urllib3: HTTP utilities (with SSL warning suppression)
• configparser: Configuration file parsing

Logging Strategy

• Comprehensive debug logging available with -v flag
• File-based logging for operational history
• Different log levels for console vs file output

API Integrations

• UniFi Access: RESTful API for visitor management, requires authentication token
• Hostex: Booking platform API for reservation data
• Simplepush: Simple HTTP-based notification service
• Airbnb ICS: Calendar feed parsing for reservation extraction

Testing and Verification

• Use --list-door-groups to verify UniFi Access connectivity and available door groups
• Run with -v flag to see detailed operation logs
• Check log files for historical operation data and error analysis