360 Ghar Backend

A high-performance, modern backend powering 360 Ghar's unified real estate platform. Built with FastAPI and PostgreSQL, this API serves three integrated modules:

- 360 Ghar Core: Real estate marketplace for buying and renting properties with swipe-based discovery, property visits, and agent coordination
- 360 Stays: Short-stay booking platform for hotels, vacation rentals, and temporary accommodations
- Property Management: Comprehensive property management system for landlords and property managers (leases, rent collection, maintenance, reporting)

Table of Contents

- About The Project
- Key Features
- Tech Stack
- Project Structure
- API Endpoints
- Getting Started
- Running with Docker
- Environment Configuration
- API Documentation
- MCP HTTP Server
- Key Implementation Details
- Contributing
- License

About The Project

360 Ghar is a unified real estate platform serving the complete property lifecycle:

- 360 Ghar Core revolutionizes property discovery through an engaging, swipe-based interface combined with powerful map-based search and professional agent assistance for buying and renting properties.
- 360 Stays provides a complete short-stay booking system with availability checks, dynamic pricing, and guest management for hotels and vacation rentals.
- Property Management empowers landlords and property managers with tools for tenant management, lease tracking, rent collection, maintenance handling, and financial reporting.

All three modules share a common backend infrastructure, user authentication, and property database.

Overview Video

A 2-3 minute silent walkthrough of the platform's six modules and architecture. Read the full wiki.

Key Features

360 Ghar Core (Real Estate Marketplace)

- Tinder-like Property Swiping: Intuitive swipe interface to like or pass on properties - Advanced Property Search: Unified endpoint supporting geospatial, full-text, and filtered search - Property Visit Scheduling: Agent-managed visit coordination with automatic assignment - Agent Management: Comprehensive agent system with load balancing and performance tracking - User Personalization: Preference learning from user interactions and search history

360 Stays (Short-Stay Bookings)

- Short-stay Bookings: Complete booking system with availability checks and pricing - Dynamic Pricing: Configurable daily rates and minimum stay requirements - Guest Management: Booking lifecycle from reservation to checkout

Property Management

- Tenant & Lease Management: Track tenants, leases, and rental applications - Rent Collection: Manual-first rent ledger with charge generation and payment tracking - Maintenance Requests: Work order management for property upkeep - Document Vault: Secure storage for leases, receipts, and property documents - Financial Reporting: Rent roll, income statements, P&L, and occupancy reports

Technical Highlights

- Modern & Fast: Built with FastAPI for high performance and automatic API documentation - Fully Async: Asynchronous architecture from API to database operations - Geospatial Powered: PostgreSQL + PostGIS for efficient location-based queries - Secure Authentication: Supabase Auth integration with phone-based primary authentication - Performance Optimized: Designed for PgBouncer compatibility and scalable connection pooling - Production Ready: Sentry integration, comprehensive logging, and error handling - Containerized: Full Docker support with Docker Compose for development

Tech Stack

| Category | Technology |
| --------------------- | ------------------------------------------------------------- |
| Backend Framework | FastAPI |
| Database | PostgreSQL + PostGIS |
| ORM | SQLAlchemy 2.0+ (Async) |
| Data Validation | Pydantic |
| Authentication | Supabase Auth |
| Caching | Redis (optional) |
| Migrations | Supabase Migrations |
| Observability | Sentry |
| Containerization | Docker & Docker Compose |
| Geospatial | GeoAlchemy2 |

Project Structure

app/
├── api/                 # API endpoints and routing
│   └── api_v1/
│       └── endpoints/   # Individual endpoint modules
├── config/              # Compatibility config package; implementation remains in core/config.py
├── core/                # Core components (config, db, auth, logging)
├── infrastructure/      # App factory helpers, adapters, lifespan, middleware wiring
├── middleware/          # Custom middleware (rate limiting, security)
├── models/              # SQLAlchemy ORM models and enums  
├── modules/             # Reserved namespace for future physical domain packages
├── schemas/             # Pydantic schemas for data validation
├── services/            # Business logic and database operations (legacy implementation layer)
├── shared/              # Reserved namespace for future physical shared packages
└── utils/               # Utility functions
supabase/

└── migrations/          # Database schema migrations
populate_data/           # Legacy data files (preserved for reference)

seed_data/               # Data seeding system (hardcoded, seed, generated categories)

tests/                   # Test files

API Endpoints

All endpoints are prefixed with /api/v1.

🔑 Authentication Model

- Clients authenticate directly with Supabase Auth SDK (phone-first, email optional). - Backend expects Authorization: Bearer <supabase_access_token> for protected routes. - Backend no longer exposes /api/v1/auth/* user-session endpoints.

👤 Users (/users)

- GET /profile/: Get current user profile - PUT /profile/: Update user profile information - PUT /preferences/: Update property search preferences - PUT /location/: Update user's current location

🏠 Properties (/properties)

- GET /: Unified Property Search with geospatial, text search, and advanced filtering - GET /recommendations/: Get personalized property recommendations - GET /{property_id}/: Get detailed property information - POST /: Create new property (authenticated users) - PUT /{property_id}/: Update property (property owners) - DELETE /{property_id}/: Delete property (property owners)

…