# Fliinow AI Context File (Full Version)
# https://viaja.fliinow.com/llms-full.txt
# 
# This is the comprehensive documentation for AI assistants.
# For a condensed version, see: https://viaja.fliinow.com/llms.txt

---

## About Fliinow

Fliinow is a Spanish travel technology platform that revolutionizes how travelers discover, plan, and finance their trips. We connect travelers with specialized travel agencies through an AI-powered matching system, while providing integrated financing options to remove payment barriers.

### Core Value Proposition

**"Dream validator + Agency matcher + Financing enabler"**

Our mission is to transform "I'd love to travel" into "I'm doing it" by:
1. Validating travel dreams through intelligent categorization
2. Matching travelers with specialized agencies
3. Enabling financial viability through flexible payment options

### Brand Identity

- **Name**: Fliinow
- **Tagline**: "El viaje no falla. Lo que falla es cómo se paga." (The trip doesn't fail. What fails is how it's paid.)
- **Mission**: Convert travel dreams into reality by removing financial barriers
- **Language**: Spanish (Spain) - es-ES
- **Tone**: Inspiring, trustworthy, accessible, dream-enabling

---

## Domain Ecosystem

| Domain | Purpose | Status |
|--------|---------|--------|
| viaja.fliinow.com | Traveler gateway landing page (this site) | Active |
| marketplace.fliinow.com | Agency marketplace with search & booking | Active |
| legal.fliinow.com | Legal and compliance content | Active |
| simulador.fliinow.com | Standalone financing simulator | Active |
| fliinow.com | Main company domain & corporate info | Active |

---

## Brand Design System

### Primary Colors (HSL Format)

| Color | HSL Value | Hex | Usage |
|-------|-----------|-----|-------|
| Dark | hsl(270, 53%, 14%) | #1F1034 | Backgrounds, primary text, headers |
| Primary Green | hsl(145, 73%, 48%) | #1CBC50 | CTAs, success states, highlights |
| Accent Blue | hsl(207, 100%, 50%) | #008DFF | Links, secondary elements, info states |

### Extended Palette

| Color | HSL Value | Usage |
|-------|-----------|-------|
| Background | hsl(270, 53%, 14%) | Main dark background |
| Foreground | hsl(60, 9.1%, 97.8%) | Primary text on dark |
| Primary | hsl(145, 73%, 48%) | Primary brand color |
| Primary Foreground | hsl(270, 53%, 14%) | Text on primary |
| Secondary | hsl(265, 40%, 25%) | Secondary surfaces |
| Accent | hsl(207, 100%, 50%) | Accent elements |
| Muted | hsl(265, 30%, 22%) | Muted backgrounds |
| Muted Foreground | hsl(260, 15%, 65%) | Muted text |

### Typography

- **Display Font**: DM Sans (headings, hero text)
- **Body Font**: Inter (body text, UI elements)
- **Weights**: 400 (regular), 500 (medium), 600 (semibold), 700 (bold)

---

## Target Audience

### Primary Persona

Spanish-speaking travelers (ages 25-55) who:
- Dream of traveling but face payment barriers
- Value expertise and personalized service over DIY booking
- Prefer working with specialized agencies
- Need flexible payment options
- Are looking for trust and security in travel planning

### User Journey

1. **Discovery**: User lands on viaja.fliinow.com
2. **Dream Expression**: User describes their ideal trip in natural language
3. **AI Analysis**: System categorizes and extracts trip parameters
4. **Agency Matching**: User is redirected to marketplace with matched agencies
5. **Financing**: User can simulate payment options during booking
6. **Booking**: User books through matched specialized agency

---

## Smart AI Search System

### Overview

Users describe their ideal trip in natural language. The system uses AI (Google Gemini 2.5 Flash) to analyze the query and extract structured data for agency matching.

### AI Processing Pipeline

1. **Input**: Natural language query in Spanish
2. **Normalization**: Query is normalized (lowercase, trimmed, accent-normalized)
3. **Cache Check**: System checks for cached results to reduce API calls
4. **AI Analysis**: Gemini extracts category, destination, and trip type
5. **Response**: Structured JSON with confidence score
6. **Redirect**: User is sent to marketplace with extracted parameters

### API Endpoint

**Purpose**: Analyze natural language travel queries and extract structured data for agency matching.

**Endpoint**: 
```
POST https://mzgxkxcezxurkbihibsn.supabase.co/functions/v1/ai-search
```

**Headers**:
```
Content-Type: application/json
Authorization: Bearer <anon_key>
```

