Engenharia Backend com Node.js e TypeScript: o Guia Definitivo para 2026

graph TB
    Client[Client Applications] --> LB[Load Balancer]
    LB --> API1[API Instance 1]
    LB --> API2[API Instance 2]
    LB --> API3[API Instance N]
    
    API1 --> Auth[Auth Service]
    API1 --> Cache[Redis Cache]
    API1 --> Queue[Job Queue]
    API1 --> DB[(PostgreSQL)]
    
    Auth --> AuthDB[(Auth Database)]
    Queue --> Worker1[Background Worker 1]
    Queue --> Worker2[Background Worker N]
    
    API1 --> External[External APIs]
    API1 --> Storage[File Storage]
    
    subgraph "Monitoring"
        Logs[Structured Logs]
        Metrics[Metrics Collection]
        Traces[Distributed Tracing]
    end
    
    API1 --> Logs
    API1 --> Metrics
    API1 --> Traces

src/
├── application/          # Use cases e business logic
│   ├── services/
│   ├── use-cases/
│   └── interfaces/
├── domain/              # Entidades e regras de negócio
│   ├── entities/
│   ├── value-objects/
│   └── repositories/
├── infrastructure/      # Implementações concretas
│   ├── database/
│   ├── http/
│   ├── cache/
│   └── external-apis/
├── presentation/        # Controllers e middlewares
│   ├── controllers/
│   ├── middlewares/
│   └── validators/
└── shared/             # Utilities e tipos compartilhados
    ├── errors/
    ├── types/
    └── utils/

// src/infrastructure/config/index.ts
import { z } from 'zod'
 
const configSchema = z.object({
  NODE_ENV: z.enum(['development', 'staging', 'production']).default('development'),
  PORT: z.coerce.number().default(3000),
  
  // Database
  DATABASE_URL: z.string().url(),
  DATABASE_POOL_MIN: z.coerce.number().default(2),
  DATABASE_POOL_MAX: z.coerce.number().default(10),
  
  // Redis
  REDIS_URL: z.string().url(),
  REDIS_MAX_RETRIES: z.coerce.number().default(3),
  
  // Auth
  JWT_SECRET: z.string().min(32),
  JWT_EXPIRES_IN: z.string().default('24h'),
  
  // External APIs
  OPENAI_API_KEY: z.string().optional(),
  WEBHOOK_SECRET: z.string(),
  
  // Monitoring
  LOG_LEVEL: z.enum(['error', 'warn', 'info', 'debug']).default('info'),
  SENTRY_DSN: z.string().url().optional(),
})
 
type Config = z.infer<typeof configSchema>
 
class ConfigManager {
  private static instance: Config
  
  static get(): Config {
    if (!this.instance) {
      const result = configSchema.safeParse(process.env)
      
      if (!result.success) {
        console.error('Invalid configuration:', result.error.format())
        process.exit(1)
      }
      
      this.instance = result.data
    }
    
    return this.instance
  }
  
  static isDevelopment(): boolean {
    return this.get().NODE_ENV === 'development'
  }
  
  static isProduction(): boolean {
    return this.get().NODE_ENV === 'production'
  }
}
 
export { ConfigManager }

// src/domain/value-objects/identifiers.ts
declare const __brand: unique symbol
 
type Brand<T, TBrand> = T & { [__brand]: TBrand }
 
export type UserId = Brand<string, 'UserId'>
export type PostId = Brand<string, 'PostId'>
export type SessionId = Brand<string, 'SessionId'>
 
// Factory functions para criação type-safe
export const UserId = {
  create: (id: string): UserId => {
    if (!id || id.length < 1) {
      throw new Error('Invalid UserId')
    }
    return id as UserId
  },
  
  fromUUID: (uuid: string): UserId => {
    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
    if (!uuidRegex.test(uuid)) {
      throw new Error('Invalid UUID format for UserId')
    }
    return uuid as UserId
  }
}
 
export const PostId = {
  create: (id: string): PostId => {
    if (!id || id.length < 1) {
      throw new Error('Invalid PostId')
    }
    return id as PostId
  }
}

// src/domain/entities/api-response.ts
export type ApiResponse<T> = 
  | { status: 'success'; data: T; timestamp: Date }
  | { status: 'error'; error: string; code: string; timestamp: Date }
  | { status: 'loading'; progress?: number; timestamp: Date }
 
export type ProcessingJob =
  | { status: 'pending'; queuedAt: Date }
  | { status: 'processing'; startedAt: Date; progress: number }
  | { status: 'completed'; completedAt: Date; result: unknown }
  | { status: 'failed'; failedAt: Date; error: string; retryCount: number }
 
// Type guards para working com unions
export const isSuccess = <T>(response: ApiResponse<T>): response is Extract<ApiResponse<T>, { status: 'success' }> => {
  return response.status === 'success'
}
 
