# Firestore Composite Index Setup Guide

## Why We Need a Composite Index

The MediLink orchestrator needs to efficiently query the `queues` collection to find unacknowledged messages for specific machines. Without an index, Firestore would have to scan all documents, which is inefficient and costly.

The query pattern is:
```javascript
// Find unacknowledged messages for a specific machine, ordered by creation time
collection("queues")
  .where("machine_id", "==", "clinic-001")
  .where("acked", "==", false)
  .orderBy("created_at")
  .limit(10)
```

This requires a composite index on: `machine_id (ASC), acked (ASC), created_at (ASC)`

## Step-by-Step: Create Composite Index

### Step 1: Access Firestore Indexes

1. Go to: https://console.cloud.google.com/firestore/indexes?project=genial-analyzer-476721-f8
2. Click the **"Create Index"** button (or **"Add Index"**)

### Step 2: Configure the Index

**Collection ID:**
- Enter: `queues`

**Index Fields:**
- **Field 1:**
  - Field path: `machine_id`
  - Array config: (leave default)
  - Order: `Ascending`

- **Field 2:**
  - Field path: `acked`
  - Array config: (leave default)
  - Order: `Ascending`

- **Field 3:**
  - Field path: `created_at`
  - Array config: (leave default)
  - Order: `Ascending`

**Query Scope:**
- Leave as default: `Collection`

### Step 3: Create the Index

1. Click **"Create"** or **"Create Index"**
2. The index will show status: **"Creating"**
3. **Wait 2-5 minutes** for the index to build
4. Status will change to **"Ready"**

### Step 4: Verify Index Creation

- The index should appear in the list
- Name will be something like: `C~queues~machine_id~acked~created_at`
- Status: **"Ready"**

## Visual Guide

```
Firestore Console → Indexes
├── Create Index
│   ├── Collection ID: queues
│   ├── Fields:
│   │   ├── machine_id (Ascending)
│   │   ├── acked (Ascending)
│   │   └── created_at (Ascending)
│   └── Create
```

## Alternative: Automatic Index Creation

If you forget to create the index manually, Firestore will automatically suggest creating it when the orchestrator tries to run queries. However, it's better to create it proactively to avoid query failures during deployment.

## Troubleshooting

### Index Creation Fails
- **Error**: "Index already exists"
  - Solution: The index may have been created automatically. Check the indexes list.

- **Error**: "Invalid field path"
  - Solution: Make sure field names match exactly: `machine_id`, `acked`, `created_at`

### Index Taking Too Long
- **Time**: Index creation typically takes 2-5 minutes
- **If stuck**: Refresh the page or check back later

### Index Not Working
- **Check**: Make sure all three fields are indexed in the correct order
- **Verify**: Field names match the document structure exactly

## What the Index Does

This composite index allows the orchestrator to efficiently:

1. **Filter by machine_id**: Find messages for specific clinics
2. **Filter by acked**: Only get unacknowledged messages
3. **Order by created_at**: Process messages in chronological order
4. **Limit results**: Get batches of messages efficiently

Without this index, the orchestrator would be slow and potentially fail under load.

## Next Steps

After creating the index:

1. ✅ Run the infrastructure setup script
2. ✅ Deploy Cloud Run
3. ✅ Set up Gmail watch
4. ✅ Test with forwarded emails

The index creation is a one-time setup and will be used by all future orchestrator deployments.


















