# Supabase Database & Auth

TravelAgent uses Supabase as a full-stack Backend-as-a-Service (BaaS) solution. We deeply utilize Supabase's Auth, PostgreSQL database, and most importantly, Row Level Security (RLS) to implement B2B-grade security.

## 🗄️ Database Schema

All database migrations are tracked in the `travelagent/supabase/migrations/` directory. Here is an overview of the core tables:

1. **`users`**
   * **Purpose**: Extends Supabase's built-in `auth.users` to store application-specific roles and profiles.
   * **Key Fields**: `id` (references auth.users), `role` (user, admin, agent), `name`.
2. **`requirements`**
   * **Purpose**: Stores the initial travel requirements filled out manually or parsed from PDF/text imports.
   * **Key Fields**: `user_id`, `origin`, `destinations` (Array), `travel_dates` (JSON), `travelers` (JSON), `budget_range`, `preferences` (JSON), `notes`.
3. **`itineraries`**
   * **Purpose**: Stores the final, structured itinerary generated by the AI.
   * **Key Fields**: `requirement_id` (references requirements), `content` (JSON structure holding days and activities), `user_id`.
4. **`user_favorites`**
   * **Purpose**: Allows each travel agent to build a personal "pocket list" (spots, restaurants, accommodations) that the AI prioritizes during planning.
   * **Key Fields**: `user_id`, `type` (spot/food/accommodation), `name`, `description`, `tags` (Array), `location_data` (Google Places results).
5. **`ai_audit_logs`**
   * **Purpose**: Records latency, token usage, and raw request/response payloads for every Gemini AI call for debugging and cost analysis.
   * **Key Fields**: `user_id`, `action_type`, `prompt_tokens`, `completion_tokens`, `duration_ms`.
6. **`place_cache`**
   * **Purpose**: Caches Google Places API query results to reduce API costs, with a default TTL of 7 days.

***

## 🔐 Auth & Row Level Security (RLS)

This system operates on an **"Invite-Only"** model, meaning **public registration is disabled**. New accounts must be created via an invitation link generated by an `admin` in the dashboard. Users follow the link to set their password and activate their account.

### Row Level Security (RLS) Policies

RLS is enabled on every table to ensure "users can only see their own data".

Taking the `requirements` table as an example, the RLS rules are:

* **SELECT / UPDATE / DELETE**: `auth.uid() = user_id` (Can only operate on their own rows).
* **INSERT**: Can only insert rows where `user_id` matches their own UID.

### Role-Based Access Control (RBAC)

We implemented RBAC combining a custom Postgres Function (`get_my_role()`) and the `users` table:

1. **`admin`**: Can access site-wide data, manage invitations, and view `ai_audit_logs`.
2. **`user` (Travel Agent)**: Default role. Can only access and manipulate their own requirements, itineraries, and favorites.
3. **`agent`**: Reserved internal role for automated system services.

### Server-Side Exceptions (Service Role)

In Next.js Server Actions, when an operation needs to bypass RLS (e.g., an Admin generating a new invite link, or the AI Agent recording an Audit Log), we initialize a Supabase client using the `SUPABASE_SERVICE_ROLE_KEY` to grant superuser privileges. **This key must NEVER be used in frontend components.**


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://letztek.gitbook.io/travelagent/docs/en/architecture/supabase.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.