Skip to content

Project Overview & Domain Model

1. Project Description

The Portugal Odyssey Platform is a tourism marketplace designed to connect travelers with curated, personalized experiences in Portugal. Unlike traditional booking platforms, it leverages Artificial Intelligence to match customer preferences (context) with a catalog of services provided by partners, orchestrating them into cohesive "Experiences".

The platform handles the entire lifecycle of tourism services: - Partner Onboarding & Management: handling legal, financial, and operational data. - Service Catalog: managing diverse service types (Accommodation, Transport, Activities, etc.). - Contract Management: digitalizing agreements between the platform, partners, and services. - Experience Creation: AI-driven assembly of services into travel packages.

1.1 The Role of AI

The platform is AI-Native, meaning AI is not just an add-on but a core driver of the business logic.

  • Agentic Architecture: The system is designed to be interacted with by AI Agents via the Model Context Protocol (MCP). Agents can query the Knowledge Base (RAG), search for services, and potentially orchestrate actions.
  • Personalization Engine: AI algorithms analyze user preferences (social, environmental, temporal context) to recommend the best fit services.
  • Operational Efficiency: AI assists in parsing partner documents, verifying compliance, and even drafting contracts or service proposals.

2. Top Level Entities & Roles

The platform's Identity and Access Management (IAM) distinguishes three primary top-level entities, each playing a specific role in the ecosystem.

2.1 Admin (Platform Owner)

  • Role: admin
  • Responsibility: Oversees the entire platform, manages partner onboarding approvals, defines global configurations, and handles disputes.
  • Key Interactions:
    • Approves Partner accounts and Service listings.
    • Manages Contract templates.
    • Views global analytics.

2.2 Partner (Service Provider)

  • Role: partner
  • Responsibility: Provides the actual tourism services (hotels, tours, transfers). One Partner can manage multiple Services.
  • Key Interactions:
    • Manages their Partner profile (legal/financial basics).
    • Lists and updates PartnerService offerings.
    • Signs Contract agreements (Partner-level and Service-level).
    • Uploads and maintains compliance Documents.

2.3 End User (Client/Traveler)

  • Role: customer
  • Responsibility: The consumer of the experiences.
  • Key Interactions:
    • Defines preferences and context.
    • Receives Experience recommendations.
    • Books and pays for experiences.

3. Data Domain Models

The following sections describe the core data models that power the platform's business logic.

3.1 Partner Domain

The Partner entity is the root of the supply side. It aggregates all legal, financial, and operational data required to do business.

Partner Entity

Represents a business entity providing services. - Identity: id, name, code, tenant_slug (for multi-tenancy). - Status: PENDING, ACTIVE, SUSPENDED, INACTIVE. - Legal & Financial: - tax_id, vat_number - legal_name, company_registration_number - fiscal_address (Street, City, Country, etc.) - Business Info: - business_address - website, industry, description - contact_person_name - Statistics: PartnerStats tracking total contracts, services, and pending actions.

3.2 Service Domain

A PartnerService is a specific offering provided by a Partner. It is the atomic unit of an Experience.

PartnerService Entity

Represents a specific sellable service. - Core Info: id, partner_id, name, short_description. - Type: ACCOMMODATION, TRANSPORT, ACTIVITY, INSURANCE, FOOD_BEVERAGE, CUSTOM. - Status: DRAFT, ACTIVE, SUSPENDED. - Configuration (Parameters): - The parameters field is a flexible JSON structure defined by ServiceParametersDto. - Location: address, city, coordinates (lat/lng). - Pricing: currency, adults, infants, seniors (base prices). - Capacity: min_people, max_people. - Duration: value, unit (minutes/hours/days). - Multimedia: Lists of images and videos. - Lifecycle Hooks: Configuration for external integration (onStart, onEnd, process_booking) allowing the platform to trigger actions on external partner systems. - Compliance: ServiceDocument list for service-specific licenses or certifications.

4. Service Availability & Calendar Strategy

The platform employs a flexible Inventory Strategy defined within the service parameters, rather than a rigid central booking table. This allows for diverse service types (e.g., a hotel room vs. a walking tour).

4.1 Availability Model (ServiceScheduleDto)

Availability is computed by intersecting the Service Schedule definitions with Existing Bookings.

The schedule parameter defines when a service can be booked:

  1. Calendars (ServiceCalendarDto): A service can have multiple calendars to handle seasonality.

    • Period: start_date to end_date.
    • Slots: A list of ServiceScheduleTimeSlotDto defining specific windows (e.g., "Monday 09:00-11:00", "Friday 14:00-16:00").

    Example Strategy: A "Summer Calendar" might have frequent slots, while a "Winter Calendar" has reduced availability.

  2. Unavailability Rules (ServiceUnavailableDaysDto):

    • Specific Dates: Exact dates blocked off (e.g., "2025-12-25").
    • Weekdays: Recurring blocked days (e.g., "Every Sunday").

  3. Capacity Constraints:

    • Defined by min_people and max_people.
    • System checks if Current Bookings + Requested Participants <= Max Capacity for a given slot.

4.2 Booking Logic

Bookings are made against these availabilities. - Structure: A Booking references an experienceId and customerName (currently simplified). - Validation: When a booking is requested, the system: 1. Checks if the date falls within an active Calendar. 2. Verifies the specific Time Slot exists. 3. Ensures the date is not in Unavailable Days. 4. Validates that Capacity is not exceeded.

4.3 External Synchronization

Through Lifecycle Hooks (api or script), the platform can query external partner systems for real-time availability (Dynamic Inventory) or push verified bookings to their systems.

5. Contract Domain

Contracts govern the relationship between the Platform and the Partners.

Contract Entity

Represents a legal agreement. - Scope: - PARTNER_LEVEL: General agreement covering the partner relationship. - SERVICE_LEVEL: Specific terms for a particular service. - Status: DRAFT, ACTIVE, EXPIRED, TERMINATED. - Lifespan: start_date, end_date. - Content: - template_id: Reference to the standard template used. - terms: JSON object containing the negotiated terms specific to this contract. - template_file_url: The link to the generated PDF.

6. Experience Domain

The Experience is the customer-facing product, dynamically assembled based on context.

Experience Entity

Represents a curated travel package for a client. - Ownership: customer_id. - Status: PENDING, ACTIVE, COMPLETED, CANCELLED. - Context (The "Why"): - Temporal: season, timeOfDay, duration. - Spatial: location, coordinates, proximity. - Social: participants, groupType (e.g., family, couple). - Environmental: weather, noiseLevel. - Timeline: start_date, end_date.

This document serves as a high-level reference for the project's domain and data structure.