# 🔄 PLANNER COMMUNICATION - QUICK REFERENCE

**Status:** ✅ ALL SYNCHRONIZED  
**TypeScript:** ✅ PASS (0 errors)  

---

## 📡 Communication Layers

### Layer 1: Frontend (Vue 3)
```typescript
// plannerStore.ts - Request data
async createPlan(dto: CreatePlanDTO) {
  const newPlan = await plannerService.createPlan(dto)
}

// What it sends:
CreatePlanDTO = {
  name: string ✅
  description?: string
  isPublic?: boolean
  settings?: RouteSettings
}

// What it receives:
Plan = {
  id, userId, name, description, stages,
  settings, isPublic, createdAt, updatedAt
}
```

### Layer 2: API (Fastify + Zod)
```typescript
// Routes - Validate & Route
fastify.post('/plans', {
  preHandler: validateRequest(createPlanSchema),
  handler: controller.createPlan()
})

// Zod Schema validates exactly what frontend sends:
createPlanSchema = {
  name: string (min 1, max 200) ✅
  description: string (max 2000) ✅ optional
  isPublic: boolean ✅ default false
  settings: routeSettings ✅ optional
}

// Then returns full object:
Plan (complete with all fields)
```

### Layer 3: Backend (Service)
```typescript
// Service - Create full object
async createPlan(userId, dto): Promise<Plan> {
  return {
    id: uuid(),
    userId,
    name: dto.name ✅
    description: dto.description,
    stages: [],
    settings: dto.settings,
    isPublic: dto.isPublic ?? false,
    createdAt: new Date(),
    updatedAt: new Date()
  }
}
```

---

## ✅ Key Verification Points

### Property Names
```typescript
✅ plan.name       (NOT plan.title)
✅ stage.name      (NOT stage.title)
✅ stage.notes     (NOT stage.description)
✅ stage.location.address  (NOT stage.address)
```

### Request/Response Flow
```typescript
Frontend (sends DTO)
   ↓
API (validates with Zod)
   ↓
Backend (creates full object)
   ↓
Frontend (receives full object)
```

### Type Imports
```typescript
// ✅ CORRECT (everywhere)
import { Plan, Stage, CreatePlanDTO } from '@my-roadtrip/types'

// ❌ WRONG (don't use)
import { Plan } from '@my-road-trip/types'  // Note the dash!
```

---

## 📋 All Endpoints (Verified)

| Endpoint | Method | Auth | In | Out | Working |
|----------|--------|------|----|----|---------|
| /plans | GET | Yes | - | Plan[] | ✅ |
| /plans/:id | GET | Yes | - | Plan | ✅ |
| /plans | POST | Yes | CreatePlanDTO | Plan | ✅ |
| /plans/:id | PATCH | Yes | UpdatePlanDTO | Plan | ✅ |
| /plans/:id | DELETE | Yes | - | - | ✅ |
| /plans/:id/stages | POST | Yes | CreateStageDTO | Stage | ✅ |
| /stages/:id | PATCH | Yes | UpdateStageDTO | Stage | ✅ |
| /stages/:id | DELETE | Yes | - | - | ✅ |

---

## 🔄 Example: Create Plan

### Step 1: Frontend Sends
```typescript
// User clicks "Create Plan"
const dto: CreatePlanDTO = {
  name: 'Road Trip USA',
  description: 'Coast to coast',
  isPublic: false
}

// Service calls API
POST /api/planner/plans
Body: dto
```

### Step 2: API Validates
```typescript
// Zod schema checks:
✅ name is string (min 1, max 200)
✅ description is string (max 2000)
✅ isPublic is boolean
✅ All fields present or optional

// If valid: continue
// If invalid: return 400 error
```

### Step 3: Backend Creates
```typescript
// Service receives validated DTO
const plan: Plan = {
  id: 'plan-123',
  userId: 'user-456',
  name: dto.name ✅
  description: dto.description,
  stages: [],
  settings: undefined,
  isPublic: false,
  createdAt: new Date(),
  updatedAt: new Date()
}

// Repository saves to Firestore
```

### Step 4: Frontend Receives
```typescript
// Response (Plan object):
{
  id: 'plan-123',
  userId: 'user-456',
  name: 'Road Trip USA' ✅
  description: 'Coast to coast',
  stages: [],
  isPublic: false,
  createdAt: Date,
  updatedAt: Date
}

// Store updates
plans.value.push(newPlan)
```

---

## 🛡️ Type Safety (All Verified)

| Layer | Validation | Status |
|-------|-----------|--------|
| Frontend | TypeScript types | ✅ PASS |
| API | Zod schemas | ✅ PASS |
| Backend | TypeScript types | ✅ PASS |
| Database | Document structure | ✅ PASS |

---

## ❌ Common Mistakes (All Fixed)

```typescript
❌ plan.title           → ✅ plan.name
❌ stage.description    → ✅ stage.notes
❌ stage.address        → ✅ stage.location.address
❌ @my-road-trip/types  → ✅ @my-roadtrip/types
❌ SendingFullPlan      → ✅ Sending CreatePlanDTO then receiving Plan
```

---

## 🎯 Verification Summary

**Frontend:** ✅ Sends correct DTOs, receives full objects  
**API:** ✅ Validates with Zod, converts to full objects  
**Backend:** ✅ Creates and stores complete objects  
**Types:** ✅ Single source of truth in shared package  
**Communication:** ✅ All layers in sync  

---

## 📚 Detailed Documentation

See `PLANNER_COMMUNICATION_AUDIT.md` for complete analysis:
- Full type definitions
- Request/response examples
- Data flow diagrams
- Endpoint verification table
- Security checks

---

**Status: READY FOR PRODUCTION** ✅
