# nhovratov/mask-to-content-blocks architecture
> Architecture diagram of the GitHub repository nhovratov/mask-to-content-blocks, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/nhovratov/mask-to-content-blocks
- Repository: https://github.com/nhovratov/mask-to-content-blocks
## Overview
1. This repository is a TYPO3 extension whose only job is to migrate existing Mask content elements to TYPO3 Content Blocks. It is not a site feature extension; it is a one-shot migration utility that runs inside a TYPO3 installation.
2. The main entry point is a TYPO3 CLI command, `mask-to-content-blocks:migrate`, implemented in `Classes/Command/MaskToContentBlocksCommand.php`. The command is the orchestration layer: it reads the currently loaded Mask definitions and generates Content Block definitions.
3. The migration writes the generated Content Blocks back into the same extension context where the Mask elements already live. That makes the tool a transformation bridge between two TYPO3 content-type systems rather than a standalone generator.
4. A dedicated service, `Classes/Service/SvgIconService.php`, handles SVG icon-related processing during generation. This suggests the migration preserves or converts icon assets as part of the Content Block output, which is a separate concern from the core element conversion logic.
5. Dependency wiring is handled through TYPO3’s service container in `Configuration/Services.yaml`. That file registers the command and service classes for injection, so the architecture is based on framework-managed services rather than direct instantiation.
6. The system boundary is very clear: it depends on an existing TYPO3 v13 runtime with Mask already installed and populated. The extension does not store or manage content itself; it transforms configuration/code that already exists in the TYPO3 instance.
7. The output side targets TYPO3 Content Blocks, the official TYPO3 mechanism for defining content types. So the migration path is: Mask element metadata in TYPO3 → command execution → generated Content Block definitions → manual verification and cleanup.
8. The repository also contains a `.github/workflows/publish.yml`, indicating automated release/publishing for the extension package. This affects distribution, not runtime behavior.
9. `.ddev/config.yaml` shows the project is set up for local TYPO3 development in DDEV, which matters mainly for spinning up the required TYPO3 environment and testing the migration command.
10. Operationally, the README describes a manual post-migration boundary: after generation, Mask and this extension can be removed, but TypoScript overrides and frontend/backend previews may need adjustment. That means the tool handles structure conversion, while presentation-layer validation remains outside its scope.
11. In architectural terms, this repo is a small, command-driven migration adapter with one primary workflow and one supporting service, sitting between two TYPO3 content-modeling systems.
Main entry points: [`Classes/Command/MaskToContentBlocksCommand.php`](https://github.com/nhovratov/mask-to-content-blocks/blob/main/Classes/Command/MaskToContentBlocksCommand.php) (Migration Command), [`Configuration/Services.yaml`](https://github.com/nhovratov/mask-to-content-blocks/blob/main/Configuration/Services.yaml) (Service Wiring), [`.github/workflows/publish.yml`](https://github.com/nhovratov/mask-to-content-blocks/blob/main/.github/workflows/publish.yml) (Publish Workflow), [`Classes/Service/SvgIconService.php`](https://github.com/nhovratov/mask-to-content-blocks/blob/main/Classes/Service/SvgIconService.php) (SVG Icon Service)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_runtime["TYPO3 Migration Runtime"]
node_command["Migration Command
TYPO3 CLI command"]
node_mask_source["Mask Definitions
existing TYPO3 config"]
node_content_blocks["Content Blocks
generated TYPO3 output"]
node_svg_service["SVG Icon Service
support service
[SvgIconService.php]"]
node_typo3_runtime[("TYPO3 v13
host runtime")]
node_mask_extension["Mask Extension
dependency"]
node_migration_bridge{{"Migration Bridge
transform flow"}}
node_manual_review(("Post-check
human validation"))
end
subgraph group_tooling["Project Tooling"]
node_ddev_env["DDEV Setup
local dev env
[config.yaml]"]
node_publish_workflow["Publish Workflow
release automation
[publish.yml]"]
node_readme["Usage Guide
documentation
[README.md]"]
end
subgraph group_package["Extension Package"]
node_service_container["Service Wiring
TYPO3 DI config
[Services.yaml]"]
node_extension_meta["Extension Meta
TYPO3 package metadata
[ext_emconf.php]"]
node_composer_pkg["Composer Package
package manifest
[composer.json]"]
end
node_service_container -->|"injects"| node_command
node_service_container -->|"injects"| node_svg_service
node_typo3_runtime -->|"loads"| node_service_container
node_typo3_runtime -->|"executes"| node_command
node_mask_extension -->|"provides"| node_mask_source
node_command -->|"reads"| node_mask_source
node_command -->|"drives"| node_migration_bridge
node_mask_source -->|"input"| node_migration_bridge
node_svg_service -->|"supports"| node_migration_bridge
node_migration_bridge -->|"generates"| node_content_blocks
node_content_blocks -.->|"validated by"| node_manual_review
node_readme -.->|"documents"| node_manual_review
node_ddev_env -->|"hosts"| node_typo3_runtime
node_publish_workflow -->|"packages"| node_composer_pkg
node_publish_workflow -->|"packages"| node_extension_meta
node_composer_pkg -->|"declares"| node_extension_meta
click node_command "https://github.com/nhovratov/mask-to-content-blocks/blob/main/Classes/Command/MaskToContentBlocksCommand.php"
click node_svg_service "https://github.com/nhovratov/mask-to-content-blocks/blob/main/Classes/Service/SvgIconService.php"
click node_service_container "https://github.com/nhovratov/mask-to-content-blocks/blob/main/Configuration/Services.yaml"
click node_ddev_env "https://github.com/nhovratov/mask-to-content-blocks/blob/main/.ddev/config.yaml"
click node_publish_workflow "https://github.com/nhovratov/mask-to-content-blocks/blob/main/.github/workflows/publish.yml"
click node_extension_meta "https://github.com/nhovratov/mask-to-content-blocks/blob/main/ext_emconf.php"
click node_composer_pkg "https://github.com/nhovratov/mask-to-content-blocks/blob/main/composer.json"
click node_readme "https://github.com/nhovratov/mask-to-content-blocks/blob/main/README.md"
classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_command,node_mask_source,node_content_blocks,node_svg_service,node_typo3_runtime,node_mask_extension,node_migration_bridge,node_manual_review toneBlue
class node_ddev_env,node_publish_workflow,node_readme toneAmber
class node_service_container,node_extension_meta,node_composer_pkg toneMint
```
## Components
### TYPO3 Migration Runtime
Executed inside an existing TYPO3 v13 installation with Mask installed and populated.
- [Migration Command](https://github.com/nhovratov/mask-to-content-blocks/blob/main/Classes/Command/MaskToContentBlocksCommand.php): TYPO3 CLI command · Orchestrates the migration workflow from Mask definitions to Content Blocks. · `Classes/Command/MaskToContentBlocksCommand.php`
- **Mask Definitions**: existing TYPO3 config · Loaded Mask content-element metadata that serves as the input to migration.
- **Content Blocks**: generated TYPO3 output · Generated content-type definitions written back into the extension context.
- [SVG Icon Service](https://github.com/nhovratov/mask-to-content-blocks/blob/main/Classes/Service/SvgIconService.php): support service · Processes SVG icon assets as part of the generation flow. · `Classes/Service/SvgIconService.php`
- **TYPO3 v13**: host runtime · Required execution environment that provides the command framework and extension runtime.
- **Mask Extension**: dependency · Pre-existing extension whose content elements are migrated.
- **Migration Bridge**: transform flow · Converts Mask element metadata into Content Block definitions.
- **Post-check**: human validation · Manual verification and cleanup after generation, including presentation-layer adjustments.
### Project Tooling
Local development and release automation around the migration utility.
- [DDEV Setup](https://github.com/nhovratov/mask-to-content-blocks/blob/main/.ddev/config.yaml): local dev env · Local TYPO3 development environment for running the migration command. · `.ddev/config.yaml`
- [Publish Workflow](https://github.com/nhovratov/mask-to-content-blocks/blob/main/.github/workflows/publish.yml): release automation · GitHub Actions workflow for packaging and publishing the extension. · `.github/workflows/publish.yml`
- [Usage Guide](https://github.com/nhovratov/mask-to-content-blocks/blob/main/README.md): documentation · Explains the migration boundary, workflow, and post-migration responsibilities. · `README.md`
### Extension Package
TYPO3 extension metadata and dependency wiring.
- [Service Wiring](https://github.com/nhovratov/mask-to-content-blocks/blob/main/Configuration/Services.yaml): TYPO3 DI config · Registers the command and service for framework-managed injection. · `Configuration/Services.yaml`
- [Extension Meta](https://github.com/nhovratov/mask-to-content-blocks/blob/main/ext_emconf.php): TYPO3 package metadata · Extension declaration and package metadata for TYPO3/composer distribution. · `ext_emconf.php`
- [Composer Package](https://github.com/nhovratov/mask-to-content-blocks/blob/main/composer.json): package manifest · Composer metadata and dependencies for installation and distribution. · `composer.json`
## Connections
- Service Wiring → Migration Command: injects · Registers the CLI command as a framework service.
- Service Wiring → SVG Icon Service: injects · Registers the SVG processing service for dependency injection.
- TYPO3 v13 → Service Wiring: loads · TYPO3 boots the service container configuration.
- TYPO3 v13 → Migration Command: executes · Runs the migration command inside the TYPO3 CLI runtime.
- Mask Extension → Mask Definitions: provides · Supplies the existing Mask definitions used as migration input.
- Migration Command → Mask Definitions: reads · Loads current Mask metadata before generation.
- Migration Command → Migration Bridge: drives · Coordinates the conversion workflow.
- Mask Definitions → Migration Bridge: input · Provides the source content-element structure.
- SVG Icon Service → Migration Bridge: supports · Handles SVG icon-related processing during generation.
- Migration Bridge → Content Blocks: generates · Writes Content Block definitions into the extension context.
- Content Blocks → Post-check: validated by · Requires manual verification and cleanup after generation.
- Usage Guide → Post-check: documents · Describes post-migration adjustments and boundaries.
- DDEV Setup → TYPO3 v13: hosts · Provides a local environment for running TYPO3 and the command.
- Publish Workflow → Composer Package: packages · Automates extension release/publishing.
- Publish Workflow → Extension Meta: packages · Uses extension metadata during distribution.
- Composer Package → Extension Meta: declares · Package metadata and TYPO3 extension metadata define installability.