Clean Architecture: Protege tu Runway Técnico

TL;DR:

• La Trampa: Prototipos de agencia que mezclan controladores HTTP, consultas ORM y APIs de pago en un solo archivo colapsan con tráfico real y convierten iteraciones simples en semanas de fricción.
• Flujo de Dependencias Invertidas: Aislar las reglas del negocio detrás de interfaces de dominio puras relega los frameworks web y drivers de bases de datos a adaptadores externos descartables.
• Radio de Impacto Confinado: Delimitar fronteras permite migraciones de base de datos sin caídas, sustitución ágil de proveedores y suites de pruebas en memoria que corren en menos de 5 ms.

La Trampa del Código Espagueti: Por Qué los Equipos se Frenan en Seco

Más del 70% del tiempo de ingeniería en startups estancadas no se dedica a construir nuevas funcionalidades.

Se evapora apagando incendios en código frágil y estrechamente acoplado.

Durante las primeras tres semanas de un MVP, todo parece avanzar a velocidad récord.

Los primeros endpoints construidos a las prisas responden bien para cinco cuentas de prueba, y los fundadores celebran despliegues diarios.

Hacia el sexto mes, la fricción se vuelve crítica: modificar un botón en el carrito rompe la autorización entre organizaciones, un cambio en el esquema de base de datos corrompe registros históricos y publicar un ajuste en los precios toma tres semanas de pruebas en lugar de treinta minutos.

La deuda técnica acumulada congela la velocidad del equipo.

El software pasa de ser la mayor ventaja competitiva de la empresa a convertirse en un lastre financiero insostenible.

Capas Concéntricas: Separar el Dominio de las Herramientas Externas

Clean Architecture no es perfeccionismo académico diseñado para lucir diagramas teóricos.

Es una estrategia de continuidad operativa creada para proteger las reglas centrales del negocio frente a la volatilidad tecnológica exterior.

La arquitectura distribuye el sistema en anillos concéntricos regidos por una regla fundamental: las dependencias siempre apuntan hacia adentro, hacia las reglas de negocio, nunca hacia afuera, hacia las herramientas.

1. Entidades (El Núcleo): Las reglas fundamentales del negocio (cálculo de comisiones, límites de planes, invariantes nutricionales clínicos). Esta capa ignora por completo la existencia de SQL, HTTP o SDKs cloud.
2. Casos de Uso (Aplicación): Operaciones concretas del sistema (ActivarSuscripcion, CancelarOrden). Coordinan entidades y definen contratos de interfaces.
3. Adaptadores de Interfaz: Traductores que transforman peticiones web en objetos de dominio y resultados del dominio en respuestas JSON.
4. Infraestructura (La Periferia): Mecanismos técnicos volátiles como PostgreSQL, Stripe, Redis y Express.

Cuando la pasarela de pagos actualiza su API o el equipo migra de base de datos, el núcleo del dominio permanece intacto.

Vulnerable: El Controlador Express Típicamente Acoplado

// VULNERABLE: Acoplamiento directo de enrutamiento HTTP, parsing no tipado, Stripe y ORM
import { Request, Response } from "express";
import { prisma } from "../lib/prisma";
import Stripe from "stripe";
import { resend } from "../lib/email";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: "2023-10-16" });

export async function handleActivateSubscription(req: Request, res: Response) {
  // 1. Entrada no tipada: vulnerabilidades del payload pasan sin filtro a la logica
  const { tenantId, planTier, paymentToken, seats } = req.body as any;

  // 2. Reglas de negocio dispersas dentro de la capa de transporte
  if (seats < 1 || seats > 500) {
    return res.status(400).json({ error: "Cantidad de asientos invalida" });
  }

  const basePrice = planTier === "ENTERPRISE" ? 120 : 49;
  const totalInCents = seats * basePrice * 100;

  try {
    // 3. Llamada directa a proveedor externo sin abstraccion ni reintentos
    const charge = await stripe.charges.create({
      amount: totalInCents,
      currency: "usd",
      source: paymentToken,
      description: `Suscripcion para organizacion ${tenantId}`,
    });

    // 4. Mutacion en base de datos no atomica.
    // Si Prisma falla aqui, el cobro ocurrio pero no existe registro activo!
    const subscription = await prisma.subscription.create({
      data: {
        tenantId,
        planTier,
        seats,
        stripeChargeId: charge.id,
        status: "ACTIVE",
      },
    });

    // 5. Envio de correo en linea que ralentiza la respuesta HTTP y falla en silencio
    await resend.emails.send({
      to: req.body.email,
      subject: "Suscripcion Activada",
      text: `Tu plan ${planTier} ya se encuentra activo.`,
    });

    return res.status(200).json({ success: true, id: subscription.id });
  } catch (error: any) {
    return res.status(500).json({ error: error.message });
  }
}

