Skip to content

🎯 IMPLEMENTATION PLAN: Plugin Infrastructure (08_00)

📍 UBICACIÓN

Carpeta de trabajo: 4 - INTEGRATION/08_PLUGINS/08_00_plugin_infrastructure/

🤖 INSTRUCCIONES PARA LA IA

Prompt Inicial

Cuando comiences a trabajar en esta carpeta, di:

"Estoy trabajando en la carpeta 08_00_plugin_infrastructure. Voy a implementar el Plan de Infraestructura de Plugins. Déjame leer el IMPLEMENTATION_PLAN.md y organizarme en fases."

Workflow Automático

  1. Lee este archivo completo antes de empezar
  2. Organízate en las 4 FASES definidas abajo
  3. Cada fase = 1 prompt (aprox. 2-3 horas de trabajo)
  4. Al finalizar cada fase: Actualiza el checklist y haz commit
  5. Entre fases: Espera confirmación del usuario antes de continuar

📊 DIVISIÓN EN FASES (4 prompts totales)

FASE 1: Refactoring de Interfaces (Prompt 1)

Duración estimada: 2-3 horas Objetivo: Completar refactoring de las 3 interfaces restantes

Micro-pipeline: 1. Leer interfaces actuales (IParameterHost, IModulationTarget, IUIController) 2. Refactorizar cada una para heredar de 04_CORE 3. Actualizar namespaces a audiolab::plugins 4. Agregar documentación de métodos heredados 5. Actualizar ejemplos de uso 6. Verificar compilación

Checklist: - [ ] IParameterHost.hpp refactorizada - [ ] IModulationTarget.hpp refactorizada - [ ] IUIController.hpp refactorizada - [ ] Ejemplos de uso actualizados - [ ] Compila sin errores

FASE 2: Framework L4 + Utilities (Prompt 2)

Duración estimada: 3-4 horas Objetivo: Crear framework base L4 y utilidades

Micro-pipeline: 1. Crear subdirectorio 08_00_01_l4_framework/ 2. Implementar PluginL4Base.hpp con clase base 3. Implementar L4ParameterManager.hpp 4. Implementar L4StateManager.hpp 5. Implementar L4ProcessingContext.hpp 6. Crear subdirectorio 08_00_03_utilities/ 7. Implementar utilidades (ParameterHelpers, StateHelpers, etc.) 8. Crear CMakeLists.txt para cada subdirectorio 9. Verificar compilación

Checklist: - [ ] PluginL4Base implementada - [ ] L4ParameterManager implementada - [ ] L4StateManager implementada - [ ] L4ProcessingContext implementada - [ ] Utilidades implementadas (5 archivos) - [ ] CMakeLists.txt creados - [ ] Compila sin errores

FASE 3: Framework L5 + Developer Tools (Prompt 3)

Duración estimada: 3-4 horas Objetivo: Crear framework base L5 y herramientas de desarrollo

Micro-pipeline: 1. Crear subdirectorio 08_00_02_l5_framework/ 2. Implementar PluginL5Base.hpp con gestión de slots 3. Implementar L5SlotManager.hpp 4. Implementar L5RouterManager.hpp 5. Implementar L5GlobalParameterManager.hpp 6. Crear subdirectorio 08_00_04_developer_tools/ 7. Implementar developer tools (PluginValidator, MockPlugin, etc.) 8. Crear CMakeLists.txt 9. Verificar compilación

Checklist: - [ ] PluginL5Base implementada - [ ] L5SlotManager implementada - [ ] L5RouterManager implementada - [ ] L5GlobalParameterManager implementada - [ ] Developer tools implementadas (5 archivos) - [ ] CMakeLists.txt creados - [ ] Compila sin errores

FASE 4: Tests + Documentation (Prompt 4)

Duración estimada: 2-3 horas Objetivo: Crear tests exhaustivos y actualizar documentación

Micro-pipeline: 1. Crear tests en 2 - FOUNDATION/03_INFRA/03_04_testing_framework/ 2. Implementar test_plugin_interfaces.cpp 3. Implementar test_l4_framework.cpp 4. Implementar test_l5_framework.cpp 5. Ejecutar todos los tests 6. Actualizar SPEC.md, README.md, CORE_MAPPING.md 7. Actualizar CMakeLists.txt principal 8. Commit final con mensaje descriptivo

Checklist: - [ ] test_plugin_interfaces.cpp creado y pasa - [ ] test_l4_framework.cpp creado y pasa - [ ] test_l5_framework.cpp creado y pasa - [ ] Cobertura > 80% - [ ] Documentación actualizada (3 archivos) - [ ] CMakeLists.txt principal actualizado - [ ] Commit realizado

📝 TAREAS DETALLADAS

TAREA 1.1: Refactorizar IParameterHost.hpp

Archivo: 08_00_00_contracts/IParameterHost.hpp

