Add more info to architecture (#4233)

* Add more info to architecture

* Fix various typos and improve clarity in docs

app/labor/flare_tag.rb

@@ -20,6 +20,7 @@ class FlareTag
 
   def tag
     @tag ||= Rails.cache.fetch("article_flare_tag-#{article.id}-#{article.updated_at}", expires_in: 12.hours) do
+      # Take the first flare tag to show up in the array
       flare = FLARE_TAGS.detect { |tag| article.cached_tag_list_array.include?(tag) }
       flare && flare != except_tag ? Tag.select(%i[name bg_color_hex text_color_hex]).find_by(name: flare) : nil
     end

docs/frontend/liquid-tags.md

@@ -42,3 +42,45 @@ Here is a bunch of liquid tags supported on DEV:
 {% blogcast 1234 %}
 {% kotlin https://pl.kotl.in/owreUFFUG %}
 ```
+
+## How liquid tags are developed
+
+Liquid tags are a matter of parsing the "arguments" and serving relevant JavaScript.
+
+Liquid tags go in the `app/liquid_tags` folder. All liquid tags inherit from the base, like so...
+
+```ruby
+class KotlinTag < LiquidTagBase
+```
+
+Each liquid tag contains an `initialize` method which takes arguments and a `render` method which calls the appropriate view.
+
+```ruby
+  def initialize(tag_name, link, tokens)
+    super
+    stripped_link = ActionController::Base.helpers.strip_tags(link)
+    the_link = stripped_link.split(" ").first
+    @embedded_url = KotlinTag.embedded_url(the_link)
+  end
+
+  def render(_context)
+    ActionController::Base.new.render_to_string(
+      partial: PARTIAL,
+      locals: {
+        url: @embedded_url
+      }
+    )
+  end
+```
+
+View files can be found in `app/views/liquids`.
+
+Each new liquid tag should be accompanied by instructions in `app/views/pages/_editor_guide_text.html.erb`.
+
+Liquid Tags should also be accompanied by tests in `spec/liquid_tags` which confirm expected behavior.
+
+Some Liquid Tags are constructed using HTML and CSS within the app, and some are constructed by displaying an iframe of an external site.
+
+CSS for Liquid Tags are found in `app/assets/stylesheets/ltags`. Liquid tag classes should generally be prepnded by `ltag__`. e.g. `ltag__tag__content` etc.
+
+Here is an example of a good Liquid Tag pull request... https://github.com/thepracticaldev/dev.to/pull/3801

docs/getting-started/architecture.md

@@ -16,7 +16,7 @@ Ruby on Rails is a web framework heavy on conventions over configuration. All el
 before_action :set_cache_control_headers
 ```
 
-We also user server-side caching [Rails caching](https://guides.rubyonrails.org/caching_with_rails.html). Any time you see `Rails.cache` or `<%= cache ... %>`, this is code affected in production by caching. 
+We also user server-side caching [Rails caching](https://guides.rubyonrails.org/caching_with_rails.html). Any time you see `Rails.cache` or `<%= cache ... %>`, this is code affected in production by caching.
 
 ## We use inline CSS and deferred scripts for usage performance improvements
 
@@ -36,4 +36,30 @@ We also have a sprawling CSS structure with few consistent rules.
 
 The home feed is based on a combination of collective recent posts that are cached and delivered the same to everyone in the HTML, and additional articles fetched from an Algolia index after page load. To determine which posts a user sees, they are ranked based on the user's followed tags, followed users, and relative weights for each tag. Additional fetched articles also follow this general pattern.
 
-Currently, the top post on the home feed, which must have a cover image, is shared among all users.
+Currently, the top post on the home feed, which must have a cover image, is shared among all users.
+
+# General app concepts
+
+## Articles (or posts)
+
+This is the main high level content a user creates. An Article has many comments, taggings through acts-as-taggable gem, belongs to a user (and possibly an organization), and is generally the central core unit.
+
+## Comments
+
+Comments belong to articles (or podcasts, generally polymorphic). They belong first and foremost to the user in our architecture, which is reflected by the URL (`/username/tag-slug`) but they also fit in communal areas below other content. They are threaded but flatten out so that there is not infinite threading (e.g. once a discussion branch gets going, no more branching after a few).
+
+## Tags
+
+Tags help organize content, with rules for each tag. A tag is a de facto community with one or more moderators with privileges to determine what is appropriate for the tag. Some tags act as "flare" for posts so they show up more pronounced in the article when viewed from the index. Tags that belong as "flare" are currently defined in the `FlareTag` object. In cases of multiple flare tags, the flare displayed is determined by its hierarchy.
+
+## ClassifiedListings (or listings)
+
+Classified listings are similar to posts in some ways, but with more limitations. They are designed to be categorized into market areas. They also make use of tags.
+
+## Organization
+
+Users can belong to organizations, which have their own profile pages where posts can be published etc. This can be any group endeavor such as a company, an open source project, or any standalone publication on DEV
+
+---
+
+This is far from a complete view of the app, but it covers a few core concepts.

docs/getting-started/pull-request.md

@@ -11,3 +11,5 @@ title: Preparing a Pull Request
 - If you follow the pull request template, you can't go wrong.
 
 _Please note: all commits in a pull request will be squashed when merged, but when your PR is approved and passes our CI, it will be live on production!_
+
+If the pull request affects the public API in any way, a post on DEV from the DEV Team account should accompany it. This is the duty of the core team to carry out.