# Airbnb-Style Rental Marketplace Backend
Version : 1.0.108

airbnb is a global platform enabling hosts to list properties and guests to book short-term stays with secure payments, messaging, and review systems. It connects hosts and guests through a robust travel/hospitality marketplace, handling authentication, bookings, payments, and moderation. The backend supports global operations with multi-language and multi-currency features...

## How to Use Project Documents

The `Airbnb` project has been designed and generated using **Mindbricks**, a powerful microservice-based backend generation platform. All documentation is automatically produced by the **Mindbricks Genesis Engine**, based on the high-level architectural patterns defined by the user or inferred by AI.

This documentation set is intended for both **AI agents** and **human developers**—including frontend and backend engineers—who need precise and structured information about how to interact with the backend services of this project. Each document reflects the live architecture of the system, providing a reliable reference for API consumption, data models, authentication flows, and business logic.

By following this documentation, developers can seamlessly integrate with the backend, while AI agents can use it to reason about the service structure, make accurate decisions, or even generate compatible client-side code.

## Accessing Project Services

Each service generated by Mindbricks is exposed via a **dedicated REST API** endpoint. Every service documentation set includes the **base URL** of that service along with the **specific API paths** for each available route.

Before consuming any API, developers or agents must understand the service URL structure and environment-specific endpoints.

### Service Endpoint Structure

| Environment | URL Pattern Example |
|-------------|---------------------|
| **Preview** | `https://airbnb3.prw.mindbricks.com/auth-api` |
| **Staging** | `https://airbnb3-stage.mindbricks.co/auth-api` |
| **Production** | `https://airbnb3.mindbricks.co/auth-api` |


Replace `auth` with the actual service name as lower case (e.g., `order-api`, `bff-service`, customermanagement-api etc.).

### Environment Usage Notes

* **Preview APIs** become accessible after a project is previewed inside the Mindbricks platform. These are ideal for development and testing.
* **Staging** and **Production** APIs are only accessible after the project is deployed to cloud environments provisioned via Mindbricks.
* In some cases, the project owner may choose to deploy services on their **own infrastructure**. In such scenarios, the service base URLs will be **custom** and should be communicated manually by the project owner to developers or AI agents.

> **Frontend applications** should be designed to **easily switch between environments**, allowing dynamic endpoint targeting for Preview, Staging, and Production.

## Getting Started: Use the Auth Service First

Before interacting with other services in the `Airbnb` project, **AI agents and developers should begin by integrating with the Auth Service**.

Mindbricks automatically generates a dedicated authentication microservice based on the project’s authentication definitions provided by the architect. This service provides the essential user and access management foundation for the project.

Agents should first utilize the Auth Service to:

* Register and authenticate users (login)
* Manage users, roles, and permissions
* Handle user groups (if defined)
* Support multi-tenancy logic (if configured)
* Perform Policy-Based Access Control (PBAC), if activated by the architect

### Auth Service Documentation

Use the following resources to understand and integrate the Auth Service:

* **REST API Guide** – ideal for frontend and direct HTTP usage  
  [Auth REST API Guide](docs/auth-service/rest-api-guide.html)

* **Event Guide** – helpful for event-driven or cross-service integrations  
  [Auth Event Guide](docs/auth-service/event-guide.html)

* **Service Design Document** – overall structure, patterns, and logic  
  [Auth Service Design](docs/auth-service/service-design.html)

> **Note:** For most frontend use cases, the **REST API Guide** will be the primary source. The **Event Guide** and **Service Design** documents are especially useful when integrating with other backend microservices or building systems that interact with the auth service indirectly.

## Using the BFF (Backend-for-Frontend) Service

In Mindbricks, all backend services are designed with an advanced **CQRS (Command Query Responsibility Segregation)** architecture. Within this architecture, **business services** are responsible for managing their respective domains and ensuring the accuracy and freshness of domain data.

The **BFF service** complements these business services by providing a **read-only** aggregation and query layer tailored specifically for frontend and client-side applications.

### Key Principles of the BFF Service

* **Elasticsearch Replicas for Fast Queries:**  
  Each data object managed by a business service is automatically replicated as an **Elasticsearch index**, making it accessible for fast, frontend-oriented queries through the BFF.

* **Cross-Service Data Aggregation:**  
  The BFF offers an **aggregation layer** capable of combining data across multiple services, enabling complex filters, searches, and unified views of related data.

* **Read-Only by Design:**  
  The BFF service is **strictly read-only**. All create, update, or delete operations must be performed through the relevant business services, or via event-driven sagas if designed.