export const isError = <T>(response: ApiResponse<T>): response is Extract<ApiResponse<T>, { status: 'error' }> => {
  return response.status === 'error'
}
 
// Usage em controllers
export class PostController {
  async getPost(req: Request, res: Response): Promise<void> {
    const postId = PostId.create(req.params.id)
    const result = await this.postService.getById(postId)
    
    if (isSuccess(result)) {
      // TypeScript sabe que result.data existe
      res.json(result.data)
    } else if (isError(result)) {
      // TypeScript sabe que result.error existe
      res.status(400).json({ error: result.error, code: result.code })
    }
  }
}

// src/application/interfaces/repository.ts
export interface Entity {
  id: string
  createdAt: Date
  updatedAt: Date
}
 
export interface Repository<T extends Entity> {
  findById(id: string): Promise<T | null>
  findMany(criteria: Partial<T>): Promise<T[]>
  create(data: Omit<T, 'id' | 'createdAt' | 'updatedAt'>): Promise<T>
  update(id: string, data: Partial<Omit<T, 'id' | 'createdAt'>>): Promise<T>
  delete(id: string): Promise<void>
}
 
// Implementação concreta
export class PrismaRepository<T extends Entity> implements Repository<T> {
  constructor(
    private readonly model: any, // Prisma model
    private readonly mapper: (raw: any) => T
  ) {}
  
  async findById(id: string): Promise<T | null> {
    const raw = await this.model.findUnique({ where: { id } })
    return raw ? this.mapper(raw) : null
  }
  
  async findMany(criteria: Partial<T>): Promise<T[]> {
    const raw = await this.model.findMany({ where: criteria })
    return raw.map(this.mapper)
  }
  
  // ... outras implementações
}

// src/application/services/auth.service.ts
import jwt from 'jsonwebtoken'
import { randomBytes } from 'crypto'
import { ConfigManager } from '@/infrastructure/config'
 
export interface TokenPayload {
  userId: UserId
  email: string
  roles: string[]
  permissions: string[]
}
 
export interface AuthTokens {
  accessToken: string
  refreshToken: string
  expiresIn: number
}
 
export class AuthService {
  private readonly jwtSecret = ConfigManager.get().JWT_SECRET
  private readonly refreshTokens = new Set<string>() // Em produção: Redis
  
  async generateTokens(payload: TokenPayload): Promise<AuthTokens> {
    const accessToken = jwt.sign(payload, this.jwtSecret, {
      expiresIn: '15m', // Short-lived access token
      issuer: 'vivodecodigo-api',
      audience: 'vivodecodigo-client'
    })
    
    const refreshToken = randomBytes(64).toString('hex')
    
    // Store refresh token (em produção: Redis com TTL)
    this.refreshTokens.add(refreshToken)
    
    return {
      accessToken,
      refreshToken,
      expiresIn: 15 * 60 // 15 minutes
    }
  }
  
  async refreshAccessToken(refreshToken: string): Promise<AuthTokens | null> {
    if (!this.refreshTokens.has(refreshToken)) {
      return null
    }
    
    // Invalidate old refresh token (rotation)
    this.refreshTokens.delete(refreshToken)
    
    // Em produção: buscar user data associada ao refresh token
    const payload: TokenPayload = await this.getUserFromRefreshToken(refreshToken)
    
    return this.generateTokens(payload)
  }
  
  async revokeRefreshToken(refreshToken: string): Promise<void> {
    this.refreshTokens.delete(refreshToken)
  }
  
  verifyAccessToken(token: string): TokenPayload | null {
    try {
      return jwt.verify(token, this.jwtSecret) as TokenPayload
    } catch {
      return null
    }
  }
  
  private async getUserFromRefreshToken(refreshToken: string): Promise<TokenPayload> {
    // Implementação específica para buscar dados do usuário
    // Em produção: query no Redis/Database
    throw new Error('Not implemented')
  }
}

// src/presentation/middlewares/auth.middleware.ts
import { Request, Response, NextFunction } from 'express'
import { AuthService } from '@/application/services/auth.service'
 
export interface AuthenticatedRequest extends Request {
  user: TokenPayload
}
 
export class AuthMiddleware {
  constructor(private readonly authService: AuthService) {}
  
  authenticate() {
    return async (req: Request, res: Response, next: NextFunction) => {
      const authHeader = req.headers.authorization
      
      if (!authHeader?.startsWith('Bearer ')) {
        return res.status(401).json({ error: 'Missing or invalid authorization header' })
      }
      
      const token = authHeader.substring(7)
      const payload = this.authService.verifyAccessToken(token)
      
      if (!payload) {
        return res.status(401).json({ error: 'Invalid or expired token' })
      }
      
      (req as AuthenticatedRequest).user = payload
      next()
    }
  }
  
