frontend-layer-infrastructure
Use this skill to design and implement robust frontend infrastructure and data layers, abstracting type-safe API clients, enforcing Anti-Corruption Layer (ACL) DTO mappers, resolving 401 refresh token
SKILL.mdskills/frontend-engineering/product-frontend-clean-architecture-development/subskills/frontend-layer-infrastructure/SKILL.md
GitHubFrontend Infrastructure & Data Layer Architecture
Bu alt uzmanlık yeteneği; Clean Architecture'ın Altyapı ve Veri Katmanı (Infrastructure / Data Layer) prensiplerini, dış dünya entegrasyonlarını, tip güvenli API istemcilerini, Anti-Corruption Layer (ACL) DTO haritalayıcılarını, TanStack Query v5 önbellek yaşam döngüsünü ve güvenli depolama adaptörlerini yönetir.
- Ana Orkestratör Referansı: product-frontend-clean-architecture-development
- Detaylı Sektör Araştırma Raporu: infrastructure_layer_architecture_deep_research.md
🚫 1. Katı Mimari Kurallar ve Kısıtlamalar (Enforced Guardrails)
- Sıfır DTO Sızıntısı (Strict Anti-Corruption Layer):
- Backend'den dönen ham JSON yanıtları (
snake_casealanlar, ilişkisel yabancı anahtarlar) doğrudan Presentation veya Domain katmanına verilemez. Her DTO, Altyapı katmanındaki bir Data Mapper ile Domain Entity'sine çevrilmelidir.
- Backend'den dönen ham JSON yanıtları (
- Repository Soyutlaması & Doğrudan İstemci Çağrısı Yasağı:
- UI bileşenleri ham
fetchveya Axios instance'ı çağıramaz. Tüm veri erişimleriOrderRepository,UserRepositorygibi sözleşmeler (Ports) üzerinden yürütülmelidir.
- UI bileşenleri ham
- Tek Uçuşlu (Single-Flight) 401 Token Yenileme Koruması:
- Paralel giden istekler aynı anda
401 Unauthorizedaldığında birden fazla refresh isteği fırlatılamaz. Tek birrefreshPromisememoize edilmeli ve diğer istekler bu vaadi beklemelidir.
- Paralel giden istekler aynı anda
- TanStack Query v5 Katman İzolasyonu:
- Domain ve Altyapı katmanlarında hiçbir React Query hook'u (
useQuery,useMutation) bulunamaz. TanStack Query yalnızca Presentation Adapters (queryOptions) ve UI hook'larında yer alır.
- Domain ve Altyapı katmanlarında hiçbir React Query hook'u (
- Geri Alma Garantili (Rollback) Optimistic UI:
- Anlık UI güncellemelerinde (beğeni, sepet artırımı),
onMutateaşamasında önbellek snapshot'ı alınmalı veonErrordurumunda deterministik olarak geri yüklenmelidir.
- Anlık UI güncellemelerinde (beğeni, sepet artırımı),
- Web ve Mobil Güvenli Depolama Standartları:
- Web tarafında hassas JWT/Refresh token'lar
localStorage'da ASLA saklanamaz (XSS riski); BFF mimarisi veHttpOnly; Secure; SameSite=Strictçerezleri zorunludur. - Mobil/Expo tarafında
AsyncStorageyerine donanımsalexpo-secure-storeve şifrelireact-native-mmkvhibrit modeli kullanılmalıdır.
- Web tarafında hassas JWT/Refresh token'lar
🏛️ 2. Temel Mimari Yapı Taşları ve Kod Şablonları
A. Anti-Corruption Layer (ACL) Çift Yönlü Haritalama (toDomain & toDTO)
// infrastructure/mappers/userMapper.ts
import { z } from 'zod';
import { UserProfile } from '../../domain/models/user';
import { UserId } from '../../domain/shared/brand';
export const UserDtoSchema = z.object({
user_id: z.string().uuid(),
first_name: z.string(),
last_name: z.string(),
is_active: z.union([z.literal(1), z.literal(0)]),
registered_timestamp: z.number(),
});
export type UserDto = z.infer<typeof UserDtoSchema>;
export class UserMapper {
public static toDomain(raw: unknown): UserProfile {
const dto = UserDtoSchema.parse(raw); // "Parse, Don't Validate"
return {
id: dto.user_id as UserId,
fullName: `${dto.first_name} ${dto.last_name}`.trim(),
isActive: dto.is_active === 1,
registeredAt: new Date(dto.registered_timestamp * 1000),
};
}
public static toDTO(domain: UserProfile): Record<string, unknown> {
const [firstName, ...rest] = domain.fullName.split(' ');
return {
user_id: domain.id,
first_name: firstName,
last_name: rest.join(' '),
is_active: domain.isActive ? 1 : 0,
};
}
}
B. Single-Flight Token Manager & Yetkili Fetch Adaptörü
// infrastructure/http/tokenManager.ts
export class TokenManager {
private static refreshPromise: Promise<string> | null = null;
public static async getValidToken(
refreshTokenFn: () => Promise<string | null>,
saveTokensFn: (tokens: { accessToken: string }) => Promise<void>
): Promise<string> {
if (this.refreshPromise) {
return this.refreshPromise; // Devam eden tekil isteğe abone ol
}
this.refreshPromise = (async () => {
try {
const refreshToken = await refreshTokenFn();
if (!refreshToken) throw new Error('Refresh token bulunamadı');
const res = await fetch('https://api.example.com/v1/auth/refresh', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ refreshToken }),
});
if (!res.ok) throw new Error('Oturum süresi doldu');
const data = await res.json();
await saveTokensFn(data);
return data.accessToken;
} finally {
this.refreshPromise = null; // Kilidi serbest bırak
}
})();
return this.refreshPromise;
}
}
C. TanStack Query v5: Query Key Factory & queryOptions
// presentation/adapters/queries/todoQueries.ts
import { queryOptions } from '@tanstack/react-query';
import { TodoRepository } from '../../../infrastructure/repositories/todoRepository';
export const todoKeys = {
all: ['todos'] as const,
lists: () => [...todoKeys.all, 'list'] as const,
list: (filter: string) => [...todoKeys.lists(), { filter }] as const,
details: () => [...todoKeys.all, 'detail'] as const,
detail: (id: string) => [...todoKeys.details(), id] as const,
};
export const todoQueries = {
list: (filter = 'all', repo: TodoRepository) =>
queryOptions({
queryKey: todoKeys.list(filter),
queryFn: ({ signal }) => repo.getTodos(filter, signal),
staleTime: 1000 * 60 * 2, // 2 dakika taze
}),
detail: (id: string, repo: TodoRepository) =>
queryOptions({
queryKey: todoKeys.detail(id),
queryFn: ({ signal }) => repo.getTodoById(id, signal),
staleTime: 1000 * 60 * 5,
enabled: Boolean(id),
}),
};
D. Rollback Garantili Optimistic Update Mutasyonu
// presentation/hooks/useToggleTodo.ts
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { todoKeys } from '../adapters/queries/todoQueries';
import { Todo } from '../../domain/models/todo';
export function useToggleTodo(todoRepo: TodoRepository) {
const queryClient = useQueryClient();
return useMutation({
mutationFn: (todo: Todo) => todoRepo.toggleTodo(todo.id, !todo.completed),
onMutate: async (todo) => {
// 1. İlgili sorguların devam eden fetch işlemlerini iptal et
await queryClient.cancelQueries({ queryKey: todoKeys.all });
// 2. Rollback için snapshot al
const previousTodos = queryClient.getQueryData<Todo[]>(todoKeys.list('all'));
// 3. İyimser güncelleme yap
queryClient.setQueryData<Todo[]>(todoKeys.list('all'), (old = []) =>
old.map((t) => (t.id === todo.id ? { ...t, completed: !t.completed } : t))
);
return { previousTodos };
},
onError: (_err, _todo, context) => {
// 4. Hata durumunda snapshot'ı geri yükle (Rollback)
if (context?.previousTodos) {
queryClient.setQueryData(todoKeys.list('all'), context.previousTodos);
}
},
onSettled: () => {
// 5. Sunucuyla son durumu eşitle
queryClient.invalidateQueries({ queryKey: todoKeys.all });
},
});
}
E. Mobil (React Native / Expo) Hibrit Güvenli Depolama Mimarisi
// infrastructure/storage/secureMmkvStorage.ts
import * as SecureStore from 'expo-secure-store';
import { MMKV } from 'react-native-mmkv';
import * as Crypto from 'expo-crypto';
const MMKV_KEY_ALIAS = 'app_mmkv_encryption_key';
let storageInstance: MMKV | null = null;
export async function getSecureStorage(): Promise<MMKV> {
if (storageInstance) return storageInstance;
let encryptionKey = await SecureStore.getItemAsync(MMKV_KEY_ALIAS);
if (!encryptionKey) {
const randomBytes = await Crypto.getRandomBytesAsync(32);
encryptionKey = Array.from(randomBytes).map((b) => b.toString(16).padStart(2, '0')).join('');
await SecureStore.setItemAsync(MMKV_KEY_ALIAS, encryptionKey, {
keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
});
}
storageInstance = new MMKV({
id: 'secure-app-cache',
encryptionKey,
});
return storageInstance;
}
⚠️ 3. Kaçınılması Gereken Anti-Pattern'lar
| Anti-Pattern | Neden Zararlı? | Doğru Kurumsal Yaklaşım |
|---|---|---|
| DTO Sızıntısı (Leaky DTOs) | Backend bir alanı değiştirdiğinde 40 UI bileşeni kırılır. | ACL Data Mapper sınıfı ile DTO'yu saf Domain Entity'sine çevirin. |
useApi<T> Jenerik Tuzağı |
TanStack Query'nin select, staleTime, queryFn ve tip çıkarımını baltalar. |
Hiyerarşik queryOptions ve Query Key Factory kullanın. |
localStorage'da JWT Tutulması |
XSS veya 3. parti scriptler ile token'lar tek satırda çalınabilir. | Web'de BFF HttpOnly çerezleri; mobilde expo-secure-store kullanın. |
| Paralel 401 Fırtınası | 5 paralel istek aynı anda refresh atarak oturum iptaline yol açar. | Single-Flight Promise Memoization ile tek bir yenileme isteği işletin. |
| Rollback'siz Optimistic UI | Ağ hatasında ekran yanlış durumu göstermeye devam eder. | onMutate (snapshot) ve onError (rollback) ikilisini zorunlu kılın. |
📋 4. Doğrulama ve Kabul Kriterleri (Checklist)
- Hiçbir UI bileşeninde ham DTO veya snake_case alan kullanılmıyor; tüm veriler Mapper'dan geçiyor.
- UI bileşenleri doğrudan
fetchveya Axios çağırmıyor; Repository arayüzleri tüketiliyor. - 401 durumunda paralel isteklerin hepsi tek bir refresh promise'ine bağlanıyor.
- TanStack Query sorguları
queryOptionsve hiyerarşik Query Key Factory ile tanımlanmış. - Optimistic update yapılan tüm mutasyonlarda hata durumunda snapshot geri yükleme (rollback) mevcut.
- Web tarafında
localStorageiçinde oturum token'ı bulunmuyor (BFF HttpOnly çerezi aktif). - Mobil/Expo tarafında
AsyncStoragekullanılmıyor; donanımsal Keychain/Keystore ve AES şifreli MMKV kullanılıyor.