primitives property

Property

The Property is the largest primitive by surface area. It backs the Ghar Core marketplace, 360 Stays bookings, Property Management leases, and 360 Virtual Tours. A single properties table holds every listing regardless of module, differentiated by property_type and purpose.

Active contributors: Saksham, Ravi

Model

File: app/models/properties.py

The Property class declares composite indexes tuned for the most common filtered feed queries: idx_property_filters on (property_type, purpose, is_available) and idx_property_price on base_price. PostGIS and full-text search indexes are created by migrations, not the model.

Key columns:

• property_type - PropertyType enum. Includes house, apartment, builder_floor, villa, plot, pg, flatmate, office, shop, and others. The PG_FLATMATE_TYPES constant {PropertyType.pg, PropertyType.flatmate} marks types routed through the Flatmates module.
• purpose - PropertyPurpose enum (buy, rent, short_stay). Drives whether a listing shows up in the marketplace, rental search, or 360 Stays.
• status / is_available - PropertyStatus enum plus a denormalized boolean for fast filtering.
• Geospatial: a Geography(Point, 4326) column backed by PostGIS. The model ships with SQLite compile shims so Base.metadata.create_all works in tests.
• __ts_vector__ - PostgreSQL tsvector column for full-text search.
• base_price, monthly_rent, daily_rate - pricing varies by purpose.
• is_seed_data - marks seed/demo listings. The 02_clear_data.py script uses this to scope deletions.

Relationships

• User (owner) - many-to-one via owner foreign key. Every property belongs to a user.
• PropertyImage - one-to-many, with ImageCategory enum (room, hall, kitchen, bathroom, floor_plan, etc.)
• Amenity and PropertyAmenity - many-to-many bridge
• Visit, Booking - child entities with ON DELETE CASCADE
• Lease - active when the property is under property management
• Tour - optional virtual tour attached to the listing
• RentCharge - one-to-many. Rent ledger entries for PM-managed properties.
• MaintenanceRequest - one-to-many. Maintenance tickets filed against the property.
• Document - one-to-many. Lease agreements, receipts, and other attachments.
• Expense - one-to-many. Owner expenses tracked by the PM module.
• InspectionChecklist - one-to-many. Move-in/move-out condition reports.
• property_embeddings - pgvector row used for semantic search (see app/vector/)

Search and discovery

The Property model is queried through app/repositories/property_repository.py and property_query_builder.py, which compose geospatial filters (ST_DWithin for radius, ST_Distance for sorting), full-text filters against __ts_vector__, and hybrid vector+text scoring through the property_embeddings table. List, search, recommendations, and /me endpoints now return a 3-tuple (items, next_cursor, has_more) for keyset cursor pagination, following the June 2026 refactor.

Service layer

The property service is split across app/services/property/ (crud, search, recommendations). See features/ghar-core.md for the discovery feed, swipe mechanics, and recommendation flow.