  requirePermissions(permissions: string[]) {
    return (req: Request, res: Response, next: NextFunction) => {
      const user = (req as AuthenticatedRequest).user
      
      if (!user) {
        return res.status(401).json({ error: 'Authentication required' })
      }
      
      const hasPermission = permissions.every(permission => 
        user.permissions.includes(permission)
      )
      
      if (!hasPermission) {
        return res.status(403).json({ 
          error: 'Insufficient permissions',
          required: permissions,
          current: user.permissions
        })
      }
      
      next()
    }
  }
  
  requireRoles(roles: string[]) {
    return (req: Request, res: Response, next: NextFunction) => {
      const user = (req as AuthenticatedRequest).user
      
      if (!user) {
        return res.status(401).json({ error: 'Authentication required' })
      }
      
      const hasRole = roles.some(role => user.roles.includes(role))
      
      if (!hasRole) {
        return res.status(403).json({ 
          error: 'Insufficient role',
          required: roles,
          current: user.roles
        })
      }
      
      next()
    }
  }
}

import type { PoolConfig } from 'pg'
import prisma from '@/lib/db/prisma'
import { getPgSslConfig } from '@/lib/db/pg-ssl'
 
const connectionString = process.env.DATABASE_URL
if (!connectionString) throw new Error('DATABASE_URL ausente')
 
export const productionPoolOptions = {
  connectionString,
  ssl: getPgSslConfig(connectionString),
  max: 1,
  idleTimeoutMillis: 30_000,
  connectionTimeoutMillis: 10_000,
  statement_timeout: 30_000,
} satisfies PoolConfig
 
export class DatabaseManager {
  static getInstance() { return prisma }
 
  static async healthCheck(): Promise<boolean> {
    try {
      await prisma.$queryRaw`SELECT 1`
      return true
    } catch {
      return false
    }
  }
}

// src/infrastructure/database/transaction-manager.ts
import { PrismaClient, Prisma } from '@prisma/client'
import { DatabaseManager } from './prisma'
import { Logger } from '@/infrastructure/logging/logger'
 
interface TransactionOptions {
  maxRetries?: number
  timeoutMs?: number
  isolationLevel?: Prisma.TransactionIsolationLevel
}
 
const DEFAULT_OPTIONS: Required<TransactionOptions> = {
  maxRetries: 3,
  timeoutMs: 10000,
  isolationLevel: Prisma.TransactionIsolationLevel.ReadCommitted,
}
 
export class TransactionManager {
  private readonly db: PrismaClient
 
  constructor() {
    this.db = DatabaseManager.getInstance()
  }
 
  async execute<T>(
    operation: (tx: Prisma.TransactionClient) => Promise<T>,
    opts?: TransactionOptions
  ): Promise<T> {
    const { maxRetries, timeoutMs, isolationLevel } = {
      ...DEFAULT_OPTIONS,
      ...opts,
    }
 
    let lastError: Error | null = null
 
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        const result = await this.db.$transaction(operation, {
          maxWait: 5000, // tempo máximo esperando connection do pool
          timeout: timeoutMs,
          isolationLevel,
        })
 
        if (attempt > 1) {
          Logger.info('Transaction succeeded after retry', {
            attempt,
            maxRetries,
          })
        }
 
        return result
      } catch (error) {
        lastError = error as Error
 
        const isRetryable =
          error instanceof Prisma.PrismaClientKnownRequestError &&
          ['P2034', 'P2028'].includes(error.code) // deadlock ou timeout
 
        if (!isRetryable || attempt === maxRetries) {
          Logger.error('Transaction failed permanently', lastError, {
            attempt,
            maxRetries,
            errorCode:
              error instanceof Prisma.PrismaClientKnownRequestError
                ? error.code
                : 'UNKNOWN',
          })
          throw lastError
        }
 
        // Backoff exponencial: 100ms, 200ms, 400ms...
        const backoffMs = Math.min(100 * Math.pow(2, attempt - 1), 2000)
        Logger.warn('Transaction retrying after deadlock/timeout', {
          attempt,
          backoffMs,
          errorCode:
            (error as Prisma.PrismaClientKnownRequestError).code,
        })
 
        await new Promise((resolve) => setTimeout(resolve, backoffMs))
      }
    }
 
    throw lastError!
  }
}
 
// Uso prático: transferência de créditos entre usuários
const txManager = new TransactionManager()
 
const result = await txManager.execute(async (tx) => {
  const sender = await tx.user.update({
    where: { id: senderId },
    data: { credits: { decrement: amount } },
  })
 
  if (sender.credits < 0) {
    throw new Error('Insufficient credits') // rollback automático
  }
 
  const receiver = await tx.user.update({
    where: { id: receiverId },
    data: { credits: { increment: amount } },
  })
 
  await tx.transaction.create({
    data: {
      senderId,
      receiverId,
      amount,
      status: 'completed',
    },
  })
 
  return { sender, receiver }
}, { timeoutMs: 5000, isolationLevel: 'Serializable' })

