# Arquitectura de demos y modulos — CD-System
> Documento tecnico de referencia | Revision: 2026-03-20

---

## Principio fundamental

> **El demo controla la estetica. El modulo controla la funcionalidad. Nunca al reves.**

Un demo define COMO se ve un sitio. Los modulos definen QUE funcionalidades tiene. La combinacion de ambos produce un producto.

---

## Las 3 capas de adaptacion visual de un demo

```
CAPA 1: CSS (skin + demo CSS)
    → Define colores, tipografia, fondos, bordes, sombras, hovers
    → Incluye global overrides para convertir clases Porto a la estetica del demo
    → Afecta TODAS las vistas sin tocar HTML

CAPA 2: Page header (partial compartido)
    → Un archivo .blade.php por demo: page-header-{name}.blade.php
    → Registrado en los 10 dynamic-headers de cada modulo
    → Define el banner superior de cada pagina de modulo

CAPA 3: Paginas base del demo (welcome, about, contact)
    → Estas SI son especificas del demo
    → Integran datos de modulos via $services, $featuredProjects, $featuredFaqs, etc.
    → Viven en: modules/cd-base/frontend/demos/demo-{name}/
```

---

## Donde DEBE y NO DEBE haber logica de demo

### CORRECTO: logica de demo en estos lugares

| Lugar | Ejemplo | Por que |
|-------|---------|---------|
| `dynamic-header.blade.php` | `@if($isAccounting1) @include(partial)` | El page header es visual, cambia por demo |
| `demos/demo-{name}/welcome.blade.php` | Layout completo del homepage | La homepage es 100% del demo |
| `demos/demo-{name}/about.blade.php` | Layout de la pagina about | Idem |
| `demos/demo-{name}/contact.blade.php` | Layout de la pagina contact | Idem |
| `demo-{name}.css` | Global overrides | CSS es el lugar correcto para estilos |
| `skin-{name}.css` | Variables de color | El skin solo define la paleta |
| `headers/demo-{name}.blade.php` | Navegacion | El header es propio del demo |
| `footers/demo-{name}.blade.php` | Footer | El footer es propio del demo |

### INCORRECTO: logica de demo en estos lugares

| Lugar | Ejemplo | Por que es incorrecto |
|-------|---------|----------------------|
| Controladores de modulos | `if ($demo === 'accounting-1') return view(...)` | El controlador no debe saber de demos |
| Vistas index de modulos | `@if($currentDemo === 'accounting-1') <cards hardcodeadas>` | Las vistas de modulos deben ser agnosticas |
| Vistas show/detail de modulos | `@if($demo === 'X') <layout diferente>` | Idem |
| Modelos | Nunca | Nunca |

### La regla de oro

**Si necesitas que un modulo se vea diferente en un demo, usas CSS. No duplicas HTML.**

Los global overrides en el demo CSS convierten las clases Porto (`.bg-light`, `.text-dark`, `.card`, etc.) a la estetica del demo. Esto afecta TODAS las vistas de modulos sin tocar una sola linea de Blade.

```css
/* demo-accounting-1.css — Global Overrides */
.bg-color-grey-scale-1 { background-color: var(--secondary) !important; }
.text-color-dark { color: var(--light) !important; }
.card { background-color: var(--dark) !important; }
.form-control { background-color: var(--dark) !important; }
```

---

## Anatomia completa de un demo

### Archivos requeridos

```
public/template/css/
├── skins/skin-{name}.css               ← Paleta de colores (variables CSS)
└── demos/demo-{name}.css               ← Estilos + global overrides

resources/views/
├── layout/front/
│   ├── headers/demo-{name}.blade.php   ← Header con nav dinamica
│   ├── footers/demo-{name}.blade.php   ← Footer con nav + contacto + newsletter
│   └── partials/
│       └── page-header-{name}.blade.php ← Page header compartido para modulos
│
└── modules/cd-base/frontend/demos/demo-{name}/
    ├── welcome.blade.php               ← Homepage (integra modulos dinamicos)
    ├── about.blade.php                 ← Pagina empresa
    └── contact.blade.php               ← Pagina contacto
```

