# Especificacion de Arquitectura Limpia

## Purpose

Define la implementacion de Clean Architecture para ROITheme, un tema WordPress que sigue principios de Domain-Driven Design con separacion fisica de contextos delimitados (Admin, Public, Shared).

## Requirements

### Requirement: Separacion Fisica de Contextos

The system MUST organize code into three physically delimited contexts: Admin/, Public/, and Shared/.

#### Scenario: Codigo pertenece al contexto de administracion
- **WHEN** el codigo maneja operaciones CRUD, configuracion o funcionalidad del panel admin
- **THEN** el codigo DEBE colocarse en el directorio `Admin/`
- **AND** el codigo NO DEBE importar del directorio `Public/`

#### Scenario: Codigo pertenece al contexto publico/frontend
- **WHEN** el codigo maneja renderizado, visualizacion o presentacion frontend
- **THEN** el codigo DEBE colocarse en el directorio `Public/`
- **AND** el codigo NO DEBE importar del directorio `Admin/`

#### Scenario: Codigo es compartido entre contextos
- **WHEN** el codigo es usado por AMBOS contextos Admin/ y Public/
- **THEN** el codigo DEBE colocarse en el directorio `Shared/` raiz
- **AND** tanto Admin/ como Public/ PUEDEN importar de Shared/

---

### Requirement: Organizacion Granular de Codigo Compartido

The system MUST implement three levels of shared code to avoid mixing context-specific shared code.

#### Scenario: Codigo compartido solo dentro del contexto Admin
- **WHEN** el codigo es reutilizado por multiples modulos Admin pero NO por Public
- **THEN** el codigo DEBE colocarse en el directorio `Admin/Shared/`
- **AND** los modulos de Public/ NO DEBEN importar de `Admin/Shared/`

#### Scenario: Codigo compartido solo dentro del contexto Public
- **WHEN** el codigo es reutilizado por multiples modulos Public pero NO por Admin
- **THEN** el codigo DEBE colocarse en el directorio `Public/Shared/`
- **AND** los modulos de Admin/ NO DEBEN importar de `Public/Shared/`

#### Scenario: Codigo compartido entre ambos contextos
- **WHEN** el codigo es reutilizado por AMBOS modulos Admin/ y Public/
- **THEN** el codigo DEBE colocarse en el directorio `Shared/` raiz
- **AND** esto incluye ValueObjects, Exceptions y Contracts base

---

### Requirement: Cada Contexto Sigue las Capas de Clean Architecture

Each context (Admin/, Public/, Shared/) MUST internally implement the three Clean Architecture layers: Domain, Application, Infrastructure.

#### Scenario: Estructura de modulo dentro del contexto Admin
- **GIVEN** un componente llamado "Navbar" en el contexto Admin
- **WHEN** el modulo es creado
- **THEN** la estructura DEBE ser: Admin/Navbar/ con subcarpetas Domain/, Application/, Infrastructure/

#### Scenario: Estructura de modulo dentro del contexto Public
- **GIVEN** un componente llamado "Navbar" en el contexto Public
- **WHEN** el modulo es creado
- **THEN** la estructura DEBE ser: Public/Navbar/ con subcarpetas Domain/, Application/, Infrastructure/

---

### Requirement: Cumplimiento de Direccion de Dependencias

The system MUST enforce that dependencies flow ONLY from outer layers to inner layers.

#### Scenario: Infrastructure depende de Application y Domain
- **WHEN** el codigo esta en la capa Infrastructure
- **THEN** PUEDE importar de la capa Application
- **AND** PUEDE importar de la capa Domain

#### Scenario: Application depende solo de Domain
- **WHEN** el codigo esta en la capa Application
- **THEN** PUEDE importar de la capa Domain
- **AND** NO DEBE importar de la capa Infrastructure

#### Scenario: Domain no tiene dependencias externas
- **WHEN** el codigo esta en la capa Domain
- **THEN** NO DEBE importar de la capa Application
- **AND** NO DEBE importar de la capa Infrastructure
- **AND** NO DEBE importar funciones o globales de WordPress

---

### Requirement: La Capa Domain Contiene Solo Logica de Negocio Pura

The Domain layer MUST contain only pure business logic without framework dependencies.

#### Scenario: Validacion de contenido de capa Domain
- **WHEN** el codigo se coloca en la capa Domain
- **THEN** PUEDE contener Entities, Value Objects, Domain Services, Interfaces, Exceptions
- **AND** NO DEBE contener global $wpdb, $_POST, $_GET, $_SESSION, add_action, add_filter, HTML, CSS, JavaScript

#### Scenario: Implementacion de entidad Domain
- **GIVEN** una entidad Domain como NavbarConfiguration
- **WHEN** la entidad es implementada
- **THEN** DEBE contener reglas de negocio y validacion
- **AND** NO DEBE contener logica de persistencia
- **AND** NO DEBE referenciar APIs de WordPress