import { AsyncLocalStorage } from 'node:async_hooks'
import { Prisma } from '@prisma/client'
 
const queries = new AsyncLocalStorage<Map<string, number>>()
 
export function withQueryScope<T>(work: () => Promise<T>): Promise<T> {
  return queries.run(new Map(), work)
}
 
export const nPlusOneExtension = Prisma.defineExtension({
  name: 'n-plus-one-diagnostic',
  query: {
    $allModels: {
      async $allOperations({ model, operation, args, query }) {
        const counts = queries.getStore()
        if (counts && ['findUnique', 'findFirst', 'findMany'].includes(operation)) {
          const key = `${model}.${operation}`
          const count = (counts.get(key) ?? 0) + 1
          counts.set(key, count)
          if (count === 5) console.warn(`Revisar repetição de leitura: ${key}`)
        }
        return query(args)
      },
    },
  },
})

import prisma from '@/lib/db/prisma'
import { nPlusOneExtension, withQueryScope } from './prisma-n-plus-one'
 
const db = prisma.$extends(nPlusOneExtension)
 
export function listWithRepeatedReads() {
  return withQueryScope(async () => {
    const posts = await db.post.findMany({
      where: { status: 'PUBLISHED', category_id: { not: null } },
      orderBy: { id: 'asc' },
      take: 10,
      select: { id: true, category_id: true },
    })
    const result = []
    for (const post of posts) {
      const category = await db.category.findUnique({
        where: { id: post.category_id! },
        select: { id: true, name: true },
      })
      result.push({ ...post, category })
    }
    return result
  })
}

export function listWithBatchedReads() {
  return withQueryScope(async () => {
    const posts = await db.post.findMany({
      where: { status: 'PUBLISHED', category_id: { not: null } },
      orderBy: { id: 'asc' },
      take: 10,
      select: { id: true, category_id: true },
    })
    const ids = [...new Set(posts.flatMap(post => post.category_id ? [post.category_id] : []))]
    const categories = ids.length ? await db.category.findMany({
      where: { id: { in: ids } },
      select: { id: true, name: true },
    }) : []
    const byId = new Map(categories.map(category => [category.id, category]))
    return posts.map(post => ({
      ...post,
      category: post.category_id ? byId.get(post.category_id) ?? null : null,
    }))
  })
}

// src/infrastructure/database/repositories/post.repository.ts
import { DatabaseManager } from '../prisma'
import { Post, PostId, UserId } from '@/domain/entities'
 
export class PostRepository {
  private readonly db = DatabaseManager.getInstance()
  
  async findByIdWithAuthor(postId: PostId): Promise<Post | null> {
    // Single query com join otimizado
    const result = await this.db.post.findUnique({
      where: { id: postId },
      include: {
        author: {
          select: { // Apenas campos necessários
            id: true,
            name: true,
            email: true,
            avatar: true
          }
        },
        tags: {
          select: {
            id: true,
            name: true,
            slug: true
          }
        },
        _count: {
          select: {
            comments: true,
            likes: true
          }
        }
      }
    })
    
    return result ? this.mapToEntity(result) : null
  }
  
  async findPopularPosts(limit: number = 10): Promise<Post[]> {
    // Query otimizada com índices apropriados
    const results = await this.db.post.findMany({
      where: {
        publishedAt: { not: null },
        status: 'published'
      },
      orderBy: [
        { viewCount: 'desc' },
        { publishedAt: 'desc' }
      ],
      take: limit,
      include: {
        author: {
          select: { id: true, name: true, avatar: true }
        },
        _count: {
          select: { comments: true, likes: true }
        }
      }
    })
    
    return results.map(this.mapToEntity)
  }
  
  // Bulk operations para performance
  async incrementViewCount(postIds: PostId[]): Promise<void> {
    await this.db.post.updateMany({
      where: {
        id: { in: postIds }
      },
      data: {
        viewCount: { increment: 1 }
      }
    })
  }
  
  private mapToEntity(raw: any): Post {
    // Mapping de Prisma result para domain entity
    return new Post({
      id: PostId.create(raw.id),
      title: raw.title,
      slug: raw.slug,
      content: raw.content,
      authorId: UserId.create(raw.authorId),
      publishedAt: raw.publishedAt,
      createdAt: raw.createdAt,
      updatedAt: raw.updatedAt,
      // ... outros campos
    })
  }
}

// src/infrastructure/rate-limiting/rate-limiter.ts
import Redis from 'ioredis'
import { ConfigManager } from '@/infrastructure/config'
 
export interface RateLimitConfig {
  windowMs: number
  maxRequests: number
  keyGenerator: (req: any) => string
  skipSuccessfulRequests?: boolean
  skipFailedRequests?: boolean
}
 