### Registros en dynamic-headers (10 archivos)

Cada modulo tiene un `partials/dynamic-header.blade.php` donde se registra el demo:

```blade
@elseif(get_active_demo() == 'demo-{name}')
    @include('layout.front.partials.page-header-{name}', [
        'pageTitle' => $pageTitle,
        'pageLabel' => 'LABEL_DEL_MODULO',
        'pageBreadcrumb' => $breadcrumbItems,
        'pageSubtitle' => $pageSubtitle ?? null,
    ])
```

Los 10 archivos:
1. `modules/services/frontend/partials/dynamic-header.blade.php`
2. `modules/projects/frontend/partials/dynamic-header.blade.php`
3. `modules/blog/frontend/partials/dynamic-header.blade.php`
4. `modules/cd-base/faqs/frontend/partials/dynamic-header.blade.php`
5. `modules/gallery/frontend/partials/dynamic-header.blade.php`
6. `modules/products/frontend/partials/dynamic-header.blade.php`
7. `modules/team-members/frontend/partials/dynamic-header.blade.php`
8. `modules/references/frontend/partials/dynamic-header.blade.php`
9. `modules/cd-base/frontend/partials/dynamic-header.blade.php` (contact)
10. `modules/menu/frontend/partials/dynamic-header.blade.php`

---

## Como el CSS controla la estetica de los modulos

### Estructura del demo CSS

```css
/* 1. Foundation */
html, body { background-color: var(--secondary) !important; }

/* 2. Header */
#header .header-body { ... }

/* 3. Typography */
h1, h2, h3 { text-transform: none; }

/* 4. Components (buttons, cards, forms) */
.btn-primary { ... }
.card { ... }

/* 5. Module-specific refinements */
.service-card { ... }
.project-card { ... }
.faq-item { ... }

/* 6. Responsive */
@media (max-width: 991px) { ... }

/* 7. GLOBAL OVERRIDES — el bloque mas importante */
/* Convierte clases Porto light-mode a la estetica del demo */
.bg-light, .bg-color-light { background-color: var(--secondary) !important; }
.text-color-dark, .text-dark { color: var(--light) !important; }
.text-muted, .text-color-grey { color: var(--quaternary) !important; }
.card { background-color: var(--dark) !important; }
.form-control { background-color: var(--dark) !important; color: var(--light) !important; }

/* 8. Container width */
.main .container:not(.container-xl-custom) { max-width: 1440px; }
```

### Por que los global overrides resuelven todo

Las vistas de modulos usan clases Porto estandar: `.bg-light`, `.text-color-dark`, `.card`, etc. Estas clases producen un look light-mode por defecto.

El bloque de global overrides en el demo CSS **redefine** esas clases para el demo especifico. El resultado: la misma vista HTML se ve dark mode en accounting-1 y light mode en otro demo.

**No se necesita duplicar HTML.** Un unico archivo CSS controla la estetica de TODOS los modulos.

---

## Flujo de renderizado: que pasa cuando se visita /services/{slug}

```
1. Laravel resuelve la ruta → ServiceController::serviceDetail($slug)
2. El controlador busca el Service en la DB (NO sabe de demos)
3. Retorna la vista service-detail.blade.php con $service
4. La vista:
   a. Detecta el demo actual via get_theme_demo()
   b. Para el page header: usa el dynamic-header que @include el partial del demo
   c. Para el contenido: renderiza HTML con clases Porto estandar
5. El browser carga:
   a. skin-{name}.css → define las variables de color
   b. demo-{name}.css → aplica estilos + global overrides
6. Resultado: el HTML Porto se ve con la estetica del demo activo
```

---

## Patron para integrar modulos en el welcome

El HomepageController pasa datos de TODOS los modulos activos. El welcome del demo elige cuales mostrar:

```blade
{{-- Solo mostrar si el modulo esta activo Y tiene datos --}}
@if(is_module_active('services') && isset($services) && $services->count() > 0)
    <section>
        @foreach($services->take(3) as $index => $service)
            {{-- Card con clases del demo --}}
        @endforeach
    </section>
@endif

@if(is_module_active('projects') && isset($featuredProjects) && $featuredProjects->count() > 0)
    <section>
        @foreach($featuredProjects->take(4) as $project)
            {{-- Card con clases del demo --}}
        @endforeach
    </section>
@endif

@if(is_module_active('faqs') && isset($featuredFaqs) && $featuredFaqs->count() > 0)
    <section>
        @foreach($featuredFaqs->take(5) as $faq)
            {{-- Accordion/toggle con clases del demo --}}
        @endforeach
    </section>
@endif
```

Variables disponibles del HomepageController:
- `$services` — hasta 6 servicios activos
- `$featuredProjects` — hasta 6 proyectos
- `$featuredFaqs` — hasta 5 FAQs
- `$featuredPosts` — hasta 3 posts de blog
- `$galleryImages` — hasta 8 imagenes
- `$teamMembers` — miembros del equipo
- `$featuredReferences` — referencias
- `$carouselImages` — carousel

---

## Checklist para crear un demo nuevo

### Fase 1 — Archivos base
- [ ] Crear `skin-{name}.css` con paleta completa (primary, secondary, tertiary, quaternary, dark, light + inversas + grises + rgbas)
- [ ] Crear `demo-{name}.css` con estilos base + global overrides
- [ ] Crear `headers/demo-{name}.blade.php` con nav dinamica
- [ ] Crear `footers/demo-{name}.blade.php` con nav + contacto + newsletter
- [ ] Crear `page-header-{name}.blade.php` partial compartido

### Fase 2 — Paginas base
- [ ] Crear `demos/demo-{name}/welcome.blade.php` con secciones dinamicas de modulos
- [ ] Crear `demos/demo-{name}/about.blade.php` usando el page-header compartido
- [ ] Crear `demos/demo-{name}/contact.blade.php` usando el page-header compartido

### Fase 3 — Registro en dynamic-headers
- [ ] Registrar en services/dynamic-header.blade.php
- [ ] Registrar en projects/dynamic-header.blade.php
- [ ] Registrar en blog/dynamic-header.blade.php
- [ ] Registrar en faqs/dynamic-header.blade.php
- [ ] Registrar en gallery/dynamic-header.blade.php
- [ ] Registrar en products/dynamic-header.blade.php
- [ ] Registrar en team-members/dynamic-header.blade.php
- [ ] Registrar en references/dynamic-header.blade.php
- [ ] Registrar en contact/dynamic-header.blade.php
- [ ] Registrar en menu/dynamic-header.blade.php

### Fase 4 — Verificacion
- [ ] Homepage renderiza con modulos activos
- [ ] About usa page-header compartido
- [ ] Contact usa page-header compartido + formulario funciona
- [ ] /services lista servicios de DB
- [ ] /services/{slug} muestra detalle con page-header correcto
- [ ] /projects lista proyectos de DB
- [ ] /projects/{slug} muestra detalle con page-header correcto
- [ ] /faqs muestra FAQs de DB
- [ ] Header muestra links de modulos activos
- [ ] Footer muestra nav + contacto dinamico
- [ ] Sin gaps blancos entre secciones
- [ ] Responsive funciona (mobile, tablet, desktop)
- [ ] Container width consistente en todas las paginas

### Fase 5 — NO hacer
- [ ] No agregar logica de demo en controllers
- [ ] No crear vistas especificas de modulo por demo (usar CSS)
- [ ] No hardcodear contenido en vistas de modulo
- [ ] No duplicar HTML para estilos diferentes

---

## Estado actual de deuda tecnica

Vistas de modulos que aun tienen logica inline de demo (a limpiar progresivamente):

| Archivo | Tipo | Estado |
|---------|------|--------|
| `services/services.blade.php` | `@if accounting-1` con vista diferenciada | Dinamizado pero el @if aun existe |
| `services/service-detail.blade.php` | `@if accounting-1` para page-header | Arreglado — usa partial |
| `blog/index.blade.php` | `@if accounting-1` y `@if restaurant` | Pendiente limpiar |
| `blog/post.blade.php` | `@if accounting-1` | Pendiente limpiar |
| `products/ProductController.php` | `if demo === digital-agency-2` | Caso especial BewPro |