Las debilidades de este enfoque tradicional son críticas:

• Cero Independencia del Transporte: Probar esta operación de negocio requiere simular el entorno completo de Express (req, res, next).
• Integridad Transaccional Rota: Si la inserción en base de datos falla tras el cobro exitoso en Stripe, el dinero del cliente fue debitado sin activar el servicio.
• Radio de Impacto Ilimitado: Migrar de Prisma a Kysely o de Stripe a Paddle obliga a reescribir cada controlador en el repositorio.

Production: Dominio Desacoplado y Puertos Invertidos

Primero, definimos la entidad de negocio inmutable y los contratos de entrada mediante Zod:

import { z } from "zod";

export const activateSubscriptionInputSchema = z.object({
  tenantId: z.string().uuid(),
  idempotencyKey: z.string().min(16),
  planTier: z.enum(["STARTER", "GROWTH", "ENTERPRISE"]),
  seats: z.number().int().min(1).max(500),
  paymentToken: z.string().min(1),
});

export type ActivateSubscriptionInput = z.infer<typeof activateSubscriptionInputSchema>;

// Entidad de Dominio con invariantes de negocio autocontenidos
export class Subscription {
  constructor(
    public readonly id: string,
    public readonly tenantId: string,
    public readonly planTier: "STARTER" | "GROWTH" | "ENTERPRISE",
    public readonly seats: number,
    public readonly status: "ACTIVE" | "SUSPENDED",
    public readonly externalPaymentId: string
  ) {}

  static calculateTotalCents(planTier: "STARTER" | "GROWTH" | "ENTERPRISE", seats: number): number {
    const rateMap = { STARTER: 49, GROWTH: 89, ENTERPRISE: 120 };
    const subtotal = rateMap[planTier] * seats;
    // Regla de negocio: 10% de descuento por volumen a partir de 50 usuarios
    const discountMultiplier = seats >= 50 ? 0.9 : 1.0;
    return Math.round(subtotal * discountMultiplier * 100);
  }
}

// Puertos Invertidos: Interfaces puras que definen QUE necesita la aplicacion
export interface SubscriptionRepository {
  saveAtomic(subscription: Subscription): Promise<void>;
  findByIdempotencyKey(key: string): Promise<Subscription | null>;
}

export interface BillingGateway {
  charge(amountCents: number, token: string, idempotencyKey: string): Promise<{ transactionId: string }>;
}

export interface NotificationService {
  dispatchActivationNotice(tenantId: string, planTier: string): Promise<void>;
}

Segundo, implementamos el caso de uso puro que orquesta el flujo de negocio:

type Result<T, E> = { success: true; value: T } | { success: false; error: E };

export class ActivateSubscriptionUseCase {
  constructor(
    private readonly subscriptions: SubscriptionRepository,
    private readonly billing: BillingGateway,
    private readonly notifications: NotificationService
  ) {}

  async execute(rawInput: unknown): Promise<Result<Subscription, string>> {
    // 1. Validacion de contrato a prueba de fallos antes de ejecutar
    const parsed = activateSubscriptionInputSchema.safeParse(rawInput);
    if (!parsed.success) {
      return { success: false, error: `VALIDATION_FAILED: ${parsed.error.message}` };
    }

    const { tenantId, idempotencyKey, planTier, seats, paymentToken } = parsed.data;

    // 2. Proteccion de idempotencia contra cobros duplicados por reconexiones de red
    const existing = await this.subscriptions.findByIdempotencyKey(idempotencyKey);
    if (existing) {
      return { success: true, value: existing };
    }

    // 3. Evaluacion de invariantes dentro de la entidad pura
    const totalCents = Subscription.calculateTotalCents(planTier, seats);

    try {
      // 4. Cobro aislado a traves del contrato del puerto
      const billingResult = await this.billing.charge(totalCents, paymentToken, idempotencyKey);

      const subscription = new Subscription(
        crypto.randomUUID(),
        tenantId,
        planTier,
        seats,
        "ACTIVE",
        billingResult.transactionId
      );

      // 5. Persistencia atomica mediante repositorio inyectado
      await this.subscriptions.saveAtomic(subscription);

      // 6. Notificacion asincrona que no bloquea la respuesta HTTP
      void this.notifications.dispatchActivationNotice(tenantId, planTier);

      return { success: true, value: subscription };
    } catch (err: unknown) {
      return {
        success: false,
        error: err instanceof Error ? err.message : "SUBSCRIPTION_ACTIVATION_FAILED",
      };
    }
  }
}