export interface RateLimitResult {
  allowed: boolean
  remaining: number
  resetTime: Date
  totalRequests: number
}
 
export class RateLimiter {
  private readonly redis: Redis
  
  constructor() {
    this.redis = new Redis(ConfigManager.get().REDIS_URL)
  }
  
  async checkLimit(
    identifier: string, 
    config: RateLimitConfig
  ): Promise<RateLimitResult> {
    const key = `rate_limit:${identifier}`
    const now = Date.now()
    const window = Math.floor(now / config.windowMs)
    const windowKey = `${key}:${window}`
    
    // Sliding window com Redis pipeline para atomicidade
    const pipeline = this.redis.pipeline()
    pipeline.incr(windowKey)
    pipeline.expire(windowKey, Math.ceil(config.windowMs / 1000))
    
    const results = await pipeline.exec()
    const currentRequests = results?.[0]?.[1] as number || 0
    
    const allowed = currentRequests <= config.maxRequests
    const remaining = Math.max(0, config.maxRequests - currentRequests)
    const resetTime = new Date((window + 1) * config.windowMs)
    
    return {
      allowed,
      remaining,
      resetTime,
      totalRequests: currentRequests
    }
  }
  
  // Rate limiting adaptativo baseado em load
  async adaptiveLimit(
    identifier: string,
    baseConfig: RateLimitConfig,
    systemLoad: number // 0-1
  ): Promise<RateLimitResult> {
    const adaptedConfig = {
      ...baseConfig,
      maxRequests: Math.floor(baseConfig.maxRequests * (1 - systemLoad * 0.5))
    }
    
    return this.checkLimit(identifier, adaptedConfig)
  }
}
 
// Middleware Express
export class RateLimitMiddleware {
  constructor(private readonly rateLimiter: RateLimiter) {}
  
  create(config: RateLimitConfig) {
    return async (req: Request, res: Response, next: NextFunction) => {
      const identifier = config.keyGenerator(req)
      const result = await this.rateLimiter.checkLimit(identifier, config)
      
      // Headers padronizados
      res.set({
        'X-RateLimit-Limit': config.maxRequests.toString(),
        'X-RateLimit-Remaining': result.remaining.toString(),
        'X-RateLimit-Reset': result.resetTime.getTime().toString()
      })
      
      if (!result.allowed) {
        return res.status(429).json({
          error: 'Too Many Requests',
          message: `Rate limit exceeded. Try again at ${result.resetTime.toISOString()}`,
          retryAfter: Math.ceil((result.resetTime.getTime() - Date.now()) / 1000)
        })
      }
      
      next()
    }
  }
  
  // Rate limiting por endpoint específico
  createEndpointLimiter(endpoint: string, limits: Record<string, RateLimitConfig>) {
    return async (req: Request, res: Response, next: NextFunction) => {
      const config = limits[endpoint]
      if (!config) return next()
      
      const identifier = `${endpoint}:${config.keyGenerator(req)}`
      const result = await this.rateLimiter.checkLimit(identifier, config)
      
      if (!result.allowed) {
        return res.status(429).json({
          error: 'Endpoint rate limit exceeded',
          endpoint,
          retryAfter: Math.ceil((result.resetTime.getTime() - Date.now()) / 1000)
        })
      }
      
      next()
    }
  }
}

// src/infrastructure/rate-limiting/configs.ts
import { Request } from 'express'
import { RateLimitConfig } from './rate-limiter'
 
// Key generators para diferentes contextos
export const keyGenerators = {
  byIP: (req: Request) => req.ip,
  byUser: (req: Request) => (req as any).user?.id || req.ip,
  byAPIKey: (req: Request) => req.headers['x-api-key'] as string || req.ip,
  composite: (req: Request) => `${req.ip}:${(req as any).user?.id || 'anonymous'}`
}
 
// Configurações por tipo de endpoint
export const rateLimitConfigs: Record<string, RateLimitConfig> = {
  // API pública - mais restritiva
  public: {
    windowMs: 15 * 60 * 1000, // 15 minutos
    maxRequests: 100,
    keyGenerator: keyGenerators.byIP
  },
  
  // Usuários autenticados - mais permissiva
  authenticated: {
    windowMs: 15 * 60 * 1000,
    maxRequests: 1000,
    keyGenerator: keyGenerators.byUser,
    skipSuccessfulRequests: true
  },
  
  // Operações críticas - muito restritiva
  critical: {
    windowMs: 60 * 1000, // 1 minuto
    maxRequests: 5,
    keyGenerator: keyGenerators.byUser
  },
  
  // Upload de arquivos - por tamanho e frequência
  upload: {
    windowMs: 60 * 60 * 1000, // 1 hora
    maxRequests: 50,
    keyGenerator: keyGenerators.byUser
  },
  
  // Webhooks externos - por API key
  webhook: {
    windowMs: 60 * 1000,
    maxRequests: 100,
    keyGenerator: keyGenerators.byAPIKey
  }
}

