diff --git a/docs/badges/prop_rewrite_entities.rst b/docs/badges/prop_rewrite_entities.rst index d8ac0cf..b831db2 100644 --- a/docs/badges/prop_rewrite_entities.rst +++ b/docs/badges/prop_rewrite_entities.rst @@ -1,6 +1,6 @@ .. _prop_rewrite_entities: -Proposed Entities +Entities involved ==== Let us dive deep into the entities that would come together to make the Fedora diff --git a/docs/badges/prop_rewrite_interactions.rst b/docs/badges/prop_rewrite_interactions.rst index fe65cee..216ee1f 100644 --- a/docs/badges/prop_rewrite_interactions.rst +++ b/docs/badges/prop_rewrite_interactions.rst @@ -1,6 +1,6 @@ .. _prop_rewrite_interactions: -Proposed Interactions +Interactions possible ==== The interactions between the previously mentioned entities would dictate the @@ -12,113 +12,230 @@ the top of the aforementioned joining lines. Internal-only interactions ---- -Interactions involving only internal entities are termed in this context as +Interactions involving only internal entities are termed, in this context, as internal-only interactions. .. image:: ../_static/badges-proposed-architecture.png :target: ../_images/badges-proposed-architecture.png -**AA** - 1. Defines the interaction between entities, Accolades CLI and Accolades - API. - 2. Accolades CLI can help abstract reading, creating, changing and deleting - of badge related assets or information with the help of the endpoints - that the Accolades API provides. - 3. This interaction causes DA and CA interactions to take place, as the data - requested is read from and data modified is changed into the Database and - Collection entities. For eg. fetching information about the badges - awarded to a certain user from the Database entity (DA) and automating - adding new badges with the awarding conditions to the Collection entity - (CA). - 4. This interaction affects LA and MA interactions as changes made to the - Accolades API would affect how it reacts to the actions made by the - Liberation and Message Consumer entities. For eg. new badges added into - the Collection entity might show up on the catalog of the Liberation - entity (LA) and the awarding condition added to the Collection entity - would change the way the Message Consumer behaves in awarding badges - (MA). +AA +^^^^ -**LA** - 1. Defines the interaction between entities, Liberation and Accolades API. - 2. Liberation provides an interactive web interface for abstracting reading, - creating, changing, awarding and deleting of badge related assets or - information with the help of the endpoints that the Accolades API - provides. - 3. This interaction causes DA and CA interactions to take place, as the data - requested is read from and data modified is changed into the Database and - Collection entities. For eg. displaying the leaderboard of the top 100 - community members by fetching it from the Database entity (DA) and - adding new badges with the awarding conditions to the Collection entity - (CA). - 4. This interaction affects AA and MA interactions as changes made to the - Accolades API would affect how it reacts to the actions made by the - Accolades CLI and Message Consumer entities. For eg. newly awarded badge - from Liberation would show up on the Accolades CLI for the user querying - about that information (AA) and the awarding condition added to the - Collection entity would change the way the Message Consumer behaves in - awarding badges (MA). +1. Defines the interaction between entities, Accolades CLI and Accolades API. +2. Accolades CLI can help abstract reading, creating, changing and deleting of + badge related assets or information with the help of the endpoints that the + Accolades API provides. +3. This interaction causes DA and CA interactions to take place, as the data + requested is read from and data modified is changed into the Database and + Collection entities. For eg. fetching information about the badges awarded + to a certain user from the Database entity (DA) and automating adding new + badges with the awarding conditions to the Collection entity (CA). +4. This interaction affects LA and MA interactions as changes made to the + Accolades API would affect how it reacts to the actions made by the + Liberation and Message Consumer entities. For eg. new badges added into the + Collection entity might show up on the catalog of the Liberation entity (LA) + and the awarding condition added to the Collection entity would change the + way the Message Consumer behaves in awarding badges (MA). -**DA** - 1. Defines the interaction between entities, Database and Accolades API. - 2. Database stores the information of the achievements made by the - community members by their recordable actions within the Fedora Project - community, along with the metadata of when the badges were awarded etc. - 3. This interaction cannot be directly triggered and can only happen as a - cause of LA, AA and MA interactions. As a result, this interaction does - not become a causative agent for any other interaction. For eg. awarding - a user with a badge from the Liberation entity would lead to changes - made in the Database entity (LA), querying about the badges achieved - by a user in the Accolades CLI entity requires reading information from - the Database entity (AA) and conditioned awards made from the Message - Consumer entity would be reflected on the Database entity (MA). - 4. This interaction affects only those interactions, that cause it to happen - in the first place. This can be explained as the consequences of the - aforementioned example interactions - for eg. Liberation entity would be - able to see the badge under the username that it was awarded to recently - (LA) and Accolades CLI entity would be able to retrieve the information - it requested for (AA) but the MA interaction would stay unaffected. +LA +^^^^ -**** +1. Defines the interaction between entities, Liberation and Accolades API. +2. Liberation provides an interactive web interface for abstracting reading, + creating, changing, awarding and deleting of badge related assets or + information with the help of the endpoints that the Accolades API provides. +3. This interaction causes DA and CA interactions to take place, as the data + requested is read from and data modified is changed into the Database and + Collection entities. For eg. displaying the leaderboard of the top 100 + community members by fetching it from the Database entity (DA) and adding + new badges with the awarding conditions to the Collection entity (CA). +4. This interaction affects AA and MA interactions as changes made to the + Accolades API would affect how it reacts to the actions made by the + Accolades CLI and Message Consumer entities. For eg. newly awarded badge + from Liberation would show up on the Accolades CLI for the user querying + about that information (AA) and the awarding condition added to the + Collection entity would change the way the Message Consumer behaves in + awarding badges (MA). + +DA +^^^^ + +1. Defines the interaction between entities, Database and Accolades API. +2. Database stores the information of the achievements made by the community + members by their recordable actions within the Fedora Project community, + along with the metadata of when the badges were awarded etc. +3. This interaction cannot be directly triggered and can only happen as a cause + of LA, AA and MA interactions. As a result, this interaction does not become + a causative agent for any other interaction. For eg. awarding a user with a + badge from the Liberation entity would lead to changes made in the Database + entity (LA), querying about the badges achieved by a user in the Accolades + CLI entity requires reading information from the Database entity (AA) and + conditioned awards made from the Message Consumer entity would be reflected + on the Database entity (MA). +4. This interaction affects only those interactions, that cause it to happen in + the first place. This can be explained as the consequences of the + aforementioned example interactions - for eg. Liberation entity would be + able to see the badge under the username that it was awarded to recently + (LA) and Accolades CLI entity would be able to retrieve the information it + requested for (AA) but the MA interaction would stay unaffected. + +CA +^^^^ + +1. Defines the interaction between entities, Collection and Accolades API. +2. Collection entity stores the badge assets (artworks, badge rules, awarding + conditions etc.) that the Accolades API can read content from, add new + badges, change/update and delete/remove existing ones. +3. This interaction cannot be directly triggered and can only happen as a + cause of internal interactions like LA, AA, DA and MA as well as external + interactions like changes made into the Collection entity by external + entities like Repository Members etc. For eg. adding new badges for + distribution using the Liberation entity (LA) and doing so using the + Accolades CLI (AA) would lead to changes in the Collection entity, changes + in the database due to the awarding of badges would require reading + information from the Collection entity (DA) and rules on how the Message + Consumer entity would award badges would be described by the conditions + mentioned in the Collection entity (MA). +4. This interaction affects only those interactions, that cause it to happen + in the first place. This can be explained as the consequences of the + aforementioned examples - for eg. addition of new badge for distribution + would cause it to be accessible on Liberation entity (LA) and on Accolades + API (AA), Message Consumer entity would now have new rules as a result to + changes in the Collection entity (MA) but the DA interaction would stay + unaffected. + +MA +^^^^ + +1. Defines the interaction between entities, Messages Consumer and Accolades + API. +2. Message Consumer listens in to the Fedora Messaging bus and compares the + messages against the awarding conditions, and when the said condition is + satisfied, it makes a request to the Accolades API to award an external + entity, a certain Community User with the relevant badge. +3. This interaction cannot be directly triggered and can only happen as a + cause of internal interactions like CM and CA. For eg. any new additions + made to the Collection entity would change the way the Message Consumer + entity checks for conditions for badges (CA) and the Message Consumer would + read the content regarding the badges from the Collection entity (CM). +4. This interaction affects DA, LA and AA interactions as changes made to the + Accolades API entity by the Messages Consumer entity would affect how it + reacts to the actions made into the Database entity, by the Liberation + entity and Message Consumer entities. For eg. badges awarded automatically + by the Messsage Consumer entity's interaction would cause a change to be + made on the Database entity (DA) and lead them to be visible on the + Liberation entity (LA) and accessible on the Accolades CLI entity (AA). + +CM +^^^^ + +1. Defines the interaction between entities, Collection and Message Consumer. +2. In order for the Message Consumer to obtain badge assets (artworks, rules, + awarding conditions etc.), it has to interact with the Collection entity. +3. This interaction cannot be directly triggered and can only happen as a cause + of internal interactions like CA and external interactions like Repository + Members making changes to the Collection entity. For eg. internal changes + made to the Collection entity and external changes made to the Collection + entity (for eg. by the Repository Members) would change the way the Messages + Consumer entity would check for awarding conditions for the badges (CA). +4. The interaction does not directly affect any other internal interaction but + can indirectly affect interactions like MA. For eg. changes in the + Collection entity can change the frequency and cases when the Messages + Consumer would interact with the Accolades API (MA). External-Internal interactions ---- -**Accolades API** interacting with external entities +Interactions involving both external and internal entities are termed, in this +context, as external-internal interactions. + +Accolades API interacting with external entities +^^^^ .. image:: ../_static/badges-proposed-api-ext-interactions.png :target: ../_images/badges-proposed-api-ext-interactions.png +1. Service Admins [Access Level IV] would have a direct control on the + deployment environments (staging, development, production etc.). -**Accolades CLI** interacting with external entities +Accolades CLI interacting with external entities +^^^^ .. image:: ../_static/badges-proposed-cli-ext-interactions.png :target: ../_images/badges-proposed-cli-ext-interactions.png +1. Service Admins [Access Level IV] would have a direct control on the + deployment environments (staging, development, production etc.). +2. Badge Owners [Access Level III] would have an elevated access to the + Accolades API entity using the Accolades CLI entity where they can + automate addition of new badges for distribution within the community, + create, access, modify and remove the badges that they "own" (not the ones + that they "have been awarded"). +3. Community Users [Access Level I] would have a limited access to the + Accolades API entity using the Accolades CLI entity where they can view + the badges received by them (and by others), access the catalog of + available badges, view leaderboards and other such similar tasks. -**Liberation** interacting with external entities +Liberation interacting with external entities +^^^^ .. image:: ../_static/badges-proposed-web-ext-interactions.png :target: ../_images/badges-proposed-web-ext-interactions.png +1. Service Admins [Access Level IV] would have a direct control on the + deployment environments (staging, development, production etc.). +2. Badge Owners [Access Level III] would have an elevated access to the + Accolades API entity using the Liberation entity where they can manually + add new badges for distribution within the community, create, access, + modify and remove the badges that they "own" (not the ones that they "have + been awarded"). +3. Community Users [Access Level I] would have a limited access to the + Accolades API entity using the Liberation entity where they can view the + badges received by them (and by others), access the catalog of available + badges, view leaderboards and other such similar tasks. -**Collection** interacting with external entities +Collection interacting with external entities +^^^^ .. image:: ../_static/badges-proposed-col-ext-interactions.png :target: ../_images/badges-proposed-col-ext-interactions.png +1. Repository Members [Access Level II] would have complete access to the + Collection entity where they can access, create, modify and remove badge + assets (i.e. artworks, badge rules, awarding conditions etc.). As the + access is unrestricted, they have access to the assets created by someone + else too, which belong to the entity. -**Database** interacting with external entities +Database interacting with external entities +^^^^ .. image:: ../_static/badges-proposed-dtb-ext-interactions.png :target: ../_images/badges-proposed-dtb-ext-interactions.png +1. Service Admins [Access Level IV] would have a direct control on the + deployment environments (staging, development, production etc.). -**Messages consumer** interacting with external entities +Messages Consumer interacting with external entities +^^^^ .. image:: ../_static/badges-proposed-msg-ext-interactions.png :target: ../_images/badges-proposed-msg-ext-interactions.png +1. Service Admins [Access Level IV] would have a direct control on the + deployment environments (staging, development, production etc.). External-only interactions ---- + +Interactions involving only external entities are termed, in this context, as +external-only interactions. + +1. Badge Owners [Access Level III] might need to interact with Repository + Members [Access Level II] for assistance with changing badge assets in + the Collection entity. + +2. Community User [Access Level I] might need to interact with the Badge + Owners [Access Level III] to obtain badges for the action that they have + done within the community. + diff --git a/docs/badges/prop_rewrite_technologies.rst b/docs/badges/prop_rewrite_technologies.rst index e69de29..a3d8f9f 100644 --- a/docs/badges/prop_rewrite_technologies.rst +++ b/docs/badges/prop_rewrite_technologies.rst @@ -0,0 +1,52 @@ +.. _prop_rewrite_technologies: + +Technologies suggested +==== + +Database +---- + +*Suggested using:* + | Database: Postgres + +Accolades API +---- + +*Suggested using:* + | Web framework: `FastAPI `_ + | CLI compositor: `Click `_ + | Database abstraction: `Psycopg2 `_ + | ORM and SQL library: `SQLAlchemy `_ + | Configuration parsing: `PyYAML `_ + | Caching and indexing: `Redis `_ + +Accolades CLI +---- + +*Suggested using:* + | CLI compositor: `Click `_ + | HTTP library: `Requests `_ + | Configuration parsing: `PyYAML `_ + +Liberation +---- + +*Suggested using:* + | Frontend library: `VueJS `_ + | Frontend framework: `Vuetify `_ + | Server: `Vue server `_ + +Collection +---- + +*Suggested using:* + | Version controlled forge: `GitLab `_ + +Messages Consumer +----- + +*Suggested using:* + | Listener: `Fedora Messaging `_ + | CLI compositor: `Click `_ + | HTTP library: `Requests `_ + | Configuration parsing: `PyYAML `_