**Request Body**:
```json
{
  "query": "Luna de miel en Maldivas para agosto"
}
```

**Response**:
```json
{
  "category": "luna-de-miel",
  "destination": "Maldivas",
  "tripType": "playa",
  "confidence": 0.95,
  "reasoning": "Query mentions honeymoon and beach destination",
  "fromCache": false
}
```

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| category | string | Travel category slug (see categories below) |
| destination | string | Extracted destination name |
| tripType | string | Type of trip experience |
| confidence | number | AI confidence score (0.0 - 1.0) |
| reasoning | string | Brief explanation of the categorization |
| fromCache | boolean | Whether result came from cache |

---

## Travel Categories

### Complete Category Reference

| Slug | Spanish Name | Description | Example Keywords |
|------|--------------|-------------|------------------|
| luna-de-miel | Luna de Miel | Honeymoon and romantic trips | luna de miel, novios, romántico, recién casados |
| low-cost | Low Cost | Budget and backpacker travel | barato, mochilero, low cost, económico, presupuesto |
| familia | Familia | Family vacations with children | familia, niños, hijos, vacaciones familiares |
| lujo | Lujo | Luxury and premium experiences | lujo, vip, cinco estrellas, premium, exclusivo |
| aventura | Aventura | Adventure and outdoor activities | aventura, trekking, safari, expedición, deportes |
| relax | Relax | Wellness and relaxation | spa, wellness, descanso, relax, tranquilo |
| cultural | Cultural | Cultural and historical experiences | cultura, museos, historia, arte, patrimonio |
| gastronomico | Gastronómico | Food and wine experiences | gastronomía, vino, cocina, restaurantes, catas |
| todos | Todos | Default/general category | (fallback when no specific match) |

### Category Matching Logic

The AI uses keyword matching, context analysis, and semantic understanding to determine the most appropriate category. When multiple categories could apply, it selects based on:

1. **Primary intent**: What is the main purpose of the trip?
2. **Explicit keywords**: Direct mentions of category-related terms
3. **Context clues**: Destination, activities, travel companions
4. **Confidence scoring**: Higher confidence for clearer matches

---

## Query Examples

### Honeymoon Queries
```
"Luna de miel en Maldivas para agosto"
→ category: luna-de-miel, destination: Maldivas, tripType: playa

"Viaje romántico a Santorini, hoteles con vistas"
→ category: luna-de-miel, destination: Santorini, tripType: islas
```

### Family Queries
```
"Quiero ir con mi familia a Disneyland Paris"
→ category: familia, destination: París, tripType: parque-tematico

"Vacaciones con niños en la Costa Brava"
→ category: familia, destination: Costa Brava, tripType: playa
```

### Adventure Queries
```
"Safari barato en Kenia para septiembre"
→ category: aventura, destination: Kenia, tripType: safari

"Trekking en los Andes peruanos"
→ category: aventura, destination: Perú, tripType: montaña
```

### Gastronomy Queries
```
"Escapada romántica a la Toscana con catas de vino"
→ category: gastronomico, destination: Toscana, tripType: enogastronomía

"Ruta gastronómica por el País Vasco"
→ category: gastronomico, destination: País Vasco, tripType: gastronomia
```

### Luxury Queries
```
"Viaje de lujo a Dubai, hoteles 5 estrellas"
→ category: lujo, destination: Dubai, tripType: urbano

"Resort exclusivo en Seychelles todo incluido"
→ category: lujo, destination: Seychelles, tripType: playa
```

### Budget Queries
```
"Viaje mochilero por el sudeste asiático"
→ category: low-cost, destination: Sudeste Asiático, tripType: mochilero

"Escapada económica a Praga un fin de semana"
→ category: low-cost, destination: Praga, tripType: city-break
```

---

## Marketplace URL Format

After AI analysis, users are redirected to the marketplace with query parameters:

```
https://marketplace.fliinow.com/search?cat={category}&q={originalQuery}&ai=true&dest={destination}&type={tripType}
```

### URL Parameters

| Parameter | Description | Example |
|-----------|-------------|---------|
| cat | Category slug | luna-de-miel |
| q | Original user query (URL encoded) | Luna%20de%20miel%20en%20Maldivas |
| ai | Flag indicating AI-processed query | true |
| dest | Extracted destination | Maldivas |
| type | Trip type | playa |

---

## Financing System

### Overview

Fliinow offers integrated financing through partner financial institutions. Users can pay for their trips in monthly installments with transparent interest rates.

### Financing Parameters