graph LR
    Client[Client] --> CDN[CDN Cache]
    CDN --> LB[Load Balancer]
    LB --> App[Application]
    App --> L1[L1 Cache<br/>Memory]
    App --> L2[L2 Cache<br/>Redis]
    App --> DB[(Database)]
    
    subgraph "Cache Layers"
        CDN
        L1
        L2
    end
    
    subgraph "Cache Strategies"
        CacheAside[Cache-Aside]
        WriteThrough[Write-Through]
        WriteBack[Write-Back]
    end

// src/infrastructure/cache/cache-manager.ts
import Redis from 'ioredis'
import { LRUCache } from 'lru-cache'
import { ConfigManager } from '@/infrastructure/config'
 
export interface CacheOptions {
  ttl?: number // Time to live em segundos
  tags?: string[] // Para invalidação por tags
  compress?: boolean // Compressão para valores grandes
  serialize?: boolean // Serialização automática
}
 
export interface CacheStats {
  hits: number
  misses: number
  sets: number
  deletes: number
  hitRate: number
}
 
export class CacheManager {
  private readonly redis: Redis
  private readonly l1Cache: LRUCache<string, any>
  private readonly stats: CacheStats
  
  constructor() {
    this.redis = new Redis(ConfigManager.get().REDIS_URL)
    
    // L1 Cache (Memory) para dados hot
    this.l1Cache = new LRUCache({
      max: 1000, // Máximo 1000 items
      ttl: 5 * 60 * 1000, // 5 minutos
      allowStale: false,
      updateAgeOnGet: true
    })
    
    this.stats = {
      hits: 0,
      misses: 0,
      sets: 0,
      deletes: 0,
      hitRate: 0
    }
  }
  
  async get<T>(key: string): Promise<T | null> {
    // Tentar L1 primeiro
    const l1Result = this.l1Cache.get(key)
    if (l1Result !== undefined) {
      this.stats.hits++
      this.updateHitRate()
      return l1Result as T
    }
    
    // Tentar L2 (Redis)
    try {
      const l2Result = await this.redis.get(key)
      if (l2Result !== null) {
        const parsed = JSON.parse(l2Result) as T
        
        // Promover para L1
        this.l1Cache.set(key, parsed)
        
        this.stats.hits++
        this.updateHitRate()
        return parsed
      }
    } catch (error) {
      console.error('Cache L2 error:', error)
    }
    
    this.stats.misses++
    this.updateHitRate()
    return null
  }
  
  async set<T>(key: string, value: T, options: CacheOptions = {}): Promise<void> {
    const serialized = JSON.stringify(value)
    const ttl = options.ttl || 3600 // 1 hora default
    
    // Set em ambos os layers
    this.l1Cache.set(key, value)
    
    try {
      if (options.ttl) {
        await this.redis.setex(key, ttl, serialized)
      } else {
        await this.redis.set(key, serialized)
      }
      
      // Tags para invalidação
      if (options.tags) {
        await this.addToTags(key, options.tags)
      }
      
      this.stats.sets++
    } catch (error) {
      console.error('Cache L2 set error:', error)
    }
  }
  
  async invalidate(key: string): Promise<void> {
    this.l1Cache.delete(key)
    
    try {
      await this.redis.del(key)
      this.stats.deletes++
    } catch (error) {
      console.error('Cache invalidation error:', error)
    }
  }
  
  async invalidateByTag(tag: string): Promise<void> {
    try {
      const keys = await this.redis.smembers(`tag:${tag}`)
      
      if (keys.length > 0) {
        // Invalidar L1
        keys.forEach(key => this.l1Cache.delete(key))
        
        // Invalidar L2
        const pipeline = this.redis.pipeline()
        keys.forEach(key => pipeline.del(key))
        pipeline.del(`tag:${tag}`)
        await pipeline.exec()
        
        this.stats.deletes += keys.length
      }
    } catch (error) {
      console.error('Tag invalidation error:', error)
    }
  }
  
  // Cache-aside pattern helper
  async getOrSet<T>(
    key: string, 
    fetcher: () => Promise<T>, 
    options: CacheOptions = {}
  ): Promise<T> {
    const cached = await this.get<T>(key)
    if (cached !== null) {
      return cached
    }
    
    const fresh = await fetcher()
    await this.set(key, fresh, options)
    return fresh
  }
  
  private async addToTags(key: string, tags: string[]): Promise<void> {
    const pipeline = this.redis.pipeline()
    tags.forEach(tag => {
      pipeline.sadd(`tag:${tag}`, key)
    })
    await pipeline.exec()
  }
  
  private updateHitRate(): void {
    const total = this.stats.hits + this.stats.misses
    this.stats.hitRate = total > 0 ? this.stats.hits / total : 0
  }
  