---

### Requirement: La Capa Application Orquesta Domain

The Application layer MUST orchestrate domain entities without containing business logic.

#### Scenario: Implementacion de Use Case
- **WHEN** un Use Case es implementado
- **THEN** DEBE coordinar entidades y servicios de domain
- **AND** DEBE depender de interfaces, NO de implementaciones concretas
- **AND** NO DEBE contener reglas de validacion de negocio

#### Scenario: Uso de DTOs para transferencia de datos
- **WHEN** los datos cruzan limites entre capas
- **THEN** se DEBEN usar DTOs (Data Transfer Objects)
- **AND** los DTOs DEBEN ser contenedores de datos simples sin logica de negocio

---

### Requirement: Infrastructure Implementa Interfaces

The Infrastructure layer MUST implement interfaces defined in Domain/Application layers.

#### Scenario: Implementacion de Repository
- **GIVEN** una RepositoryInterface definida en Domain
- **WHEN** el repository es implementado
- **THEN** DEBE colocarse en Infrastructure/Persistence/
- **AND** DEBE implementar la interface de Domain
- **AND** PUEDE usar global $wpdb o APIs de WordPress

#### Scenario: Integracion con WordPress
- **WHEN** se necesita codigo especifico de WordPress
- **THEN** DEBE colocarse en la capa Infrastructure
- **AND** NO DEBE filtrarse a las capas Domain o Application

---

### Requirement: Los Modulos Son Autocontenidos e Independientes

Each module (Navbar, Footer, Toolbar, etc.) MUST be self-contained and independent from other modules.

#### Scenario: Aislamiento de modulos
- **WHEN** un modulo como Admin/Navbar/ es implementado
- **THEN** NO DEBE importar de Admin/Footer/
- **AND** NO DEBE importar de Admin/Toolbar/
- **AND** SOLO PUEDE importar de Shared/

#### Scenario: Eliminacion de modulos
- **WHEN** un modulo necesita ser eliminado
- **THEN** borrar la carpeta del modulo NO DEBE romper otros modulos
- **AND** no se DEBERIAN requerir cambios de codigo en otros modulos

---

### Requirement: Admin y Public Son Bounded Contexts Separados

Admin/ and Public/ MUST be treated as separate bounded contexts because they have different responsibilities.

#### Scenario: Responsabilidad del contexto Admin
- **WHEN** el codigo maneja administracion de componentes
- **THEN** la entidad Domain se enfoca en configuracion, validacion, estados draft/published
- **AND** los Use Cases se enfocan en operaciones Save, Update, Delete, Get

#### Scenario: Responsabilidad del contexto Public
- **WHEN** el codigo maneja renderizado de componentes
- **THEN** la entidad Domain se enfoca en estado activo, caching, filtrado por permisos
- **AND** los Use Cases se enfocan en operaciones GetActive, Render, Cache

#### Scenario: No hay duplicacion de domain
- **WHEN** Admin/Navbar/Domain/ y Public/Navbar/Domain/ ambos existen
- **THEN** NO son duplicados sino bounded contexts especializados
- **AND** Admin se enfoca en configuracion/gestion
- **AND** Public se enfoca en renderizado/visualizacion

---

### Requirement: Validacion de Arquitectura Antes de Commit

The system MUST validate architectural compliance before committing code.

#### Scenario: Validacion de capa Domain
- **WHEN** se valida codigo de la capa Domain
- **THEN** grep por global $wpdb DEBE retornar vacio
- **AND** grep por add_action DEBE retornar vacio
- **AND** grep por $_POST DEBE retornar vacio

#### Scenario: Validacion de dependencias de modulos
- **WHEN** se validan dependencias entre modulos
- **THEN** imports de Admin/Navbar/ desde Admin/Footer/ NO DEBEN existir
- **AND** imports de Public/Navbar/ desde Public/Footer/ NO DEBEN existir

---

### Requirement: Realizacion de Beneficios de la Arquitectura

The architecture MUST provide measurable benefits.

#### Scenario: Asignacion granular de trabajo
- **WHEN** un desarrollador es asignado a trabajar en Admin/Navbar/
- **THEN** puede acceder SOLO a esa carpeta
- **AND** no puede ver ni modificar Public/ u otros modulos de Admin/

#### Scenario: Eliminacion facil de modulos
- **WHEN** un componente ya no es necesario
- **THEN** eliminarlo requiere solo borrar la carpeta
- **AND** no se necesitan otras modificaciones de codigo

#### Scenario: Codigo compartido consistente
- **WHEN** se encuentra un bug en un ValueObject compartido
- **THEN** arreglarlo en Shared/Domain/ValueObjects/ lo arregla para TODOS los modulos
- **AND** no se necesita actualizar codigo duplicado