El objetivo a mediano plazo es que las vistas de modulos NO tengan ningun `@if($demo === ...)`. Todo se resuelve con CSS + page-header partials.

---

## Referencia: demo-accounting-1 (Bold Edge) como modelo

```
SKIN:    skin-accounting-1.css     → Paleta OLED Energy (cyan/violet/dark)
CSS:     demo-accounting-1.css     → Estilos Bold Edge + 200+ lineas de global overrides
HEADER:  page-header-accounting-1  → Gradient dark, badge cyan, titulo white, breadcrumb cyan
DYNAMIC: 10 dynamic-headers        → Todos registrados con @include del partial
WELCOME: Secciones dinamicas       → $services, $featuredProjects, $featuredFaqs
ABOUT:   Page-header + contenido   → Usando partial compartido
CONTACT: Page-header + formulario  → Usando partial compartido
CONTAINER: 1440px (xl-custom)      → Estandarizado via CSS override
```

---

---

## Estado de integracion de los 16 demos (auditoria 2026-03-20)

### Niveles de integracion

| Nivel | Descripcion | Archivos |
|-------|-------------|----------|
| **A - Completo** | Tiene TODO: archivos base + page-header partial + CSS overrides + dynamic-headers limpios | Solo accounting-1 |
| **B - Funcional** | Archivos base completos + registrado en dynamic-headers (con headers inline, sin partial compartido) | 9 demos |
| **C - Casi completo** | Archivos base completos pero sin registro en algunos dynamic-headers | 5 demos |
| **D - Parcial** | Falta algun archivo base | 1 demo |

### Matriz de demos

| Demo | Header | Footer | Welcome | About | Contact | CSS | Skin | Dyn-headers | Page-header partial | CSS overrides | Nivel |
|------|:------:|:------:|:-------:|:-----:|:-------:|:---:|:----:|:-----------:|:-------------------:|:-------------:|:-----:|
| accounting-1 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | **A** |
| accounting-2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | B |
| architecture-2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | B |
| business-consulting | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | B |
| construction | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Parcial | ❌ | ❌ | C |
| construction-2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | B |
| creative-agency-2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Parcial | ❌ | ❌ | C |
| digital-agency-2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | B |
| insurance | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | B |
| law-firm-2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | B |
| marketing-1 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Parcial | ❌ | ❌ | C |
| photography-3 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ❌ | ❌ | D |
| product-landing | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Parcial | ❌ | ❌ | C |
| restaurant | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | B |
| sass | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Parcial | ❌ | ❌ | C |
| transportation-logistic | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | B |

### Que falta para llevar cada demo a Nivel A

Para cada demo, el trabajo es:

1. **Crear `page-header-{name}.blade.php`** — el partial compartido (~30 lineas)
2. **Actualizar los 10 dynamic-headers** — reemplazar headers inline con `@include` del partial
3. **Agregar CSS global overrides** al demo CSS — si el demo necesita adaptar clases Porto
4. **Verificar container width** — estandarizar en todas las paginas del demo

Los demos de nivel B ya funcionan correctamente con los modulos. El nivel A agrega:
- Mantenibilidad (1 archivo para el page-header en vez de codigo inline en 10 archivos)
- Consistencia visual (imposible que un modulo tenga un header distinto a otro)

### Prioridad sugerida para iterar

Basado en el catalogo de cores (cuales demos se usan mas):

1. **demo-digital-agency-2** — 5 cores lo usan (el mas popular)
2. **demo-insurance** — 4 cores
3. **demo-business-consulting** — 2 cores
4. **demo-accounting-1** — 2 cores ✅ YA COMPLETO
5. El resto — 1 core cada uno

---

*Basado en la implementacion real de demo-accounting-1 y la auditoria completa del sistema — 2026-03-20*