  getStats(): CacheStats {
    return { ...this.stats }
  }
}

// src/shared/decorators/cache.decorator.ts
import 'reflect-metadata'
import { CacheManager } from '@/infrastructure/cache/cache-manager'
 
const cacheManager = new CacheManager()
 
export function Cacheable(options: {
  ttl?: number
  keyPrefix?: string
  tags?: string[]
}) {
  return function (target: any, propertyName: string, descriptor: PropertyDescriptor) {
    const method = descriptor.value
    
    descriptor.value = async function (...args: any[]) {
      const keyPrefix = options.keyPrefix || `${target.constructor.name}.${propertyName}`
      const argsKey = JSON.stringify(args)
      const cacheKey = `${keyPrefix}:${argsKey}`
      
      return cacheManager.getOrSet(
        cacheKey,
        () => method.apply(this, args),
        options
      )
    }
    
    return descriptor
  }
}
 
export function CacheInvalidate(tags: string[]) {
  return function (target: any, propertyName: string, descriptor: PropertyDescriptor) {
    const method = descriptor.value
    
    descriptor.value = async function (...args: any[]) {
      const result = await method.apply(this, args)
      
      // Invalidar após operação bem-sucedida
      for (const tag of tags) {
        await cacheManager.invalidateByTag(tag)
      }
      
      return result
    }
    
    return descriptor
  }
}
 
// Usage
export class PostService {
  @Cacheable({ 
    ttl: 300, // 5 minutos
    keyPrefix: 'post',
    tags: ['posts', 'content']
  })
  async getPopularPosts(): Promise<Post[]> {
    return this.postRepository.findPopularPosts()
  }
  
  @CacheInvalidate(['posts', 'content'])
  async createPost(data: CreatePostData): Promise<Post> {
    return this.postRepository.create(data)
  }
}

// src/infrastructure/websocket/websocket-manager.ts
import { Server as HttpServer } from 'http'
import { Server as SocketServer, Socket } from 'socket.io'
import { Redis } from 'ioredis'
import { createAdapter } from '@socket.io/redis-adapter'
 
export interface WebSocketMessage {
  type: string
  payload: any
  timestamp: Date
  userId?: string
  room?: string
}
 
export class WebSocketManager {
  private io: SocketServer
  private redis: Redis
  private connectedUsers = new Map<string, Socket>()
  
  constructor(httpServer: HttpServer) {
    this.redis = new Redis(process.env.REDIS_URL!)
    
    this.io = new SocketServer(httpServer, {
      cors: {
        origin: process.env.FRONTEND_URL,
        methods: ['GET', 'POST']
      },
      // Connection pooling para WebSockets
      transports: ['websocket', 'polling'],
      pingTimeout: 60000,
      pingInterval: 25000
    })
    
    // Redis adapter para clustering
    const pubClient = new Redis(process.env.REDIS_URL!)
    const subClient = pubClient.duplicate()
    this.io.adapter(createAdapter(pubClient, subClient))
    
    this.setupEventHandlers()
  }
  
  private setupEventHandlers(): void {
    this.io.use(this.authMiddleware.bind(this))
    
    this.io.on('connection', (socket: Socket) => {
      const userId = socket.data.userId
      this.connectedUsers.set(userId, socket)
      
      console.log(`User ${userId} connected`)
      
      // Join user-specific room
      socket.join(`user:${userId}`)
      
      // Handle custom events
      socket.on('join_room', (roomId: string) => {
        socket.join(roomId)
        socket.to(roomId).emit('user_joined', { userId, timestamp: new Date() })
      })
      
      socket.on('leave_room', (roomId: string) => {
        socket.leave(roomId)
        socket.to(roomId).emit('user_left', { userId, timestamp: new Date() })
      })
      
      // Handle messages
      socket.on('message', async (data: WebSocketMessage) => {
        await this.handleMessage(socket, data)
      })
      
      // Cleanup on disconnect
      socket.on('disconnect', (reason) => {
        this.connectedUsers.delete(userId)
        console.log(`User ${userId} disconnected: ${reason}`)
      })
    })
  }
  
  private async authMiddleware(socket: Socket, next: (err?: Error) => void): Promise<void> {
    try {
      const token = socket.handshake.auth.token
      const payload = await this.verifyToken(token)
      
      socket.data.userId = payload.userId
      socket.data.permissions = payload.permissions
      
      next()
    } catch (error) {
      next(new Error('Authentication failed'))
    }
  }
  
