Generic Plugin Data Browser UI: Phase 7 Discussion

by Alex Johnson 51 views

This article delves into the Phase 7 development discussion surrounding a generic plugin data browser UI. We'll explore the goals, design principles, file modifications, API design, and acceptance criteria for this crucial project phase. This initiative aims to replace the existing dedicated transcription UI with a more versatile and extensible solution that can handle metadata from various plugins.

Parent Epic

This phase is an integral part of the larger initiative outlined in #229 - Extract Transcription to Plugin System, which focuses on modularizing the transcription functionality into a plugin system.

Goal: A Universal Plugin Data Viewer

The primary goal of Phase 7 is to create a generic plugin metadata viewer capable of displaying data from any plugin. This will replace the current, dedicated transcription UI, offering a more flexible and scalable solution. The new browser will be designed to work seamlessly with any plugin, ensuring that users can easily access and view metadata regardless of the plugin's specific function. This approach eliminates the need for separate UIs for each plugin, streamlining the user experience and simplifying maintenance.

Key benefits of this approach include:

  • Unified Interface: A single interface for viewing metadata from all plugins, enhancing usability and reducing complexity.
  • Extensibility: The system should easily accommodate new plugins without requiring UI modifications.
  • Maintainability: Centralizing the metadata viewing functionality simplifies maintenance and updates.
  • Efficiency: Users can quickly access and understand plugin data without navigating multiple interfaces.

Design Principles: Building a Flexible and Extensible System

The design of the generic plugin data browser UI is guided by several key principles to ensure its flexibility, extensibility, and usability. These principles focus on creating a system that can adapt to future needs and accommodate new plugins without requiring significant modifications.

  • JSON-Based Metadata Storage: Each plugin will store its metadata as a JSON object, keyed by the plugin name. This standardized format ensures consistency and facilitates easy parsing and display of data. The use of JSON allows for a hierarchical structure, accommodating complex metadata structures that may be required by different plugins.
  • Generic Data Display: The browser will display plugin data in a generic format, working for any file. This means the UI should not be tied to any specific plugin or data structure, ensuring it can handle diverse metadata formats. The generic display will typically involve presenting the data in a tabular format, with keys and values clearly labeled.
  • Extensibility by Design: The system should be extensible as new plugins are added, requiring no UI changes per plugin. This is crucial for long-term maintainability and scalability. The UI should dynamically adapt to new plugins, automatically displaying their metadata without any manual configuration.
  • Accessibility from File Details: Plugin data should be easily accessible from the file detail page. This ensures users can quickly view the metadata associated with a particular file without navigating to a separate section. Integrating the plugin data viewer into the file details page provides a contextual and convenient way to access plugin information.

Files to Delete: Removing Redundant Code

To pave the way for the generic plugin data browser, several dedicated transcription templates will be removed. This cleanup effort ensures that the codebase remains lean and focused on the new, unified approach.

Specific files slated for deletion include:

  • src/video_policy_orchestrator/server/ui/templates/transcriptions.html: This template is used for displaying a list of transcriptions and is no longer needed with the introduction of the generic plugin data browser.
  • src/video_policy_orchestrator/server/ui/templates/transcription_detail.html: This template provides a detailed view of a single transcription and will be replaced by the generic plugin data display.

By removing these files, the project eliminates redundant code and simplifies the codebase, making it easier to maintain and extend in the future.

Files to Create: Building the Generic Plugin Data Viewer

The core of Phase 7 involves creating a new template file that will serve as the foundation for the generic plugin metadata viewer. This template will dynamically display data from various plugins, providing a unified interface for accessing plugin-related information.

New file to be created:

  • src/video_policy_orchestrator/server/ui/templates/plugin_data.html: This file will contain the HTML template for the generic plugin metadata viewer. It will use Jinja2 templating to dynamically render plugin data in a structured and user-friendly format.

The plugin_data.html template will be designed to iterate through the plugin metadata and display it in a tabular format. This approach ensures that the data is presented in a clear and organized manner, making it easy for users to understand.

Example HTML Structure:

{% extends "base.html" %}
{% block content %}
<h1>Plugin Data: {{ file.filename }}</h1>

<div class="plugin-data-browser">
  {% for plugin_name, plugin_data in plugin_metadata.items() %}
  <div class="plugin-section">
    <h2>{{ plugin_name }}</h2>
    <table class="plugin-data-table">
      {% for key, value in plugin_data.items() %}
      <tr>
        <td class="key">{{ key }}</td>
        <td class="value">{{ value }}</td>
      </tr>
      {% endfor %}
    </table>
  </div>
  {% endfor %}
</div>
{% endblock %}

This template extends a base HTML template and defines a content block that displays the plugin data. It iterates through the plugin_metadata dictionary, which contains data for each plugin. For each plugin, it creates a section with the plugin name as a heading and a table to display the key-value pairs of the plugin data.

Files to Modify: Integrating the New Functionality

Several files will be modified to integrate the generic plugin data browser into the existing system. These modifications include removing transcription-specific routes and adding new routes for accessing plugin data. Additionally, the file detail page will be updated to include a section for displaying plugin metadata.

Key modifications will be made to:

  • src/video_policy_orchestrator/server/ui/routes.py: This file contains the route definitions for the web application. Modifications will include removing routes related to transcriptions and adding new routes for accessing plugin data.
  • src/video_policy_orchestrator/server/ui/templates/file_detail.html: This template displays the details of a file. It will be updated to include a section for displaying plugin metadata.

src/video_policy_orchestrator/server/ui/routes.py