Este diseño desacoplado entrega garantías inmediatas de ingeniería:

• Pruebas en Memoria en Menos de 5 ms: Es posible validar cálculos y casos límite al instante con un InMemorySubscriptionRepository sin encender Docker ni bases de datos reales.
• Cero Contaminación de Frameworks: El caso de uso carece de referencias a Express, Fastify, Next.js, Prisma o Stripe.
• Radio de Impacto Confinado: Si decides sustituir Stripe por LemonSqueezy, únicamente modificas una clase adaptadora que implementa BillingGateway. El dominio y el caso de uso permanecen intactos.

Compromisos Técnicos: Cuándo Clean Architecture Es Esencial y Cuándo Sobrediseño

Clean Architecture es una inversión en la durabilidad del software, no un dogma para cada script.

Un ingeniero senior demuestra criterio reconociendo cuándo no conviene añadir abstracciones:

1. Evitar Sobrediseñar Operaciones CRUD Básicas: Si un endpoint solo consulta cinco columnas de una tabla para mostrarlas en un panel administrativo interno, añadir tres capas y dos interfaces introduce complejidad innecesaria. El código CRUD simple debe mantenerse directo.
2. El Valor del Monolito Modular: El 95% de las startups en crecimiento no necesitan microservicios ni agentes de mensajería distribuida complejos. Organizar el código por módulos orientados al negocio dentro de una única base de código entrega límites limpios con la simplicidad de un único despliegue.
3. Manejo del Contexto Transaccional: Cuando las operaciones requieren atomicidad sobre múltiples tablas, transmite una unidad de trabajo transaccional a través del puerto del repositorio en lugar de exponer conexiones de base de datos al caso de uso.

Prueba en Producción: Evolución sin Downtime y Runway Predecible

En Strategio (plataforma de Business Intelligence con IA, ganadora de la 2da generación de Startup Perú), diseñamos la plataforma analítica completa desde cero en 12 semanas.

Al desacoplar las reglas de agregación de datos de los drivers de almacenamiento, pudimos evolucionar motores de consulta relacionales e integraciones externas con cero tiempo de inactividad.

La plataforma alcanzó alta concurrencia manteniendo los costos de infraestructura cloud por debajo de $50 USD al mes durante toda la fase de validación.

De manera similar, en NubaNutrición, los modelos clínicos y fórmulas de cálculo de macronutrientes se aislaron en entidades de dominio puras.

Cuando se rediseñaron las interfaces móviles y web, no fue necesario modificar ni una sola línea de la lógica de evaluación clínica, eliminando riesgos de regresión por completo.

Lista de Verificación Previa para Integridad Arquitectónica

1. Cero Dependencias de Frameworks en el Núcleo: Entidades y casos de uso no importan frameworks web (Express, Fastify) ni librerías ORM.
2. Contratos de Persistencia Invertidos: Todos los repositorios y servicios externos se definen como interfaces puras de TypeScript dentro del dominio o la aplicación.
3. Pruebas en Memoria en Menos de 5 ms: Los flujos críticos están cubiertos por pruebas unitarias usando dobles en memoria sin requerir Docker ni sockets de red.
4. Radio de Impacto de Proveedores Confinado: Los SDKs de terceros (Stripe, Resend, Twilio) están encapsulados en adaptadores; sustituirlos requiere editar un único archivo.
5. Tipos de Resultado Deterministas: Los casos de uso retornan estructuras explícitas Result<T, E> en lugar de propagar excepciones imprevistas a través de las capas.

El Factor Coins5: Sistemas Escalables Construidos para Crecer

Escribir software sin fronteras arquitectónicas solo multiplica la deuda técnica a gran velocidad.

En Coins5, Marlon combina más de una década de experiencia diseñando sistemas modulares bajo Clean Architecture con flujos avanzados de ingeniería asistida por IA para entregar plataformas de producción en un tercio del tiempo convencional.

Si necesitas desenredar una base de código monolítica existente o diseñar tu próximo sistema sobre cimientos sólidos, conversemos.