  private async handleMessage(socket: Socket, message: WebSocketMessage): Promise<void> {
    // Rate limiting por usuário
    const rateLimitKey = `ws_rate_limit:${socket.data.userId}`
    const currentCount = await this.redis.incr(rateLimitKey)
    
    if (currentCount === 1) {
      await this.redis.expire(rateLimitKey, 60) // 1 minuto
    }
    
    if (currentCount > 100) { // 100 mensagens por minuto
      socket.emit('error', { message: 'Rate limit exceeded' })
      return
    }
    
    // Process message based on type
    switch (message.type) {
      case 'chat_message':
        await this.handleChatMessage(socket, message)
        break
      case 'typing_indicator':
        await this.handleTypingIndicator(socket, message)
        break
      default:
        socket.emit('error', { message: 'Unknown message type' })
    }
  }
  
  // Public methods para enviar mensagens
  async sendToUser(userId: string, message: WebSocketMessage): Promise<void> {
    this.io.to(`user:${userId}`).emit('message', message)
  }
  
  async sendToRoom(roomId: string, message: WebSocketMessage): Promise<void> {
    this.io.to(roomId).emit('message', message)
  }
  
  async broadcast(message: WebSocketMessage): Promise<void> {
    this.io.emit('message', message)
  }
  
  getConnectedUsersCount(): number {
    return this.connectedUsers.size
  }
  
  isUserConnected(userId: string): boolean {
    return this.connectedUsers.has(userId)
  }
}

// src/infrastructure/sse/sse-manager.ts
import { Request, Response } from 'express'
import { EventEmitter } from 'events'
 
export interface SSEClient {
  id: string
  userId: string
  response: Response
  lastEventId?: string
}
 
export interface SSEEvent {
  id?: string
  event?: string
  data: any
  retry?: number
}
 
export class SSEManager extends EventEmitter {
  private clients = new Map<string, SSEClient>()
  private eventHistory = new Map<string, SSEEvent[]>() // Para replay
  
  createConnection(req: Request, res: Response, userId: string): void {
    const clientId = `${userId}_${Date.now()}`
    
    // SSE headers
    res.writeHead(200, {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive',
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Headers': 'Cache-Control'
    })
    
    // Keep-alive ping
    const pingInterval = setInterval(() => {
      res.write(': ping\n\n')
    }, 30000)
    
    // Store client
    const client: SSEClient = {
      id: clientId,
      userId,
      response: res,
      lastEventId: req.headers['last-event-id'] as string
    }
    
    this.clients.set(clientId, client)
    
    // Replay missed events se necessário
    if (client.lastEventId) {
      this.replayEvents(client)
    }
    
    // Send initial connection event
    this.sendToClient(client, {
      event: 'connected',
      data: { clientId, timestamp: new Date() }
    })
    
    // Cleanup on disconnect
    req.on('close', () => {
      clearInterval(pingInterval)
      this.clients.delete(clientId)
      this.emit('client_disconnected', { clientId, userId })
    })
    
    this.emit('client_connected', { clientId, userId })
  }
  
  sendToUser(userId: string, event: SSEEvent): void {
    const userClients = Array.from(this.clients.values())
      .filter(client => client.userId === userId)
    
    userClients.forEach(client => {
      this.sendToClient(client, event)
    })
    
    // Store for replay
    this.storeEvent(userId, event)
  }
  
  broadcast(event: SSEEvent): void {
    this.clients.forEach(client => {
      this.sendToClient(client, event)
    })
    
    // Store for all users (pode ser otimizado)
    this.clients.forEach(client => {
      this.storeEvent(client.userId, event)
    })
  }
  
  private sendToClient(client: SSEClient, event: SSEEvent): void {
    try {
      let message = ''
      
      if (event.id) {
        message += `id: ${event.id}\n`
      }
      
      if (event.event) {
        message += `event: ${event.event}\n`
      }
      
      if (event.retry) {
        message += `retry: ${event.retry}\n`
      }
      
      message += `data: ${JSON.stringify(event.data)}\n\n`
      
      client.response.write(message)
    } catch (error) {
      console.error('Error sending SSE event:', error)
      this.clients.delete(client.id)
    }
  }
  
  private storeEvent(userId: string, event: SSEEvent): void {
    if (!this.eventHistory.has(userId)) {
      this.eventHistory.set(userId, [])
    }
    
    const events = this.eventHistory.get(userId)!
    events.push({ ...event, id: event.id || Date.now().toString() })
    
    // Keep only last 100 events
    if (events.length > 100) {
      events.shift()
    }
  }
  
  private replayEvents(client: SSEClient): void {
    const events = this.eventHistory.get(client.userId) || []
    const lastEventIndex = events.findIndex(event => event.id === client.lastEventId)
    
    if (lastEventIndex !== -1) {
      const missedEvents = events.slice(lastEventIndex + 1)
      missedEvents.forEach(event => {
        this.sendToClient(client, event)
      })
    }
  }
  
  getConnectedClientsCount(): number {
    return this.clients.size
  }
  
  getUserConnectionsCount(userId: string): number {
    return Array.from(this.clients.values())
      .filter(client => client.userId === userId).length
  }
}