### BFF Service Documentation

* **REST API Guide** – querying aggregated and indexed data  
  [BFF REST API Guide](docs/bff-service/rest-api-guide.html)

* **Event Guide** – syncing strategies across replicas  
  [BFF Event Guide](docs/bff-service/event-guide.html)

* **Service Design** – aggregation patterns and index structures  
  [BFF Service Design](docs/bff-service/service-design.html)

> **Tip:** Use the BFF service as the **main entry point for all frontend data queries**. It simplifies access, reduces round-trips, and ensures that data is shaped appropriately for the UI layer.

## Business Services Overview

The `Airbnb-Style Rental Marketplace Backend` project consists of multiple **business services**, each responsible for managing a specific domain within the system. These services expose their own REST APIs and documentation sets, and are accessible based on the environment (Preview, Staging, Production).

### Usage Guidance

Business services are primarily designed to:

* Handle the **state and operations of domain data**
* Offer **Create, Update, Delete** operations over owned entities
* Serve **direct data queries** (`get`, `list`) for their own objects when needed

For advanced query needs across multiple services or aggregated views, prefer using the [BFF service](#using-the-bff-backend-for-frontend-service).

### Available Business Services


### messaging Service

**Description:** Enables secure in-app messaging between guests and hosts. Handles threads, messages (with text/media/system types), abuse flagging, and admin moderation for resolution..

**Documentation:**

* [REST API Guide](docs/messaging-service/rest-api-guide.html)
* [Event Guide](docs/messaging-service/event-guide.html)
* [Service Design](docs/messaging-service/service-design.html)

**Base URL Examples:**

| Environment | URL |
|-------------|---------------------|
| **Preview** | `https://airbnb3.prw.mindbricks.com/messaging-api` |
| **Staging** | `https://airbnb3-stage.mindbricks.co/messaging-api` |
| **Production** | `https://airbnb3.mindbricks.co/messaging-api` |


### propertyCatalog Service

**Description:** Service for management of property listings, calendars, amenities, and localization for a short-term rental marketplace. Hosts can manage listings, availability, multi-language descriptions, policies, pricing, and attributes, served for global search and discovery...

**Documentation:**

* [REST API Guide](docs/propertyCatalog-service/rest-api-guide.html)
* [Event Guide](docs/propertyCatalog-service/event-guide.html)
* [Service Design](docs/propertyCatalog-service/service-design.html)

**Base URL Examples:**

| Environment | URL |
|-------------|---------------------|
| **Preview** | `https://airbnb3.prw.mindbricks.com/propertycatalog-api` |
| **Staging** | `https://airbnb3-stage.mindbricks.co/propertycatalog-api` |
| **Production** | `https://airbnb3.mindbricks.co/propertycatalog-api` |


### bookingManagement Service

**Description:** Orchestrates booking, payment, calendar, changewsand dispute flows for Airbnb-style short-term rental marketplace...test Handles reservations, approval, Stripe payments, iCal sync, payment records, and the dispute/refund lifecycle with host/guest/admin visibility.

**Documentation:**

* [REST API Guide](docs/bookingManagement-service/rest-api-guide.html)
* [Event Guide](docs/bookingManagement-service/event-guide.html)
* [Service Design](docs/bookingManagement-service/service-design.html)

**Base URL Examples:**

| Environment | URL |
|-------------|---------------------|
| **Preview** | `https://airbnb3.prw.mindbricks.com/bookingmanagement-api` |
| **Staging** | `https://airbnb3-stage.mindbricks.co/bookingmanagement-api` |
| **Production** | `https://airbnb3.mindbricks.co/bookingmanagement-api` |


### reviewSystem Service

**Description:** Handles double-blind, moderated reviews and rating aggregation for stays. Allows guests/hosts to review each other and listings, supports moderation, and exposes aggregate stats for listings/profiles...

**Documentation:**

* [REST API Guide](docs/reviewSystem-service/rest-api-guide.html)
* [Event Guide](docs/reviewSystem-service/event-guide.html)
* [Service Design](docs/reviewSystem-service/service-design.html)

**Base URL Examples:**

| Environment | URL |
|-------------|---------------------|
| **Preview** | `https://airbnb3.prw.mindbricks.com/reviewsystem-api` |
| **Staging** | `https://airbnb3-stage.mindbricks.co/reviewsystem-api` |
| **Production** | `https://airbnb3.mindbricks.co/reviewsystem-api` |


### platformAdmin Service

**Description:** Administrative and compliance management backend for moderation, audit, dispute, financial oversight, localization, and GDPR in the Airbnb-style rental platform.

**Documentation:**

* [REST API Guide](docs/platformAdmin-service/rest-api-guide.html)
* [Event Guide](docs/platformAdmin-service/event-guide.html)
* [Service Design](docs/platformAdmin-service/service-design.html)

**Base URL Examples:**

| Environment | URL |
|-------------|---------------------|
| **Preview** | `https://airbnb3.prw.mindbricks.com/platformadmin-api` |
| **Staging** | `https://airbnb3-stage.mindbricks.co/platformadmin-api` |
| **Production** | `https://airbnb3.mindbricks.co/platformadmin-api` |


### agentHub Service

**Description:** AI Agent Hub

**Documentation:**

* [REST API Guide](docs/agentHub-service/rest-api-guide.html)
* [Event Guide](docs/agentHub-service/event-guide.html)
* [Service Design](docs/agentHub-service/service-design.html)

**Base URL Examples:**

| Environment | URL |
|-------------|---------------------|
| **Preview** | `https://airbnb3.prw.mindbricks.com/agenthub-api` |
| **Staging** | `https://airbnb3-stage.mindbricks.co/agenthub-api` |
| **Production** | `https://airbnb3.mindbricks.co/agenthub-api` |


## Connect via MCP (Model Context Protocol)

All backend services in the `Airbnb` project expose their Business APIs as **MCP tools**. These tools are aggregated by the **MCP-BFF** service into a single unified endpoint that external AI tools can connect to.

### Unified MCP Endpoint

| Environment | StreamableHTTP (recommended) | SSE (legacy fallback) |
|-------------|------------------------------|------------------------|
| **Preview** | `https://airbnb3.prw.mindbricks.com/mcpbff-api/mcp` | `https://airbnb3.prw.mindbricks.com/mcpbff-api/mcp/sse` |
| **Staging** | `https://airbnb3-stage.mindbricks.co/mcpbff-api/mcp` | `https://airbnb3-stage.mindbricks.co/mcpbff-api/mcp/sse` |
| **Production** | `https://airbnb3.mindbricks.co/mcpbff-api/mcp` | `https://airbnb3.mindbricks.co/mcpbff-api/mcp/sse` |

### Authentication

MCP connections require authentication via the `Authorization` header:

- **API Key (recommended for AI agents):** `Authorization: Bearer sk_mbx_your_api_key_here`
  API keys are long-lived and don't expire like JWT tokens. Create one from the profile page.
- **JWT Token:** `Authorization: Bearer {accessToken}`
  Use a valid access token obtained from the login API.

> **OAuth is not supported** for MCP connections at this time.

### Connecting from Cursor

Add the following to your project's `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "airbnb3": {
      "url": "https://airbnb3.prw.mindbricks.com/mcpbff-api/mcp",
      "headers": {
        "Authorization": "Bearer sk_mbx_your_api_key_here"
      }
    }
  }
}
```

### Connecting from Claude Desktop

Add to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "airbnb3": {
      "url": "https://airbnb3.prw.mindbricks.com/mcpbff-api/mcp",
      "headers": {
        "Authorization": "Bearer sk_mbx_your_api_key_here"
      }
    }
  }
}
```

### What's Available

Once connected, the AI tool can discover and call all Business API tools from all services — CRUD operations, custom queries, file operations, and more. The MCP-BFF handles routing each tool call to the correct backend service and propagates your authentication context.

---

## Conclusion

This documentation set provides a comprehensive guide for understanding and consuming the `Airbnb-Style Rental Marketplace Backend` backend, generated by the Mindbricks platform. It is structured to support both AI agents and human developers in navigating authentication, data access, service responsibilities, and system architecture.

To summarize:

* Start with the **Auth Service** to manage users, roles, sessions, and permissions.
* Use the **BFF Service** for optimized, read-only data queries and cross-service aggregation.
* Refer to the **Business Services** when you need to manage domain-specific data or perform direct CRUD operations.

Each service offers a complete set of documentation—REST API guides, event interface definitions, and design insights—to help you integrate efficiently and confidently.

Whether you are building a frontend application, configuring an automation agent, or simply exploring the architecture, this documentation is your primary reference for working with the backend of this project.

> For environment-specific access, ensure you're using the correct base URLs (Preview, Staging, Production), and coordinate with the project owner for any custom deployments.