The modifications to routes.py will involve:

  • Removing Transcription-Specific Routes: The DELETE /transcriptions handler, DELETE /transcriptions/{id} handler, and DELETE /api/transcriptions handler will be removed as they are no longer needed.
  • Adding Generic Plugin Data Routes: New routes will be added to handle requests for plugin data. These routes will include:
    • GET /files/{file_id}/plugins: This route will render the plugin data page for a specific file.
    • GET /api/files/{file_id}/plugin-data: This route will return all plugin data for a file in JSON format.
    • GET /api/files/{file_id}/plugin-data/{plugin}: This route will return data for a specific plugin in JSON format.
    • GET /api/plugins: This route will return a list of registered plugins.
    • GET /api/plugins/{name}/files: This route will return a list of files with data from a specific plugin.

Example Route Handlers:

# GET /files/{file_id}/plugins - Plugin data page for file
async def file_plugin_data_handler(request: web.Request) -> web.Response:
    file_id = int(request.match_info["file_id"])
    # Load file and plugin_metadata JSON
    # Render plugin_data.html template
    ...

# GET /api/files/{file_id}/plugin-data - All plugin data for file
async def api_file_plugin_data_handler(request: web.Request) -> web.Response:
    file_id = int(request.match_info["file_id"])
    # Return JSON: {"whisper-transcriber": {...}, "radarr-metadata": {...}}
    ...

# GET /api/files/{file_id}/plugin-data/{plugin} - Single plugin's data
async def api_file_plugin_data_single_handler(request: web.Request) -> web.Response:
    file_id = int(request.match_info["file_id"])
    plugin = request.match_info["plugin"]
    # Return JSON for specific plugin
    ...

# GET /api/plugins - List registered plugins
async def api_plugins_list_handler(request: web.Request) -> web.Response:
    # Return list of registered plugins from PluginRegistry
    ...

# GET /api/plugins/{name}/files - Files with data from plugin
async def api_plugin_files_handler(request: web.Request) -> web.Response:
    plugin_name = request.match_info["name"]
    # Query files that have plugin_metadata containing this plugin
    ...

src/video_policy_orchestrator/server/ui/templates/file_detail.html

The file_detail.html template will be updated to include a section for displaying plugin metadata. This section will be conditionally rendered based on the presence of plugin metadata for the file.

Example Plugin Metadata Section:

{% if plugin_metadata %}
<section class="plugin-metadata">
  <h2>Plugin Data</h2>
  <a href="/files/{{ file.id }}/plugins">View All Plugin Data</a>
  
  {% for plugin_name, data in plugin_metadata.items() %}
  <div class="plugin-summary">
    <strong>{{ plugin_name }}</strong>: {{ data | length }} fields
  </div>
  {% endfor %}
</section>
{% endif %}

This section includes a heading, a link to the full plugin data view, and a summary of each plugin's data. The summary displays the plugin name and the number of fields in its metadata.

API Design: Providing Access to Plugin Data

The API design for Phase 7 includes several endpoints that provide access to plugin data. These endpoints allow clients to retrieve plugin data for specific files, list registered plugins, and find files associated with a particular plugin. The API is designed to be RESTful, using standard HTTP methods and JSON for data exchange.

Key API Endpoints:

Endpoint Description
GET /api/files/{file_id}/plugin-data Retrieves all plugin data for a specific file.
GET /api/files/{file_id}/plugin-data/{plugin} Retrieves data for a specific plugin for a given file.
GET /api/plugins Lists all registered plugins.
GET /api/plugins/{name}/files Retrieves a list of files that have data from a specific plugin.

These endpoints provide a comprehensive API for accessing plugin data, allowing clients to easily retrieve and display plugin-related information.

Acceptance Criteria: Ensuring a Successful Implementation

To ensure the successful implementation of Phase 7, several acceptance criteria have been defined. These criteria cover various aspects of the project, including the deletion of old files, the creation of new files, the modification of existing files, and the functionality of the API endpoints.

Key Acceptance Criteria:

  • [ ] Dedicated transcription templates deleted
  • [ ] /transcriptions routes removed
  • [ ] Generic plugin_data.html template created
  • [ ] Plugin data section added to file detail page
  • [ ] /api/files/{id}/plugin-data endpoint returns all plugin data
  • [ ] /api/plugins endpoint lists registered plugins
  • [ ] UI displays plugin data for whisper-transcriber
  • [ ] UI displays plugin data for radarr-metadata (if present)
  • [ ] No JavaScript changes needed to add new plugins

These criteria ensure that the new generic plugin data browser is fully functional and meets the design goals of the project. Meeting these criteria will result in a more flexible, extensible, and maintainable system for managing plugin data.

Dependencies: Understanding Project Dependencies

Phase 7 has a dependency on Phase 5: CLI Removal + Cleanup (#234). This dependency ensures that the codebase is cleaned up and ready for the integration of the new plugin data browser.

Parallelization: Optimizing Development Efforts

Phase 7 can be parallelized with Phase 6: Plugin SDK Enhancement. This parallelization allows development teams to work on different aspects of the project simultaneously, accelerating the overall development process. By working on the Plugin SDK Enhancement in parallel, the project can ensure that the necessary tools and infrastructure are in place to support the generic plugin data browser.

Conclusion

Phase 7 represents a significant step towards a more flexible and extensible plugin system. By replacing the dedicated transcription UI with a generic plugin data browser, the project aims to provide a unified interface for accessing metadata from various plugins. This approach not only simplifies the user experience but also makes the system more maintainable and scalable. The successful completion of Phase 7 will pave the way for future plugin development and integration. For more information on plugin development and best practices, visit a trusted website like https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Plugins.