primitives tour

Tour

Tours are the 360 Virtual Tours primitive. A tour is a collection of 360-degree panoramic scenes that a viewer navigates by clicking hotspots. Tours can be published publicly, embedded on custom domains, and instrumented with analytics. The Tour model file is the largest in app/models/ at 482 lines, covering tours, scenes, hotspots, analytics, AI jobs, media, branding, and custom domains.

Active contributors: Saksham, Ravi

Model

File: app/models/tours.py

The Tour class uses a UUID string primary key (generate_uuid) rather than an auto-incrementing int. Key columns:

• user_id - the tour creator. ON DELETE CASCADE.
• title, description - display fields
• status - TourStatus enum (draft, published, archived)
• visibility - TourVisibility enum (private, unlisted, public). Distinct from is_public (a legacy boolean kept for backward compatibility).
• is_featured - admin-curated flag for the public gallery
• view_count, like_count, share_count - denormalized engagement counters
• settings - JSONB for tour-wide configuration (autoplay, audio, transition style)
• thumbnail_url - the cover image
• published_at, archived_at - lifecycle timestamps

Indexes: idx_tours_user_id, idx_tours_status, and a composite idx_tours_user_status for the "my tours" dashboard query.

Scenes and hotspots

A tour contains many Scene records. Each scene is a single 360-degree panorama with its own media file, floor plan link, and initial camera pose. Scenes contain many Hotspot records, typed by HotspotType (navigation, info, audio, video, link, custom). Navigation hotspots link scenes together; the rest embed rich content.

Analytics

TourAnalyticsEvent records every view, hotspot click, and share. Events stream in through the public tour viewer and aggregate into the denormalized counters on Tour. A UserSession table groups events by anonymous viewer session.

AI jobs

The AIJob table tracks asynchronous AI processing: scene_analysis (auto-generating hotspot suggestions from a panorama) and hotspot_generation. Jobs move through AIJobStatus (pending, processing, completed, failed, cancelled). The websocket endpoint /ws/jobs/{job_id} pushes real-time status updates to the tour editor.

Custom domains

CustomDomain links a tour to a vanity URL (e.g. tours.acme.com/listing-42). The model tracks DNS verification (CustomDomainVerificationStatus: pending, verified, failed) and SSL provisioning (CustomDomainSSLStatus: none, pending, active, failed). The /api/v1/custom-domains router handles DNS challenge issuance and verification callbacks.

Service layer

Tour business logic lives in app/services/tour/ and app/services/tour_ai/. The AI processing pipeline is described in features/virtual-tours.md. REST endpoints are under /api/v1/tours, /api/v1/scenes, /api/v1/hotspots, /api/v1/floor-plans, and /api/v1/public (for the unauthenticated viewer).