Pasos exactos: 1. Leer archivo actual 2. Agregar includes: 

#include "../../../../../../2 - FOUNDATION/04_CORE/04_01_core_interfaces/03_communication_interfaces/iobservable.hpp"
#include "../../../../../../2 - FOUNDATION/04_CORE/04_01_core_interfaces/03_communication_interfaces/imessageable.hpp"

  1. Cambiar namespace: 

    namespace audiolab {
namespace plugins {

  2. Cambiar declaración de clase: 

    class IParameterHost : public core::IObservable,
                       public core::IMessageable {

  3. Agregar sección de métodos heredados: 

    //==========================================================================
// Inherited Methods from 04_CORE
//==========================================================================

// From core::IObservable:
//   • void attach(IObserver* observer)
//   • void detach(IObserver* observer)
//   • void notify(uint32_t eventType, void* data)
//
// From core::IMessageable:
//   • void sendMessage(const Message& message)
//   • bool supportsMessageType(uint32_t type) const
//
// See 04_CORE/04_01_core_interfaces/03_communication_interfaces for docs.

  4. Mantener solo métodos específicos de parámetros

  5. Actualizar ejemplos de uso
  6. Cerrar namespaces correctamente

Tiempo: 30 min

TAREA 1.2: Refactorizar IModulationTarget.hpp

Archivo: 08_00_00_contracts/IModulationTarget.hpp

Pasos exactos: 1. Leer archivo actual 2. Agregar include: 

#include "../../../../../../2 - FOUNDATION/04_CORE/04_01_core_interfaces/03_communication_interfaces/iobservable.hpp"

  1. Cambiar namespace a audiolab::plugins

  2. Cambiar declaración: 

    class IModulationTarget : public core::IObservable {

  3. Agregar sección de métodos heredados

  4. Definir IModulationSource interface: 

    class IModulationSource {
public:
    virtual float getSample(int sampleIndex) = 0;
    virtual void advance(int numSamples) = 0;
    virtual void reset() = 0;
    virtual ~IModulationSource() = default;
};

  5. Actualizar ejemplos

Tiempo: 30 min

TAREA 1.3: Refactorizar IUIController.hpp

Archivo: 08_00_00_contracts/IUIController.hpp

Pasos exactos: 1. Leer archivo actual 2. Agregar includes (IObservable + IMessageable) 3. Cambiar namespace a audiolab::plugins 4. Cambiar declaración para heredar de ambas interfaces 5. Agregar sección de métodos heredados 6. Definir UIMessage struct: 

struct UIMessage {
    enum Type {
        ParameterChanged,
        MeterUpdate,
        SpectrumUpdate,
        Custom
    };

    Type type;
    std::string paramId;
    float value;

    union {
        float tempo;
        int noteNumber;
        void* customData;
    } data;
};

  1. Actualizar ejemplos

Tiempo: 30 min

TAREA 2.1: Crear PluginL4Base

Archivo: 08_00_01_l4_framework/PluginL4Base.hpp

Contenido: 

#pragma once

#include "../08_00_00_contracts/IPluginProcessor.hpp"
#include "../08_00_00_contracts/IStateManager.hpp"
#include "../08_00_00_contracts/IParameterHost.hpp"
#include "../08_00_00_contracts/IAudioEngine.hpp"

namespace audiolab {
namespace plugins {

/**
 * @brief Base class for L4 plugins (single DSP engine)
 *
 * Provides default implementations for common functionality.
 * Derived classes only need to override processing logic.
 */
class PluginL4Base : public IPluginProcessor,
                     public IStateManager,
                     public IParameterHost,
                     public IAudioEngine {
public:
    PluginL4Base();
    virtual ~PluginL4Base() = default;

    // IPluginProcessor implementation
    const char* getName() const override { return "PluginL4Base"; }
    const char* getVersion() const override { return "1.0.0"; }
    const char* getVendor() const override { return "AudioLab"; }

    bool supportsBypass() const override { return true; }
    void setBypass(bool bypass) override;

    // IStateManager implementation
    bool saveToFile(const std::string& path) const override;
    bool loadFromFile(const std::string& path) override;
    std::string getDefaultPresetPath() const override;
    std::string getUserPresetPath() const override;

    // IParameterHost implementation (delegated to manager)
    void registerParameter(Parameter* param) override;
    float getParameterValue(const std::string& id) const override;
    void setParameterValue(const std::string& id, float value) override;

    // IAudioEngine implementation
    void prepareToPlay(double sampleRate, uint32_t maxBlockSize,
                      uint32_t numChannels) override;
    void releaseResources() override;
    void reset() override;

protected:
    std::atomic<bool> m_bypassed{false};
    double m_sampleRate = 44100.0;
    uint32_t m_blockSize = 512;
    uint32_t m_numChannels = 2;

    // Component managers
    std::unique_ptr<L4ParameterManager> m_paramManager;
    std::unique_ptr<L4StateManager> m_stateManager;
};

} // namespace plugins
} // namespace audiolab

Crear también: PluginL4Base.cpp con implementación

Tiempo: 1 hora

TAREA 2.2-2.4: Crear Managers L4

Archivos a crear: - L4ParameterManager.hpp/.cpp - Gestión de parámetros - L4StateManager.hpp/.cpp - Gestión de estado - L4ProcessingContext.hpp - Contexto de procesamiento

Estructura similar a PluginL4Base, siguiendo interfaces respectivas.

Tiempo: 1.5 horas

TAREA 2.5: Crear Utilities

Archivos en 08_00_03_utilities/:

  1. ParameterHelpers.hpp
  2. StateHelpers.hpp
  3. AudioHelpers.hpp
  4. ThreadSafeQueue.hpp
  5. PerformanceTimer.hpp

Cada archivo: ~100-200 líneas, funciones helper inline.

Tiempo: 1 hora

TAREA 3.1: Crear PluginL5Base

Similar a PluginL4Base pero con: - Gestión de slots - Routing interno - Parámetros globales

Tiempo: 1.5 horas

TAREA 3.2-3.4: Crear Managers L5

Archivos: - L5SlotManager.hpp/.cpp - L5RouterManager.hpp/.cpp - L5GlobalParameterManager.hpp/.cpp

Tiempo: 1.5 horas

TAREA 3.5: Crear Developer Tools

Archivos en 08_00_04_developer_tools/:

  1. PluginValidator.hpp/.cpp - Validación de plugins
  2. MockPlugin.hpp/.cpp - Mock para tests
  3. PluginFactory.hpp/.cpp - Factory pattern
  4. PluginManifest.hpp/.cpp - Manifiesto

Tiempo: 1 hora

TAREA 4.1-4.3: Crear Tests

Archivos en 2 - FOUNDATION/03_INFRA/03_04_testing_framework/:

// test_plugin_interfaces.cpp
#include <catch2/catch_all.hpp>

TEST_CASE("IPluginProcessor inherits from core interfaces") {
    // Verify inheritance with static_assert
    static_assert(std::is_base_of_v<core::IAudioProcessor, IPluginProcessor>);
    static_assert(std::is_base_of_v<core::IResettable, IPluginProcessor>);
}

TEST_CASE("IParameterHost composition works") {
    // Create mock and test
}

Tiempo: 1.5 horas

TAREA 4.4: Actualizar Documentación

Archivos a actualizar: 1. 08_00_00_contracts/SPEC.md - Referencias a 04_CORE 2. 08_00_00_contracts/README.md - Nueva estructura 3. 08_00_00_contracts/CORE_MAPPING.md - Marcar completado

Tiempo: 30 min

🎯 Criterios de Aceptación Final

Compilación

  • Todo el módulo compila sin errores
  • Sin warnings (nivel -Wall)
  • CMake configura correctamente

Tests

  • Todos los tests pasan (100%)
  • Cobertura > 80%
  • Tests de integración funcionan

Código

  • Todas las interfaces heredan de 04_CORE
  • Namespace audiolab::plugins consistente
  • Documentación Doxygen completa

Estructura

  • 5 subdirectorios creados
  • ~40-50 archivos totales
  • READMEs en cada subdirectorio

📦 Dependencias

Este módulo NO depende de otros (es la base).

Módulos que dependen de este: - 08_01 (Composition Tools) - 08_02 (DSP Integration) - 08_03 (Parameter Integration) - 08_04 (UI Composition) - 08_10 (L4 Architecture) - 08_11 (L5 Architecture)

💾 Commits Recomendados

Commit después de cada fase:

# Fase 1
git add 08_00_00_contracts/
git commit -m "feat(08_00): refactor interfaces to inherit from 04_CORE

- Refactor IParameterHost to inherit from IObservable + IMessageable
- Refactor IModulationTarget to inherit from IObservable
- Refactor IUIController to inherit from IObservable + IMessageable
- Update namespaces to audiolab::plugins
- Add inherited methods documentation"

# Fase 2
git commit -m "feat(08_00): add L4 framework and utilities"

# Fase 3
git commit -m "feat(08_00): add L5 framework and developer tools"

# Fase 4
git commit -m "feat(08_00): add tests and update documentation"

📞 Contacto & Ayuda

Si encuentras problemas: 1. Revisa CORE_MAPPING.md para ver ejemplos 2. Revisa interfaces ya refactorizadas (IPluginProcessor, IStateManager, IAudioEngine) 3. Consulta 04_CORE/04_01_core_interfaces/README.md para entender interfaces base

Estado: 📝 LISTO PARA IMPLEMENTACIÓN Última actualización: 2025-10-08 Estimación total: 10-14 horas (4 fases de 2.5-3.5h cada una)