POR QUÉ
EXISTE POP
Los patrones actuales, Clean Architecture, DDD, MVC y sus variantes, resuelven problemas reales. Pero los introducen demasiado pronto. Un proyecto pequeño termina con cinco capas, interfaces abstractas y un repositorio para cada entidad antes de tener una sola función útil.
La pregunta que más se repite al comenzar un proyecto no es técnica: es ¿dónde va esto? Un desarrollador abre el proyecto y no sabe si la lógica de autenticación vive en services, en controllers, en usecases o en auth. Esa duda es el problema que POP resuelve.
POP parte de una pregunta distinta. En lugar de preguntar qué patrón aplica aquí, pregunta cuál es el propósito de esto. La respuesta decide todo lo demás: dónde vive el código, cómo se llama, con quién habla.
No rechaza OOP ni Clean Architecture. Propone que la organización por propósito sea la capa base, sobre la cual se pueden aplicar patrones avanzados cuando el proyecto los justifique. Primero que funcione bien. Después que escale elegantemente.
POP
vs OOP
La diferencia no está en la sintaxis. Está en la pregunta de partida y en cómo esa pregunta moldea todas las decisiones que siguen.
¿Qué objeto es responsable de esto? ¿De cuál clase hereda? ¿Qué interfaz debe implementar? ¿Es un servicio, un repositorio o un caso de uso? ¿Qué patrón de diseño aplica aquí?
¿Cuál es el propósito de esto? ¿Dónde vive según ese propósito? ¿Con qué necesita comunicarse? ¿Qué puede salir mal y cómo se resuelve? ¿Alguien nuevo entendería esto en 15 minutos?
src/
controllers/
AuthController.js
services/
AuthService.js
repositories/
UserRepository.js
interfaces/
IAuthService.ts
IUserRepository.ts
models/
User.js
middleware/
authMiddleware.js
utils/
tokenHelper.js
funciones/
usuario/
iniciarSesion
cerrarSesion
registrarse
verificarSesion
datos/
usuario/
Molde.Usuario
Molde.Sesion
conexion/
api/
autenticacion
En OOP tienes que conocer la arquitectura del proyecto para saber dónde buscar. En POP el nombre de la carpeta te dice exactamente qué hay adentro. La diferencia parece pequeña al inicio; a los seis meses de proyecto, es enorme.
Cuando se abusa de la herencia, el comportamiento queda enterrado en capas. Para saber qué hace un método tienes que seguir la cadena: clase hija, clase padre, clase abstracta, interfaz. POP evita eso porque no hay herencia. Toda la lógica de una Acción está visible y sus dependencias son declaradas.
FILOSOFÍA
Todo elemento tiene un único propósito, un único lugar y un único responsable. El programador nunca debería preguntarse dónde va algo. Si la duda existe, la estructura está mal diseñada.
POP no organiza por tipo de archivo, por capa técnica ni por patrón. Organiza por intención. El código que autentica usuarios vive junto al resto de lo que tiene que ver con autenticación, sin importar si es una función, un esquema de datos o una regla de negocio.
La complejidad se gana, no se hereda. Un proyecto POP comienza simple porque simple es suficiente. Los patrones avanzados entran cuando el proyecto los pide, no porque el equipo quiera seguir mejores prácticas.
El propósito manda
La pregunta "¿para qué existe esto?" se responde antes de escribir una sola línea. El propósito define el nombre, la ubicación y las dependencias.
Un lugar, un dueño
Cada elemento tiene un lugar que no comparte con ningún otro. La duplicación de lógica es una señal de estructura mal diseñada.
Simplicidad ganada
La complejidad se justifica o no existe. No hay capas por convención. No hay abstracciones porque sí. Solo lo que el proyecto necesita ahora.
Legible por humanos
Si alguien nuevo no puede orientarse en quince minutos, la estructura falló. El código es para personas primero, para máquinas después.
PRINCIPIOS
Siete reglas. Cada una se puede aplicar hoy, en cualquier proyecto, independientemente del lenguaje.
Todo tiene un lugar. Cada elemento pertenece a una sección específica. Si no sabes dónde colocarlo, la estructura está mal diseñada, no el elemento.
Un elemento, un propósito. Una Acción no hace dos cosas. Un Molde no mezcla dominios. Cuando algo hace demasiado, se divide.
El propósito define la ubicación. No importa el lenguaje, el framework ni la plataforma. La ubicación siempre depende del propósito, nunca del tipo de archivo.
Reutilizar antes que duplicar. Si dos elementos comparten estructura, se crea un Molde. Si comparten comportamiento, se crea una Acción en comun/.
Lo que no se usa se elimina. Un campo sin lectura, una Acción sin llamadas, un Molde sin Registros. Todo eso es peso muerto y se borra.
La simplicidad tiene prioridad. Ante dos soluciones posibles, la más simple gana. La complejidad debe justificarse con un problema real, no con una preferencia técnica.
El proyecto debe ser entendible por otra persona. Si un desarrollador nuevo no puede orientarse en quince minutos usando solo los nombres de carpetas y archivos, la estructura falló, no el desarrollador.
ELEMENTOS
DEL LENGUAJE
POP define cuatro elementos fundamentales. Cada uno tiene un propósito preciso y no se mezclan entre sí. El Molde es la forma. El Registro es el contenido. La Acción es el comportamiento. La Solución es la respuesta al error.
Molde
Define la estructura. Sin lógica, sin métodos.
Un Molde describe qué campos tiene un tipo de información y de qué tipo son cada uno. No ejecuta nada. No calcula nada. Solo define la forma que tendrán los datos.
Registro
Un caso concreto basado en un Molde. Tiene valores reales.
El Molde es la forma; el Registro es el contenido. Si el Molde dice que un usuario tiene un nombre de tipo texto, el Registro tiene el nombre real. Un Registro siempre referencia su Molde.
Acción
Comportamiento ejecutable. Entrada, resultado y fallas declaradas.
Una Acción tiene un propósito único, entradas definidas, un resultado esperado y una lista explícita de lo que puede salir mal. No pertenece a ningún Molde. Existe por sí misma en la sección funciones/.
entrada correo texto contrasena texto
resultado sesion Registro Sesion
puede fallar credenciales invalidas usuario inactivo demasiados intentos
entrada usuario Registro Usuario items lista Registro Item
usa inventario.verificarStock pagos.procesarCobro notif.enviarConfirmacion
resultado pedido Registro Pedido
puede fallar stock insuficiente pago rechazado
Solución
La respuesta explícita a cada falla posible.
La Solución reemplaza el try-catch genérico. En lugar de atrapar cualquier error y hacer algo vago con él, POP exige que cada falla posible tenga una respuesta específica declarada junto a la Acción que la puede producir.
puede fallar
si imagen corrupta Solucion reprocesar max 2 intentos
si formato no soportado Solucion convertir convierte a jpg antes
si tamano excedido Solucion comprimir reduce al 80% de calidad
si falla persistente Solucion escalar notifica al sistema
// POP — específico Accion procesarImagen puede fallar si imagen corrupta Solucion reprocesar cada error tiene nombre y respuesta definida
COMUNICACIÓN
ENTRE MÓDULOS
Los módulos no se llaman directamente entre sí. Se comunican a través de Acciones declaradas. La declaración usa es explícita: cualquiera que lea la Acción sabe exactamente de qué depende, sin seguir el código ni leer documentación externa.
Accion crearPedido
entrada usuario Registro Usuario productos lista de Registro Producto
usa inventario.verificarDisponibilidad modulo inventario pagos.procesarCobro modulo pagos notificaciones.enviarConfirmacion modulo notif comun.generarId funcion comun
resultado pedido Registro Pedido
puede fallar stock insuficiente pago rechazado usuario no verificado
El bloque usa es el grafo de dependencias de la Acción, visible sin herramientas externas. Si ves este archivo sabes exactamente qué módulos toca. Eso facilita el testing, el debugging y la revisión de código.
Las dependencias siempre van en una dirección. Un módulo puede usar Acciones de otro, pero no puede ser usado por el mismo módulo que usa. Esto previene dependencias circulares por diseño, no por convención.
REUTILIZACIÓN
POP no tiene herencia. Reutiliza de dos formas: composición de Moldes con incluye y Acciones compartidas en funciones/comun/.
Un Molde puede incluir a otro como parte de su estructura. No lo hereda, lo contiene. La diferencia es importante: si el Molde base cambia, los cambios son explícitos y trazables.
cliente y empresa reutilizan Direccion sin heredar
Molde Cliente id texto nombre texto correo texto envio incluye Direccion facturacion incluye Direccion
Molde Empresa id texto razonSocial texto nit texto sedesPrincipales lista de incluye Direccion
Si el mismo comportamiento se necesita en varios dominios, se extrae a funciones/comun/. Cualquier Acción puede usarla declarándola en su bloque usa.
Accion validarCorreo entrada correo texto resultado valido booleano
usada por iniciarSesion, registrarse, actualizarPerfil cada uno la declara en su bloque 'usa'
Accion registrarse usa comun.validarCorreo comun.hashContrasena comun.generarId
MANEJO
DE ERRORES
En la mayoría de los paradigmas el manejo de errores es una capa separada, algo que se agrega después. En POP los errores son parte del contrato de la Acción desde el principio.
Cada Acción declara explícitamente qué puede salir mal. Eso convierte los errores en documentación viva: cualquiera que lea la Acción sabe qué fallas puede producir y cómo el sistema las resuelve.
entrada archivo binario tipo texto usuario Registro Usuario
usa almacenamiento.subir comun.validarTipo
resultado url texto
puede fallar
si tipo no permitido Solucion abortar informa al usuario el tipo valido
si tamano excedido Solucion transformar comprime si es imagen, rechaza si es otro tipo
si almacenamiento falla Solucion reintentar max 3 veces, espera 2s entre intentos
si falla persistente Solucion escalar notifica al equipo de infraestructura
CASOS
REALES
POP aplicado a escenarios concretos. Los tres dominios más comunes donde la pregunta "¿cuál es el propósito?" cambia todo.