# Arquitectura de 4 Capas

CD-System se estructura en 4 capas que se apilan de abajo hacia arriba. Cada capa cumple un rol específico y tiene límites claros respecto a las demás.

```
┌─────────────────────────────────────────────────┐
│  CAPA 4: DATOS DEL PROYECTO                     │
│  Identidad, contenido, assets, analytics        │
│  (cada proyecto tiene su propia DB)             │
├─────────────────────────────────────────────────┤
│  CAPA 3: MÓDULOS                                │
│  Funcionalidades activables/desactivables       │
│  blog, menu, services, gallery, faqs...         │
├─────────────────────────────────────────────────┤
│  CAPA 2: DEMO (Template Visual)                 │
│  Identidad visual del tipo de negocio           │
│  header + footer + page-headers + CSS + vistas  │
├─────────────────────────────────────────────────┤
│  CAPA 1: NÚCLEO (CD-Base)                       │
│  Framework, servicios, helpers, middleware       │
│  Layout maestro, routing, auth, admin panel     │
└─────────────────────────────────────────────────┘
```

## Capa 1: Núcleo (CD-Base)

Es la base sobre la que todo se construye. Es **compartido por todos los proyectos** sin excepción.

### Qué contiene

| Componente | Ubicación | Función |
|------------|-----------|---------|
| Framework Laravel | `app/`, `config/`, `routes/` | Motor de la aplicación |
| Layout maestro | `layout/front/master.blade.php` | Estructura HTML base de toda página frontend |
| Partials de ensamblaje | `layout/front/partials/` | `_header`, `_footer`, `_styles`, `_scripts` resuelven qué cargar según el demo activo |
| Servicios core | `app/Services/` | `SiteConfigService` (config desde DB), `ProjectAssetService` (Cloudinary) |
| Providers | `app/Providers/` | `SiteConfigServiceProvider` (merge DB + config), `CdSystemConfigServiceProvider` |
| Helpers globales | `app/helpers.php` | `get_theme_demo()`, `is_module_active()`, `get_demo_layout()`, etc. |
| Middleware | `app/Http/Middleware/` | `module.enabled:{module}` (protege rutas), `maintenance:{module}` |
| Config del sistema | `config/cd-system.php` | Registro de todos los módulos disponibles, versión, tema, seguridad |
| Config del proyecto | `config/site.php` | Estructura de datos del proyecto (valores default, la DB los sobreescribe) |
| Admin panel | `layout/demo1/`, `views/admin/` | Panel de administración (basado en Metronic) |
| Auth | `views/auth/`, `routes/auth.php` | Autenticación de usuarios |
| Seeders base | `database/seeders/` | `Project_Seeder`, `CdSystemSeeder`, `SiteDataSeeder`, `AssetsSeeder`, `AnalyticsSeeder` |
| Comando de provisión | `bewpro:provision` | Provisión automatizada de proyectos desde un solo JSON |

### Principio de diseño

El núcleo **no conoce** qué demo está activo ni qué módulos hay. Solo sabe **cómo preguntar**: lee la configuración y delega la resolución a helpers y providers. Esto garantiza que el núcleo nunca necesita modificarse al agregar demos o módulos nuevos.

### Flujo de configuración en runtime

```
Archivos JSON ──→ Seeders ──→ DB (tabla settings)
                                    │
                              SiteConfigService (cache 24h)
                                    │
                         SiteConfigServiceProvider
                         (merge: DB tiene prioridad sobre config/site.php)
                                    │
                              config('site.*')
                         disponible en toda la app
```

---

## Capa 2: Demo (Template Visual)

Un **demo** es un template visual completo que le da identidad estética a un tipo de negocio. Define cómo se ve el sitio, no qué hace.

### Los 5 componentes de un demo

| # | Componente | Ubicación | Qué hace |
|---|-----------|-----------|----------|
| 1 | **Header** | `layout/front/headers/demo-{nombre}.blade.php` | Barra de navegación superior (logo, menú, CTA, redes) |
| 2 | **Footer** | `layout/front/footers/demo-{nombre}.blade.php` | Pie de página (contacto, links, copyright) |
| 3 | **Page-Headers dinámicos** | Partials `dynamic-header.blade.php` en cada módulo | Marco visual que enmarca cada página de módulo (título, subtítulo, breadcrumb) con el estilo del demo |
| 4 | **CSS (demo + skin)** | `public/template/css/demos/demo-{nombre}.css` + `skins/skin-{nombre}.css` | El demo CSS define la estructura visual; el skin define los colores de la marca/tipo |
| 5 | **Vistas base** | `modules/cd-base/frontend/demos/demo-{nombre}/` | Welcome (home), About y Contact con diseño propio del demo |

### Page-Headers dinámicos (concepto clave)

Los page-headers son el mecanismo que permite que **cualquier módulo se integre visualmente a cualquier demo** sin que el módulo conozca al demo ni el demo conozca al módulo.

