From d2b4c2bcac030777f671ab631d6ca792f945d5ab Mon Sep 17 00:00:00 2001 From: David Erwin Date: Fri, 7 Jul 2017 13:43:05 -0400 Subject: [PATCH 1/4] Add architecture docs --- docs/_data/sidebars/talk_sidebar.yml | 8 +++ docs/architecture-tags.md | 7 +++ docs/architecture.md | 75 ++++++++++++++++++++++++++++ 3 files changed, 90 insertions(+) create mode 100644 docs/architecture-tags.md create mode 100644 docs/architecture.md diff --git a/docs/_data/sidebars/talk_sidebar.yml b/docs/_data/sidebars/talk_sidebar.yml index b44c9648f..dd311cbef 100644 --- a/docs/_data/sidebars/talk_sidebar.yml +++ b/docs/_data/sidebars/talk_sidebar.yml @@ -37,6 +37,14 @@ entries: url: /install-setup.html output: web + - title: Architecture + output: web + folderitems: + - title: Overview + url: /architecture.html + output: web + + - title: Plugins output: web folderitems: diff --git a/docs/architecture-tags.md b/docs/architecture-tags.md new file mode 100644 index 000000000..7b402b436 --- /dev/null +++ b/docs/architecture-tags.md @@ -0,0 +1,7 @@ +--- +title: Architecture Overview +keywords: architecture +sidebar: talk_sidebar +permalink: architecture-tags.html +summary: +--- diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 000000000..dbaee1b3e --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,75 @@ +--- +title: Architecture Overview +keywords: architecture +sidebar: talk_sidebar +permalink: architecture.html +summary: +--- + +## Talk's Plugin/Plugin API/Core Architecture + +Talk consists of three distinct layers of code: + +* Plugins +* Plugin API +* Core + +### Plugins + +Talk plugins deliver the features and functionality that can be changed or removed. Much of the default functionality is delivered by plugins allowing developers to change behavior along product lines that we've found to be important. + +### Plugin API + +Talk plugins interact exclusively with the Plugin API. Maintaining this layer of separation between plugins and core allows us to consciously design the api that we want it publish to plugin authors. We can then expose just the elements of core that make sense and maintain that contract as core changes. + +### Core + +Talk core consists of architecture and functionality that deliver stability, security, scalability, extendability, etc... In addition, the Core contains features and functionality that is essential to the operation of Talk as a product. + +Our goal is to continually extend our plugin infrastructure making the Core as pluggable as possible. Ultimately, a day may come where the Core of Talk is simply a framework for delivering a certain flavor of web applications. + +## Thinking about Plugins, the Plugin API and Core? + +The following is a template for a thought process that may help clarify your ideas against the backdrop of Talk's architecture. + +Think of a feature of capability. It could be something that's already in Talk or not. It could be something you want to build, or something you'd think would be a terrible idea. The important part here is to have something to interrogate. + +``` +wait(60000); +``` + +Now, ask these questions: + +### Is it a Plugin? + +Most work for Talk these days happens in the Plugin space. If the answers to any of these questions is Yes, then you're thinking of a Plugin. + +* Does Talk's exiting Plugin APIs support the thing you want to build? +* Is this something that only some users will want/need? +* Is this something that we want devs to iterate on widely? + +You should [build it as a plugin](plugins-quickstart.html). Feel free to explore here on your own or reach out to us. We love to advise on plugins, so please feel free to [file an issue](https://github.com/coralproject/talk/blob/master/CONTRIBUTING.md) and we will start a conversation. We will help you conceptualize, architect and promote your plugin if it is in line with our values. + +### Does it need updates to the Plugin API? + +If you answered yes above: + +* Do I need to extend the Plugin API to support my plugin? + +Often times all the functionality a plugin needs is in the Core, but the Plugin API doesn't expose it. In these cases, we seek to iteratively extend the Talk Plugin API. All Plugin API contributions from the community must begin by [filing an Issue](https://github.com/coralproject/talk/blob/master/CONTRIBUTING.md). + +Note: we are stabilizing the process by which new Plugin API bindings are created, agreed upon and ultimately made part of our Plugins Contract. If you are interested in this process, please reach out to us. + +### Does it need updates to the Plugin API _and_ Core? + +3) What, if any, changes need to be made to Core so that the API can be extended? + +Quite often the only things missing from Core are things like _events_, _slots_, _CSS classes_, etc... Adding these is a great way to become a Core Contributor and break new ground as a Plugin Developer. + +We seek to keep Core as lean as possible. + +### Is my idea really just Core? + +Amazing! We are always looking to extend the capabilities of Talk. We look forward to discussing what you've got to bring! + +Please see our [contributing guide](](https://github.com/coralproject/talk/blob/master/CONTRIBUTING.md)) for more information about contributing Core code. From 52d7ba8965ef245374284b732e28e7955c5e0d3d Mon Sep 17 00:00:00 2001 From: David Erwin Date: Fri, 7 Jul 2017 16:59:18 -0400 Subject: [PATCH 2/4] Add Tags docs --- docs/_data/sidebars/talk_sidebar.yml | 3 ++ docs/architecture-tags.md | 64 +++++++++++++++++++++++++++- 2 files changed, 66 insertions(+), 1 deletion(-) diff --git a/docs/_data/sidebars/talk_sidebar.yml b/docs/_data/sidebars/talk_sidebar.yml index dd311cbef..ed307b88e 100644 --- a/docs/_data/sidebars/talk_sidebar.yml +++ b/docs/_data/sidebars/talk_sidebar.yml @@ -43,6 +43,9 @@ entries: - title: Overview url: /architecture.html output: web + - title: Tags + url: /architecture-tags.html + output: web - title: Plugins diff --git a/docs/architecture-tags.md b/docs/architecture-tags.md index 7b402b436..38205c7eb 100644 --- a/docs/architecture-tags.md +++ b/docs/architecture-tags.md @@ -1,7 +1,69 @@ --- -title: Architecture Overview +title: Tags keywords: architecture sidebar: talk_sidebar permalink: architecture-tags.html summary: --- + +Tags can be added to Users, Comments and Assets. + +## Tag Definitions + +When handling tags, the Talk Server references a set of definitions that describe how tags are handled. These definitions are keyed off the tag `name`, the simple string that is stored on items. + +The schema for Tag definitions [can be found here](https://github.com/coralproject/talk/blob/3545bf01cd91044fdb738d337a0ac94d9f71fbc3/models/schema/tag.js). + +Note that along with the `name`, tag definitions contains: + +* `permissions` information about who can see and set the tag, +* `models` which `ITEM_TYPES` this tag can be applied to, and + +Whenever a tag is 'handled' by the server, it references this definition to determine that tag's behavior. + +See [Plugin API Documentation](plugins-server.html#field-tags) for more information. + +### Creating a Tag Definition + +Tag Definitions must be created before tags can be used. This ensures that users cannot push arbitrary tags to hack the system. It also allows devs to specify the behavioral characteristics of the tag. + +Take the tag created by `coral-plugin-offtopic` as an example. + +``` +// coral-plugin-offtopic/index.js +module.exports = { + tags: [ + { + name: 'OFF_TOPIC', + permissions: { + public: true, + self: true, + roles: [] + }, + models: ['COMMENTS'], + created_at: new Date() + } + ] +}; +``` + +This plugin allows users to self-report that their comment is "off topic" at the time of creation, then display a badge on those comments. + +To accomplish this, the plugin creates the tag `OFF_TOPIC` with: + +* `public: true` - will be sent over the wire to the client side) +* `self: true` - can be added by the active user to themselves or assets they own +* `roles: []` - cannot be added by anyone based on their roles +* `models: ['COMMENTS']` - can only be added to COMMENTS (not to users/assets/etc...) + +And viola! This tag is something that can only be created by the logged in user on their own comments and is sent over the wire to the client so it can display the badge. + +## Tag Links + +When tags are stored on objects in the database, they are represented by [TagLinks](https://github.com/coralproject/talk/blob/master/models/schema/tag_link.js). + +A TagLinks says that `tag` was `assigned_by` a specific user at a specific time (`created_at`). + +Note that the `tag` field in the TagLinkSchema is the full TagSchema itself. This allows for another level of flexibility. Server code may generate Tags on the fly, complete with programmatically generated permissions and item behaviors. + +If a Tag definitions exists in the global/asset context then that definition will be used regardless of what is stored here. This allows high level controls on the behavior of tags. From 1d9b627d73936ff8ebc0258fd8924c005e69551c Mon Sep 17 00:00:00 2001 From: David Erwin Date: Tue, 11 Jul 2017 11:05:58 -0400 Subject: [PATCH 3/4] Fix typos and clarify --- docs/architecture-tags.md | 4 +++- docs/architecture.md | 6 +++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/architecture-tags.md b/docs/architecture-tags.md index 38205c7eb..ec4694abc 100644 --- a/docs/architecture-tags.md +++ b/docs/architecture-tags.md @@ -25,7 +25,9 @@ See [Plugin API Documentation](plugins-server.html#field-tags) for more informat ### Creating a Tag Definition -Tag Definitions must be created before tags can be used. This ensures that users cannot push arbitrary tags to hack the system. It also allows devs to specify the behavioral characteristics of the tag. +Tag Definitions must be created in order for the system to determine what tags are permitted on the server side. + +Tag Definitions do not contain any logic themselves but provide information that other parts of the system can use to specify which models a tag can be applied to (models) and perform authorization logic (permissions). Take the tag created by `coral-plugin-offtopic` as an example. diff --git a/docs/architecture.md b/docs/architecture.md index dbaee1b3e..64bd526a7 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -42,9 +42,9 @@ Now, ask these questions: ### Is it a Plugin? -Most work for Talk these days happens in the Plugin space. If the answers to any of these questions is Yes, then you're thinking of a Plugin. +Most work for Talk happens in the Plugin space. If the answers to any of these questions is Yes, then you're thinking of a Plugin. -* Does Talk's exiting Plugin APIs support the thing you want to build? +* Does Talk's existing Plugin APIs support the thing you want to build? * Is this something that only some users will want/need? * Is this something that we want devs to iterate on widely? @@ -62,7 +62,7 @@ Note: we are stabilizing the process by which new Plugin API bindings are create ### Does it need updates to the Plugin API _and_ Core? -3) What, if any, changes need to be made to Core so that the API can be extended? +What, if any, changes need to be made to Core so that the API can be extended? Quite often the only things missing from Core are things like _events_, _slots_, _CSS classes_, etc... Adding these is a great way to become a Core Contributor and break new ground as a Plugin Developer. From dc6fa74d22a577a107aec4e4e8f17aa2813f6ede Mon Sep 17 00:00:00 2001 From: David Erwin Date: Tue, 11 Jul 2017 11:51:02 -0400 Subject: [PATCH 4/4] Add more clarity --- docs/architecture-tags.md | 12 ++++++------ docs/architecture.md | 15 ++++++++++----- 2 files changed, 16 insertions(+), 11 deletions(-) diff --git a/docs/architecture-tags.md b/docs/architecture-tags.md index ec4694abc..06c5d3498 100644 --- a/docs/architecture-tags.md +++ b/docs/architecture-tags.md @@ -6,7 +6,7 @@ permalink: architecture-tags.html summary: --- -Tags can be added to Users, Comments and Assets. +Tags are essentially strings that can be added to models. Currently, tags can be added to [Users, Comments and Assets](https://github.com/coralproject/talk/blob/ced449a1489d47c25d604020fa2e0b3b7a741353/graph/typeDefs.graphql#L144). If you would like to add tags to other models, you can extend this schema using [GraphQL hooks](plugins-server.html#graphql-hooks). ## Tag Definitions @@ -53,12 +53,12 @@ This plugin allows users to self-report that their comment is "off topic" at the To accomplish this, the plugin creates the tag `OFF_TOPIC` with: -* `public: true` - will be sent over the wire to the client side) -* `self: true` - can be added by the active user to themselves or assets they own -* `roles: []` - cannot be added by anyone based on their roles +* `permissions.public: true` - will be sent over the wire to the client side +* `permissions.self: true` - can be added by the active user to themselves or assets they own +* `permissions.roles: []` - cannot be added by anyone based on their roles * `models: ['COMMENTS']` - can only be added to COMMENTS (not to users/assets/etc...) -And viola! This tag is something that can only be created by the logged in user on their own comments and is sent over the wire to the client so it can display the badge. +And [viola](https://youtu.be/Q0O9gFf-tiI?t=23s)! This tag is something that can only be created by the logged in user on their own comments and is sent over the wire to the client so it can display the badge. ## Tag Links @@ -68,4 +68,4 @@ A TagLinks says that `tag` was `assigned_by` a specific user at a specific time Note that the `tag` field in the TagLinkSchema is the full TagSchema itself. This allows for another level of flexibility. Server code may generate Tags on the fly, complete with programmatically generated permissions and item behaviors. -If a Tag definitions exists in the global/asset context then that definition will be used regardless of what is stored here. This allows high level controls on the behavior of tags. +If a Tag definitions exists in the global/asset context then that definition will be used regardless of what is stored here. This allows high level controls on the behavior of tags, ensuring that plugins cannot produce unexpected definitions for already defined tags. diff --git a/docs/architecture.md b/docs/architecture.md index 64bd526a7..36a8d5c1d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -6,13 +6,14 @@ permalink: architecture.html summary: --- -## Talk's Plugin/Plugin API/Core Architecture +## Talk's Architecture -Talk consists of three distinct layers of code: +Talk consists of four distinct layers of code: * Plugins * Plugin API * Core +* cli ### Plugins @@ -28,11 +29,15 @@ Talk core consists of architecture and functionality that deliver stability, sec Our goal is to continually extend our plugin infrastructure making the Core as pluggable as possible. Ultimately, a day may come where the Core of Talk is simply a framework for delivering a certain flavor of web applications. +### cli + +Talk ships with a cli tool that exposes functionality to the command line. We seek to provide cli functionality for all features that could need to be accomplished programmatically or prior to the server's startup. + ## Thinking about Plugins, the Plugin API and Core? The following is a template for a thought process that may help clarify your ideas against the backdrop of Talk's architecture. -Think of a feature of capability. It could be something that's already in Talk or not. It could be something you want to build, or something you'd think would be a terrible idea. The important part here is to have something to interrogate. +Think of a feature or capability. It could be something that's already in Talk or not. It could be something you want to build, or something you'd think would be a terrible idea. The important part here is to have something to interrogate. ``` wait(60000); @@ -60,7 +65,7 @@ Often times all the functionality a plugin needs is in the Core, but the Plugin Note: we are stabilizing the process by which new Plugin API bindings are created, agreed upon and ultimately made part of our Plugins Contract. If you are interested in this process, please reach out to us. -### Does it need updates to the Plugin API _and_ Core? +### Does it require updates to the Plugin API _and_ Core? What, if any, changes need to be made to Core so that the API can be extended? @@ -72,4 +77,4 @@ We seek to keep Core as lean as possible. Amazing! We are always looking to extend the capabilities of Talk. We look forward to discussing what you've got to bring! -Please see our [contributing guide](](https://github.com/coralproject/talk/blob/master/CONTRIBUTING.md)) for more information about contributing Core code. +Please see our [contributing guide](](https://github.com/coralproject/talk/blob/master/CONTRIBUTING.md)) for more information.