---
name: backend-frontend-sync
description: Backend-Frontend senkronizasyonu. API değişikliklerinde kullan. Type sync, API contract doğrulama, WebSocket event handling.
---

# Backend-Frontend Sync

## Senkronizasyon Noktaları

```
Backend (Express/TypeORM)         Frontend (Next.js/React)
-------------------------         ------------------------
entities/*.ts             <--->   @boilerplate/types
services/*.ts             <--->   lib/api/*.ts
controllers/*.ts          <--->   hooks/use-*.ts
WebSocket events          <--->   realtime hooks
Error responses           <--->   Error handling
```

## 1. Type Senkronizasyonu

### Kural: Tek Kaynak (Single Source of Truth)

TÜM tipler `@boilerplate/types` paketinde tanımlanmalı. Backend ve frontend aynı tipi import eder.

### Tip Eşleme Kuralları

| Backend (TypeScript) | Frontend (TypeScript) | Shared Types                  |
| -------------------- | --------------------- | ----------------------------- |
| Entity class         | Interface             | `@boilerplate/types`          |
| Service response     | API response type     | `@boilerplate/types/api`      |
| Auth payload         | Auth context          | `@boilerplate/types/auth`     |
| WebSocket event      | Realtime event        | `@boilerplate/types/realtime` |

### Yeni Tip Ekleme Adımları

1. `packages/shared/types/src/` altında tip tanımla
2. `index.ts`'den export et
3. `package.json`'a export path ekle (yeni modülse)
4. `pnpm --filter @boilerplate/types build`
5. Backend ve frontend'de import et

## 2. API Client Pattern

### Service Katmanı

Frontend'de her backend endpoint'i için service fonksiyonu oluştur:

- GET → `fetchX()`, `listX()`
- POST → `createX()`
- PUT/PATCH → `updateX()`
- DELETE → `deleteX()`

### Error Handling

Backend error response'u frontend'de sanitize edilmeli:

- Status code'a göre kullanıcı mesajı
- `requestId` support referansı için sakla
- Validation error'ları field bazlı göster

## 3. WebSocket / Realtime Events

### Event Format

```typescript
interface RealtimeEvent {
  channel: string; // "projects" | "users" | ...
  action: string; // "created" | "updated" | "deleted"
  payload: unknown; // Event data
  timestamp: string; // ISO timestamp
}
```

### CRUD Sonrası Broadcast (ZORUNLU)

Backend'de CRUD işlemi sonrası:

1. DB işlemi
2. Cache invalidate
3. WebSocket broadcast

### Yeni Kanal Ekleme

| Adım | Backend                                           | Frontend                                       |
| ---- | ------------------------------------------------- | ---------------------------------------------- |
| 1    | `@boilerplate/types/realtime` → Channel type ekle | -                                              |
| 2    | CRUD endpoint'e broadcast ekle                    | -                                              |
| 3    | -                                                 | `hooks/use-realtime-<channel>.ts` hook oluştur |
| 4    | -                                                 | Provider'da hook'u çağır                       |

## 4. API Değişiklik Checklist

Backend'de API değişikliği yapıldığında:

### Backend Tarafında

- [ ] Entity/Model güncellendi
- [ ] Service güncellendi
- [ ] Controller güncellendi
- [ ] Route güncellendi (gerekiyorsa)
- [ ] Validation schema güncellendi
- [ ] Unit test yazıldı

### Shared Types Tarafında

- [ ] `@boilerplate/types` güncellendi
- [ ] Export kontrol edildi
- [ ] Build yapıldı

### Frontend Tarafında

- [ ] API service güncellendi
- [ ] Hook güncellendi
- [ ] Component güncellendi
- [ ] Realtime hook eklendi (WS broadcast varsa)
- [ ] Test yazıldı

### Doğrulama

- [ ] `pnpm build` başarılı
- [ ] `pnpm typecheck` başarılı
- [ ] Backend unit test geçti
- [ ] Frontend unit test geçti
- [ ] curl E2E test yapıldı
- [ ] Playwright E2E test yapıldı (UI değiştiyse)

## 5. Anti-Patterns

| YAPMA                             | YAP                       | Sebep              |
| --------------------------------- | ------------------------- | ------------------ |
| Frontend'de local type tanımla    | @boilerplate/types kullan | Type sync          |
| `any` type                        | `unknown` veya somut type | Type safety        |
| Hardcoded API URL                 | Environment variable      | Deploy flexibility |
| Duplicate type definition         | Tek kaynak                | Sync kolaylığı     |
| Backend değiştir, frontend'i unut | Checklist takip et        | Breaking change    |

## 6. Örnek Sync Senaryosu

**Senaryo:** User entity'ye yeni field ekleniyor.

### Adım 1: Shared Types

```
packages/shared/types/src/user.ts → Field ekle
pnpm --filter @boilerplate/types build
```

### Adım 2: Backend

```
entities/user.entity.ts → Column ekle
services/user.service.ts → Logic ekle (gerekirse)
migration oluştur ve çalıştır
```

### Adım 3: Frontend

```
API service → Yeni field'ı handle et
Component → Yeni field'ı göster
```

### Adım 4: Test

```
Backend: pnpm test
Frontend: pnpm test
E2E: curl + Playwright MCP
```

## 7. Breaking Change Yönetimi

API'de breaking change yapılacaksa:

1. Önce yeni endpoint/field ekle (additive)
2. Frontend'i yeni endpoint'e geçir
3. Eski endpoint'i deprecate et
4. Yeterli süre sonra eski endpoint'i kaldır

**ASLA:** Tek commit'te backend + frontend breaking change