```
Módulo Blog ──→ "Necesito un page-header" ──→ Sistema detecta demo activo
                                                      │
                                    ┌─────────────────┴─────────────────┐
                                    ▼                                   ▼
                           demo-restaurant                      demo-law-firm-2
                           page-header modern                   page-header modern
                           (parallax, visual)                   (colores law firm)
```

Esto significa que al agregar un nuevo demo, solo hay que crear las variantes de page-header para los módulos que se usarán. Y al agregar un nuevo módulo, solo hay que crear su `dynamic-header.blade.php` con las variantes de los demos existentes.

**Escalabilidad:** N demos x M módulos = page-headers por combinación usada, no por todas las combinaciones posibles.

### Scoping CSS

Cada demo aísla sus estilos bajo una clase HTML:

```css
html.demo-restaurant .page-header-modern { ... }
html.demo-restaurant .btn-primary { ... }
```

La clase `demo-{nombre}` se añade al `<html>` en `master.blade.php` cuando el demo está activo. Un solo demo cargado por proyecto = aislamiento total.

### Orden de carga CSS (cascada)

```
1. Vendor CSS       (Bootstrap, librerías)
2. Theme CSS        (Porto base)
3. CD-System Base   (componentes propios)
4. Modular CSS      (estilos por módulo)
5. Skin CSS         (colores: skin-{nombre}.css)
6. Custom CSS       (overrides genéricos)
7. Demo CSS         (identidad visual: demos/{demo}.css) ← prevalece
8. @yield('css')    (estilos por página específica)
```

El demo CSS va después de custom.css para que la identidad del demo siempre prevalezca.

### Registro del demo en el sistema

Para que el sistema conozca un demo, debe estar registrado en:

1. `app/helpers.php` → `get_demo_layout_mapping()` (mapea demo → header/footer)
2. `app/helpers.php` → `get_demo_skin_mapping()` (mapea demo → skin CSS)
3. `config/page-headers.php` → tipo de page-header por demo (classic, modern)

### Demos disponibles actualmente

| Demo | Tipo de negocio | Validado | Proyecto referencia |
|------|----------------|----------|---------------------|
| demo-restaurant | Gastronomía | Si | Muma |
| demo-law-firm-2 | Bufetes/abogados | Si | Bewpro Law Firm |
| demo-construction | Construcción | Disponible | - |
| demo-construction-2 | Construcción v2 | Disponible | - |
| demo-accounting-1 | Contabilidad | Disponible | - |
| demo-accounting-2 | Contabilidad v2 | Disponible | - |
| demo-architecture-2 | Arquitectura | Disponible | - |
| demo-creative-agency-2 | Agencias creativas | Disponible | - |
| demo-digital-agency-2 | Agencias digitales | Disponible | - |
| demo-photography-3 | Fotografía | Disponible | - |
| demo-insurance | Seguros | Disponible | - |
| demo-marketing-1 | Marketing | Disponible | - |
| demo-product-landing | Landing de productos | Disponible | - |
| demo-business-consulting | Consultoría | Disponible | - |
| demo-sass | SaaS | Disponible | - |
| demo-transportation-logistic | Transporte/logística | Disponible | - |

---

## Capa 3: Módulos

Los módulos son **funcionalidades independientes** que se activan o desactivan por proyecto. Cada módulo calza en el núcleo a través de puntos de integración definidos.

### Puntos de integración (slots)

Un módulo se conecta al sistema a través de estos slots:

| Slot | Qué hace | Ejemplo |
|------|----------|---------|
| **Rutas** | `routes/modules/{modulo}.php` protegidas por middleware `module.enabled` | `/blog`, `/blog/{slug}` |
| **Navegación** | `navigation.header` / `navigation.footer` controlan si aparece en menús | Blog en header y footer |
| **Page-header** | `dynamic-header.blade.php` se adapta al demo activo | Cabecera visual del listado de blog |
| **Seeders** | JSON + Seeder cargan contenido inicial | `blog.json` → `BlogSeeder` |
| **Config** | Registro en `config/cd-system.php` con active, name, version, navigation | Metadata del módulo |
| **Admin** | Vistas y controladores de administración | CRUD de posts desde el panel |

### Tipos de módulos

| Tipo | Módulos | Características |
|------|---------|----------------|
| **Contenido** | blog, menu, news | Generan contenido publicable con categorías |
| **Catálogo** | products, services, projects | Fichas con listado y detalle |
| **Visual** | gallery | Grillas de imágenes con categorías/tags |
| **Personas** | team, references | Perfiles y testimonios |
| **Soporte** | faqs | Preguntas frecuentes |
| **Marketing** | newsletter | Suscripción a emails |
| **Página** | about, contact | Páginas institucionales (vistas del demo) |
| **Sistema** | translations, project-setup | Funcionalidades internas |

### Estructura de un módulo

