# tonioseiler/craft-text-to-speech architecture

> Architecture diagram of the GitHub repository tonioseiler/craft-text-to-speech, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tonioseiler/craft-text-to-speech
- Repository: https://github.com/tonioseiler/craft-text-to-speech

## Overview

##### Main Components
- Craft CMS Core: Acts as the host environment where the plugin integrates.
- Plugin Entry/Registration: Although not explicitly listed as a separate file, the existence of the plugin files indicates that there is an entry point (via composer.json and the plugin manifests) that registers the plugin with Craft CMS.
- Controllers (src/controllers/TextToSpeechController.php): Handle incoming HTTP requests from the CMS control panel (for example, actions triggered on the entry edit page or in utilities).
- Behaviors (src/behaviors/TextToSpeechBehavior.php): Extend or modify the behavior of certain Craft elements to integrate text-to-speech functionality.
- Services (src/services/TextToSpeechService.php): Encapsulate core business logic for converting text to speech, interfacing with Google’s API, and managing audio generation.
- Jobs (src/jobs/GenerateTTSJob.php): Represent background processes that manage the asynchronous conversion of text to audio.
- Elements/Actions (src/elements/actions/GenerateAudio.php and DeleteAudio.php): Represent discrete actions available in the CMS (e.g., generating or deleting audio files).
- Models/Records (src/models/Settings.php and src/records/ProcessLogRecord.php): Store plugin settings (including API keys and voice configuration) and records of processing events.
- Migrations (src/migrations/Install.php and related migration scripts): Setup database structures like log tables that are used by the plugin.
- Templates (src/templates/*): Twig templates that provide the UI elements (like settings panels and utilities) for configuring plugin behavior within the Craft CMS control panel.
- Utilities (src/utilities/TextToSpeechUtility.php): Provide helper functions and utility operations across the plugin.

##### Out Relationships and Interactions
- That the Plugin Registration/Bootstrap connects Craft CMS to all the plugin’s components.
- The Service should then be depicted as interacting with Google Text-to-Speech API (implied by the README’s mention of using Google’s credentials and API) and returning the generated audio.
- A branch where Jobs (GenerateTTSJob) are dispatched for asynchronous processing of TTS requests.
- The Actions within the Elements (such as GenerateAudio and DeleteAudio) are invoked within the CMS and use the Service layer, reinforcing the separation of UI interactions from business logic.
- Link the Models/Settings and Records/ProcessLogRecord to the Database (set up via Migrations), showing how the plugin configuration and logs are persisted.
- Templates and Utilities as support layers that render the admin UI in Craft CMS, with the Templates presenting forms/settings and the Utility layer offering additional helper functions for the plugin.

##### Architectural Patterns
- Separation of Concerns: Different responsibilities are isolated in controllers, services, jobs, and templates.
- MVC Influences: While Craft CMS has its own architecture, notice how the Controllers, Models, and Templates work together to present and process data.
- Asynchronous Processing: Use of Jobs (GenerateTTSJob) supports offloading time-intensive TTS generation to background queues.
- Extensibility: Use of Elements, Behaviors, and Utility classes makes the system modular and enables easier extension or maintenance in future versions.

##### Technologies, Frameworks, and Libraries
- PHP 8.2 and Craft CMS 4.40.0+ are mandated by the project.
- Google Text-to-Speech API: The plugin relies on this external service for generating audio.
- Twig: Used for templating (as indicated by the Twig files in the templates directory).
- Composer: Manages dependencies and installation of the plugin.
- Additional tools (e.g., PHPStan, ECS) are referenced by configuration files (phpstan.neon, ecs.php), which may be used to maintain code quality and standards.

## Diagram (Mermaid)

```mermaid
flowchart TD
    craft["Craft CMS Core"]:::core
    pluginEntry["Plugin Entry/Registration"]:::business
    controller["Controllers\n(TextToSpeechController)"]:::business
    behavior["Behaviors\n(TextToSpeechBehavior)"]:::business
    service["Services\n(TextToSpeechService)"]:::business
    job["Jobs\n(GenerateTTSJob)"]:::business
    actions["Elements/Actions\n(GenerateAudio, DeleteAudio)"]:::business
    models["Models/Records\n(Settings, ProcessLogRecord)"]:::data
    migrations["Migrations\n(Install, create_table_logs)"]:::data
    templates["Templates\n(_edit-entry.twig, _settings.twig, _utilities.twig)"]:::presentation
    utilities["Utilities\n(TextToSpeechUtility)"]:::business
    googleAPI["Google Text-to-Speech API"]:::integration
    cmsUI["CMS UI Actions"]:::presentation

    %% Primary integration flow
    craft --> pluginEntry
    pluginEntry --> controller
    pluginEntry --> behavior
    pluginEntry --> service
    pluginEntry --> actions
    pluginEntry --> models
    pluginEntry --> migrations
    pluginEntry --> templates
    pluginEntry --> utilities

    %% CMS UI interactions
    cmsUI --> controller
    cmsUI --> templates

    %% Internal processing flow
    controller -->|"calls"| service
    service -->|"requests"| googleAPI
    service -->|"dispatches_async"| job
    actions -->|"invoke"| service
    service -->|"updates"| models
    migrations -->|"setup_DB"| models
    controller -->|"utilizes"| utilities
    service -->|"utilizes"| utilities

    %% Click Events
    click pluginEntry "https://github.com/tonioseiler/craft-text-to-speech/blob/main/composer.json"
    click pluginEntry "https://github.com/tonioseiler/craft-text-to-speech/blob/main/src/TextToSpeech.php"
    click controller "https://github.com/tonioseiler/craft-text-to-speech/blob/main/src/controllers/TextToSpeechController.php"
    click behavior "https://github.com/tonioseiler/craft-text-to-speech/blob/main/src/behaviors/TextToSpeechBehavior.php"
    click service "https://github.com/tonioseiler/craft-text-to-speech/blob/main/src/services/TextToSpeechService.php"
    click job "https://github.com/tonioseiler/craft-text-to-speech/blob/main/src/jobs/GenerateTTSJob.php"
    click actions "https://github.com/tonioseiler/craft-text-to-speech/blob/main/src/elements/actions/GenerateAudio.php"
    click actions "https://github.com/tonioseiler/craft-text-to-speech/blob/main/src/elements/actions/DeleteAudio.php"
    click models "https://github.com/tonioseiler/craft-text-to-speech/blob/main/src/models/Settings.php"
    click models "https://github.com/tonioseiler/craft-text-to-speech/blob/main/src/records/ProcessLogRecord.php"
    click migrations "https://github.com/tonioseiler/craft-text-to-speech/blob/main/src/migrations/Install.php"
    click migrations "https://github.com/tonioseiler/craft-text-to-speech/blob/main/src/migrations/m250305_092709_create_table_logs.php"
    click templates "https://github.com/tonioseiler/craft-text-to-speech/blob/main/src/templates/_edit-entry.twig"
    click templates "https://github.com/tonioseiler/craft-text-to-speech/blob/main/src/templates/_settings.twig"
    click templates "https://github.com/tonioseiler/craft-text-to-speech/blob/main/src/templates/_utilities.twig"
    click utilities "https://github.com/tonioseiler/craft-text-to-speech/blob/main/src/utilities/TextToSpeechUtility.php"

    %% Styles
    classDef core fill:#CCE5FF,stroke:#007BFF,stroke-width:2px;
    classDef business fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef data fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef presentation fill:#FFCDD2,stroke:#D32F2F,stroke-width:2px;
    classDef integration fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
```