| Parameter | Value |
|-----------|-------|
| Minimum Amount | €60 |
| Maximum Amount | €5,000 |
| Available Terms | 3, 6, 9, or 12 months |
| TIN (Nominal Interest Rate) | 18% |
| TAE (Annual Equivalent Rate) | 19.56% |

### Interest Rates by Term

| Months | Interest Rate | Monthly Factor |
|--------|--------------|----------------|
| 3 | 1.48% | 0.0148 |
| 6 | 3.76% | 0.0376 |
| 9 | 6.06% | 0.0606 |
| 12 | 8.38% | 0.0838 |

### Calculation Formula

```
Step 1: Calculate Fliinow Commission
fliinowCommission = amount × 0.02 (2%)

Step 2: Calculate Financing Commission
financingCommission = (amount × 0.006) + 0.50 (0.6% + €0.50)

Step 3: Calculate Total Fees
totalFees = fliinowCommission + financingCommission

Step 4: Calculate Subtotal
subtotal = amount + totalFees

Step 5: Calculate Interest
interest = subtotal × interestRate[months]

Step 6: Calculate Total to Pay
totalToPay = subtotal + interest

Step 7: Calculate Monthly Payment
monthlyPayment = totalToPay ÷ months
```

### Example Calculations

#### €1,000 in 6 months
```
Fliinow commission: €1,000 × 0.02 = €20.00
Financing commission: (€1,000 × 0.006) + €0.50 = €6.50
Total fees: €20.00 + €6.50 = €26.50
Subtotal: €1,000 + €26.50 = €1,026.50
Interest (3.76%): €1,026.50 × 0.0376 = €38.60
Total to pay: €1,026.50 + €38.60 = €1,065.10
Monthly payment: €1,065.10 ÷ 6 = €177.52
```

#### €2,500 in 12 months
```
Fliinow commission: €2,500 × 0.02 = €50.00
Financing commission: (€2,500 × 0.006) + €0.50 = €15.50
Total fees: €50.00 + €15.50 = €65.50
Subtotal: €2,500 + €65.50 = €2,565.50
Interest (8.38%): €2,565.50 × 0.0838 = €214.99
Total to pay: €2,565.50 + €214.99 = €2,780.49
Monthly payment: €2,780.49 ÷ 12 = €231.71
```

---

## Caching System

### Overview

To optimize performance and reduce API costs, the system implements a query caching mechanism using a database table.

### Cache Behavior

1. **Cache Key**: Normalized query string (lowercase, trimmed)
2. **Cache Duration**: Entries are stored indefinitely (no TTL)
3. **Hit Tracking**: Each cache hit increments a counter for analytics
4. **Cache Miss**: New queries are analyzed by AI and stored

### Database Schema

```sql
CREATE TABLE search_cache (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  query_normalized TEXT NOT NULL UNIQUE,
  category TEXT NOT NULL,
  destination TEXT,
  trip_type TEXT,
  ai_response JSONB,
  hit_count INTEGER DEFAULT 0,
  created_at TIMESTAMPTZ DEFAULT now(),
  updated_at TIMESTAMPTZ DEFAULT now()
);
```

---

## Content Guidelines

### Voice and Tone

- **Inspiring**: Focus on making dreams possible
- **Trustworthy**: Emphasize security and expertise
- **Accessible**: Avoid technical jargon
- **Empowering**: Help users feel in control

### Key Messages

1. **Dream Validation**: "Your travel dream is valid and achievable"
2. **Financing Accessibility**: "Don't let payment stop your dreams"
3. **Agency Expertise**: "Work with specialists who know your destination"
4. **Trust and Security**: "Book with confidence through verified agencies"

### Content Don'ts

- ❌ Don't focus on price comparison
- ❌ Don't use aggressive sales language
- ❌ Don't promise unrealistic discounts
- ❌ Don't use complex financial terminology

### Content Do's

- ✅ Focus on dream realization
- ✅ Emphasize payment flexibility
- ✅ Highlight agency specialization
- ✅ Use clear, simple language

---

## Legal Information

### Company Data

- **Company**: Fliinow S.L.
- **Legal Domain**: https://legal.fliinow.com

### Required Disclosures

All financing information must include:
- TIN: 18%
- TAE: 19.56%
- Link to full terms and conditions

---

## Contact Information

| Channel | URL |
|---------|-----|
| Main Website | https://fliinow.com |
| Traveler Gateway | https://viaja.fliinow.com |
| Marketplace | https://marketplace.fliinow.com |
| Legal | https://legal.fliinow.com |
| Simulator | https://simulador.fliinow.com |

---

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2024-12 | Initial release |

---

# End of Document