```
app/Modules/{NombreModulo}/
├── Models/                    Modelos Eloquent
├── Controllers/
│   ├── Frontend/              Controladores públicos (listado, detalle)
│   └── Admin/                 Controladores de administración (CRUD)
└── Services/                  Lógica de negocio (opcional)

resources/views/modules/{nombre-modulo}/
├── frontend/
│   ├── index.blade.php        Listado público
│   ├── show.blade.php         Detalle público
│   └── partials/
│       └── dynamic-header.blade.php   Integración visual con el demo
└── admin/
    ├── index.blade.php        Listado admin
    ├── modals/                Modales CRUD
    └── categories/            Gestión de categorías

routes/modules/{nombre-modulo}.php     Rutas protegidas por middleware

database/seeders/project-data/{nombre-modulo}.json   Datos semilla
```

### Activación y control

La activación se define en `database/seeders/project-data/cd-system.json`:

```json
{
  "modules": {
    "blog": {
      "active": true,
      "navigation": { "header": true, "footer": true }
    },
    "menu": {
      "active": true,
      "navigation": { "header": true, "footer": true }
    },
    "gallery": {
      "active": false
    }
  }
}
```

`CdSystemSeeder` carga esto en la DB → `config('cd-system.modules')` en runtime.

---

## Capa 4: Datos del Proyecto

Cada proyecto tiene su **propia base de datos**. Cambiar la DB = cambiar todo el proyecto.

### Principio multi-tenant

```
Proyecto Muma     → DB: bp-muma      → demo-restaurant + blog, menu, faqs
Proyecto LawFirm  → DB: bp-lawfirm   → demo-law-firm-2 + services, blog, faqs
Proyecto Agency   → DB: bp-agency    → demo-creative-agency-2 + services, projects, blog
```

Un solo servidor, un solo codebase. Solo cambia `DB_DATABASE` en `.env`.

### Qué contiene la capa de datos

| Dato | Fuente JSON | Seeder | Destino |
|------|------------|--------|---------|
| Demo y módulos activos | `cd-system.json` | `CdSystemSeeder` | `config/cd-system.php` (vía DB) |
| Identidad (nombre, contacto, SEO, redes, footer) | `site-data.json` | `SiteDataSeeder` | tabla `settings` → `config('site.*')` |
| Assets (logos, favicons, imágenes OG) | `assets.json` | `AssetsSeeder` | tabla `assets` + Cloudinary |
| Analytics (GA, GTM, Facebook Pixel) | `analytics.json` | `AnalyticsSeeder` | tabla `settings` → `config('site.google_analytics')` |
| Contenido por módulo | `blog.json`, `menu.json`, etc. | Seeders individuales | Tablas del módulo |
| Usuarios | `users.json` | `ProjectsUsersSeeder` | tabla `users` |

### Orden de ejecución (Project_Seeder)

```
1. CdSystemSeeder      → Demo y módulos (debe ser primero)
2. AssetsSeeder         → Assets a Cloudinary + tabla assets
3. SiteDataSeeder       → Identidad del proyecto (resuelve URLs de assets)
4. AnalyticsSeeder      → Tracking
5. ProjectsUsersSeeder  → Usuarios
6. Seeders de módulos   → Solo los módulos con active: true
7. CdBaseSeeder         → Contenido base
```

### Provisión de un proyecto

**Método rápido (recomendado):**
```bash
php artisan bewpro:provision database/seeders/project-data/provision-miproyecto.json
```
Un solo JSON con toda la configuración. Crea DB, migra, configura, seedea, limpia caché.

**Método manual:** Editar los 4 JSON + ejecutar seeders paso a paso. Documentado en [qa/00-proceso-desde-cero.md](../qa/00-proceso-desde-cero.md).

---

## Cómo se ensambla todo

Cuando un usuario visita un proyecto (ej: Muma), el sistema resuelve:

```
1. Request llega → Laravel boot
2. SiteConfigServiceProvider carga config desde DB
   → config('cd-system.theme.demo') = 'demo-restaurant'
   → config('cd-system.modules.blog.active') = true
   → config('site.name') = 'Muma'

3. master.blade.php se renderiza:
   → _header.blade.php → get_demo_layout('header') → headers/demo-restaurant.blade.php
   → contenido de la ruta (welcome, /blog, /menu, etc.)
   → _footer.blade.php → get_demo_layout('footer') → footers/demo-restaurant.blade.php
   → _styles.blade.php → carga demo-restaurant.css + skin-restaurant.css

4. Si la ruta es /blog:
   → middleware module.enabled:blog verifica que blog esté activo
   → BlogController carga posts
   → blog/frontend/index.blade.php se renderiza
   → dynamic-header.blade.php detecta demo-restaurant → page-header modern

5. Resultado: página completa con identidad Muma, estilo restaurant, contenido del blog
```

## Documentación relacionada

- [01-vision-y-modelo.md](01-vision-y-modelo.md) -- Visión y modelo de negocio
- [03-concepto-producto.md](03-concepto-producto.md) -- Cómo se empaquetan los productos
- [../core/](../core/) -- Documentación técnica detallada de cada componente