architecture design proposal.md

@@ -13,6 +13,16 @@ This document describes proposals for the evolvment of the [WordPress ActivityPu
 # Terms used 
 The following terms are used:
 
+## Content related
+
+- **post type:** Post type and custom post types within WordPress
+- **Object Type:** ActivityPub [object type](https://www.w3.org/TR/activitystreams-vocabulary/#object-types)
+- **Transformers:** a piece of code that converts items of particular WordPress post types to an ActivityPub object. For example a transformer that can transform:
+    - every post type to a `Note`
+    - `post` or `page` to `Note`, `Article`, `Image`, `Audio` or `Article` depending on the [post-format](https://wordpress.org/documentation/article/post-formats/)
+    - `tribe_events` (Event post the of [The Event Calendar](https://wordpress.org/plugins/the-events-calendar/)) to `Event`
+    - `podcast` (Podcast post of [Podlove Podcast Publisher](https://github.com/podlove/podlove-publisher)) to `PodcastEpisode` as ([proposed and implemented by Castopod](https://code.castopod.org/adaures/castopod/-/blob/main/app/Libraries/PodcastEpisode.php))
+
 ## Actor related
 
 - **Actors:** ActivityPub [Actor Objects](https://www.w3.org/TR/activitypub/#actor-objects)
@@ -24,17 +34,6 @@ The following terms are used:
     - custom definitions → custom actor types
 - **Mapping:** Which WordPress actor types are actually are mapped to any ActivityPub actors at all and to which one.
 
-## Content related
-
-- **post type:** Post type and custom post types within WordPress
-- **Object Type:** ActivityPub [object type](https://www.w3.org/TR/activitystreams-vocabulary/#object-types)
-- **Transformers:** a piece of code that converts items of a particular WordPress post type to an ActivityPub object of (a) specified type(s). For example a transformer that can transform:
-    - `post` to a `Note`
-    - `post` to a `Article`
-    - `post` to `Note`, `Article`, `Image`, `Audio` or `Article` depending on the [post-format](https://wordpress.org/documentation/article/post-formats/)
-    - `tribe_events` (Event post the of [The Event Calendar](https://wordpress.org/plugins/the-events-calendar/)) to `Event`
-    - `podcast` (Podcast post of [Podlove Podcast Publisher](https://github.com/podlove/podlove-publisher)) to `PodcastEpisode` as ([proposed and implemented by Castopod](https://code.castopod.org/adaures/castopod/-/blob/main/app/Libraries/PodcastEpisode.php))
-
 ## General
 
 - **publish/dispatch:** Sending a `Create`, `Update` or `Announce` [Activity](https://www.w3.org/TR/activitypub/#create-activity-outbox).
@@ -57,9 +56,11 @@ The WordPress ActivityPub plugin
 
 # Goals
 
-Our primary goal is to make it possible that events created within an event plugin can federate properly as an ActivityPub object with Type `Event` along with all the meta-data belonging to the event, as found in common ActivityPub implementations, e.g. of Mobilizon, in order to ensure maximum compatibly between those services.
+## Goals of the WordPress Event Fedeartion project
+The event federations project goal is make it possible that events created within an event plugin can federate properly as an ActivityPub object with Type `Event` along with all the meta-data belonging to the event, as found in common ActivityPub implementations, e.g. of Mobilizon, in order to ensure maximum compatibly between those services.
 
-Nevertheless, we see a lot of other cases that can benefit, if we achieve this using a modularized approach as proposed below. The following list indicates examples what might be those other benefits:
+## Tangential Objectives:
+Nevertheless, we see a lot of other cases that can benefit, if the primary goals of the event federation project are achieved this using a modularized approach as proposed below. The following list indicates examples what might be those other benefits:
 - Other types of content get federated in a more feature rich way:
   - `PodcastEpisode` [as proposed by CastoPod](https://code.castopod.org/adaures/castopod/-/blob/main/app/Libraries/PodcastEpisode.php)
   - `Question`
@@ -82,32 +83,24 @@ The admin user interface in v1.0.0 lets one choose to which object type all post
 
 ### Proposal
 
-Every public WordPress post type may be transformed (have different transformers available) may convert it to an ActivityPub object. Transformations that are not 
-available for a given post type are greyed out in the user interface:
+All publicly accessible WordPress post types can become active for ActivityPub federation when selecting a transformer available for the relevant post type. The transformer determines the target ActivityPub object type, which can vary depending on variables like the post type or post format. If there is no specific transformer available for a given post type, it cannot be assigned through the user interface.
 
-|                   | Note | Article | Page | Event |
-| ----------------- |:----:|:-------:|:----:|:-----:|
-| **post**          | X    | O       | O    | -     |
-| **page**          | O    | X       | O    | -     |
-| **tribe_events**  | O    | -       | -    | X     |
+|                   | Note | Post-Format | The Events Calendar Transformer | Custom Event Transformer |
+| ----------------- |:----:|:-----------:|:-------------------------------:|:------------------------:|
+| **post**          | X    | O           | -                               | -                        |
+| **page**          | O    | O           | -                               | -                        |
+| **tribe_events**  | O    | -           | X                               | O                        |
+| **custom_event**  | O    | -           | -                               | O                        |
 | **...**           | O    | -           | -                               | -                        |
 
-**x:** ActivityPub object types  
-**y:** WordPress post types  
+**x:** Available transformers
+**y:** Public and non-password protected WordPress post types
+**Note:** Only one or zero selections can be made in each row.
 
 - For any custom post type, if there is a custom transformer registered, indicate that one should be selected as default (or select it right ahead?).
 - Should not differ too much from the current view: Maybe completely hide the current activity object type part of the settings and only show the buttons for `enable` and `disable` and move the transformer table to an advanced settings page.
-- Maybe make the tables more advanced and cleary show the origin of the transformer (built-in, etc.) and maybe a Pop-Up with a description.
+- Maybe make the tables more advanced and cleary show the origin of the transformer (built-in, etc.) and maybe a Pop-Up with a description, or even a link to a configuration page of the transformer.
 
-### Problems
-
-- If two transformers with the same source and target are installed, then we have two possibilities:
-  1. A dropdown menu is displayed to select one of the transformers.
-  2. Adding another column and maybe add indicators where the transformer comes from (e.g. `builtin`, `custom` or showing the source)
-
-- Should a transformer be always a many-to-one relationship or may it be a many-to-many one.
-
-- Highly unlikely: Do we really want to manage which transformers apply to what directly or do users prefer a setting like "let a certain plugin take care of this post type"? Then further configuration would have to be managed by the other plugins.
 
 ## Backend
 
@@ -141,7 +134,7 @@ A solution could be to define a transformer interface and let the transformers b
 ```php
 interface Transformer {
     public function get_supported_post_types(): array;
-    public function get_target_activitypub_object_type(): string;
+    public function get_transformer_info(): string;
     public function to_object(WP_Post $post);
     ....
 }
@@ -151,9 +144,10 @@ Use WordPress's hook system or a public API function to let other plugins regist
 
 **Problem:** With the design above the transformer does a lot and leaves a lot of responsibility to the developer implementing it.
 
-Possible alternatives and solutions:
+**Possible alternatives and solutions:**
+
 - The ActivityPub plugin could provide reusable Traits for common tasks.
-- The ActivityPub plugin provides an even more height level framework for adding transformers. For example for events the ActivityPub plugin could provide a built-in transformer to the object type `Event` which only needs a mapping (might make things harder, instead of making them easier). See Appendix.
+- Highly unlikely: The ActivityPub plugin provides an even more height level framework for adding transformers. For example for events the ActivityPub plugin could provide a built-in transformer to the object type `Event` which only needs a mapping (might make things harder, instead of making them easier). See Appendix.
 - Don't use an interface with implementations, (miss)use class extensions.