Architecture Decisions

User Collections

When a User is added/created in the system, they get a unique "User Collection" (aka Root Collection / Workspace) that belongs to their Organization.

• The User Collection itself cannot be shared with anyone else.
• They can add items/collections to their User Collection, which will by default be editable by them, and shared with the organization as a viewer.
• They will get all of the seeded content from the Organization "Getting Started" collection, which itself gets duplicated from the master Getting Started collection in IDEO, as specified in the ENV.
• (see note below about deprecating this feature) They automatically have a "Shared with Me" subcollection that is added to this collection, which is a "smart" collection that functions like a search result of all collections that have been shared with them. They can move the card for this "Shared with Me" collection around and place it however they want within their collection. The "Shared with Me" collection can't be shared with anyone else.

Permissions + Sharing

Sharing happens when you add a viewer/editor to a "record" (item or collection). This can be an individual user, or a group. When you share the collection:

• Each user will get an email notifying them of the action (if the notification option is selected). If it is shared with a group, each of the group's members will get an email.
• Each person being shared will get a linked card in their My Collection, at the bottom, linking to the collection being shared. In My Collection, they are free to move/reorder/archive the link if they want.
• NOTE: the following logic still exists though we are hiding the "Shared with Me" Collection as it was not working intuitively:
  • Their Shared With Me Collection will also get a link created at the top. Shared With Me is always ordered by most recently updated first. In Shared With Me, the links are fixed in place since you are just a viewer of that collection (although it is technically a collection, it functions more like a search result of things that have been shared with you).

Breadcrumbs and other cached fields

Breadcrumbs are an array that acts as a cached representation of the "tree" that leads to this particular item or collection, e.g. for collection "Adidas Moodboard" it might look like:

• [["Collection", 1236, "Shape Use Cases"], ["Collection", 1237, "Adidas Moodboard"]]

The item itself is always the last element of the breadcrumb. The breadcrumb is calculated by taking the parent collection's breadcrumb and appending the crumb for this particular item.

Collections also have a couple of other cached fields, which are stored in the cached_attributes jsonb field in the database, and accessed via shortcuts on the model using the store_accessor attributes:

• cached_cover contains the collection's cover (first shareable image and text item). This is cached because it has to do a bit of querying to figure out which items belong on the cover, and the end result is a simple image url and some text which is easily cacheable. This field gets re-cached in various methods that alter or create new cards, by calling collection.cache_cover!.
• cached_tag_list is just a cached representation of the collection's tags, instead of having to query the ActsAsTaggable tables. This is re-cached any time you change the tags.

Duplicating, Linking, Creating

• When you create an item or collection, it will automatically inherit the permissions from its parent collection. If you create a collection in "My Collections", it will always add your organization (i.e. the org's "primary group") as a viewer of the collection, thereby making it "shared with the organization" by default.
• Linking to a collection or item creates a shortcut to that collection/item. The link card will have a little link icon indicating its status as a link. Clicking the card will just take you directly to the original record's URL, meaning it's the same as if you navigated to that record directly.
• Duplicating a collection or item creates a copy of the record, preserving the permissions of the original (i.e. the same editors/viewers will be attached by default unless you remove them).

Types of Collections

Shape has several types of collections that are true subclasses through single-table inheritance (STI), including some that provide augmented behavior:

• Board (foamcore)
• TestCollection/TestResultsCollection (feedback tests)
• SubmissionBox
• UserProfile

Template Collections

A Template is another type of collection you can create from the UI, which will create a normal Collection with master_template: true. Any cards you create/move into there are set as pinned: true. Any subcollections (including of the above STI types) will also get marked as master_template: true as they are all "subtemplates" of the top level master template, such that creating an instance of your template will copy the entire card structure of your template and its subtemplates. When creating an instance, the pinned cards that get copied from the master template cannot be moved or archived (though their content can be edited, for example a master template text item might say "List your team members here", and the instance editor would fill out the content). Users can still create content after any pinned parts of the template; but the pinning allows the template to dictate a consistent structure of the collection, for example when setting up a Submission Box you can create a template that everyone's submissions will follow.

When you edit/move/reorder any pinned cards in your template/subtemplate, those edits will propagate to all instances of your template. One caveat is that text edits will only propagate to text items which haven't been edited, so that people retain their own edits. If you archive any of the cards in the template, users will get a "Deleted from Template" collection that stores all the archived content, in case they want to keep anything they had been working on which is no longer part of the master template.