cardstack / cardstack-documentation

Cardstack App Suite

This is the main repo for Cardstack, an open source application architecture for building cohesive experiences, including payments, on open, decentralized infrastructure.

Join the discussion around developing on the Cardstack framework on Discord, and read our documentation on docs.cardstack.com. (Note: documentation refers to Cardstack v2. The main branch of this respository has in-progress work on v3 of Cardstack.)

Orientation

This is a monorepo. Each directory under packages and cards is distributed as a standalone NPM package under the @cardstack NPM namespace. More information is available in the README.md within each package.

Developing and Testing within this Repo

Local host names

Set up app.cardstack.test and app-assets.cardstack.test to resolve to localhost (127.0.0.1). There are a variety of ways to accomplish this, with the most direct being to edit your /etc/hosts file.

Hub environment variables

See the README in the hub package for environment variables that you'll need to setup.

Fetching waypoint config

To retrieve environment variables for waypoint in a more readable way as an alternative to waypoint config get, you can use the convenience script yarn waypoint-vars.

// prints a table of variables, with values truncated for readability
yarn waypoint-vars
// prints JSON of variables that contain any of the strings provided (case-insensitive), full values
yarn waypoint-vars VAR_NAME1 VAR_NAME2

Javascript dependencies & Typescript compilation

We use volta to manage our global javascript dependencies. In this case, specifically, we use it to manage node and yarn. To use it simply install it following the instructions here: https://docs.volta.sh/guide/getting-started

In development, we use lerna to manage the inter-dependencies of all the packages. To get started:

1. Install node and yarn via volta.
2. yarn global add lerna (use >= 2.0.0 for yarn workspaces integration)
3. lerna bootstrap
4. Launch the typescript compiler with yarn compile --watch
5. Start ember-cli and the hub node server with yarn start and/or run tests with yarn test

Editors

If you use Visual Studio Code and work on the boxel, web-client or ssr-web packages, we recommend the following extensions to make working with glint and gts files better:

• Glint language server integration for VS Code
• VSCode extension for glimmer

Note that you will see TypeScript errors shown twice if you have the built-in VS Code TypeScript extension running as well as the Glint extension. You may also see some spurious errors from the built-in extension, because it does not understand the template tag. It can be beneficial to turn off the built-in TS extension when working purely in a workspace that is configured for glint, since glint is performing a super set of TS validation. To find the built-in extension in the extensions list to disable it, you will need to search for "@builtin typescript".

Understanding the respositories under the Cardstack organization

The following summary offers an overview of where development is currently ongoing at Cardstack. (Note: any projects linked below that are not currently public will become public soon.)

cardstack/card-protocol-xdai

• The Layer 2 contracts for the card protocol live here including
  • PrepaidCardManager contract
  • RevenuePool contract
  • L2 Token contract
  • SPEND token contract
  • BridgeUtilities contract (facilitates token bridge contract)

cardstack/tokenbridge-contracts

• The home bridge and foreign bridge token contracts

https://github.com/cardstack/card-protocol-relay-service

• our gnosis relay service, forked to provide additional prepaid card manager API's that support gasless interactions with our PrepaidCardManager contract

cardstack/safe-transaction-service

• our gnosis transaction service, this was forked to provide transaction service for Sokol (xDai uses the gnosis hosted transaction service)

cardstack/cardstack

• this one! It is our monorepo that contains our CardPay Dapp (as well as eventually cardstack hub runtime). Work on the "card compiler" is also occurring in PRs of this repository. A proof-of-concept for the dapp was developed here: https://github.com/cardstack/card-pay/tree/update-UI-depot

cardstack/cardwallet

• our rainbow wallet fork that supplies our mobile client experience. Currently it is focused around interacting with Layer 1 contracts, eventually we see it as interacting with the Layer2 protocol as well. A proof-of-concept was developed here: https://github.com/cardstack/rainbow/branches

cardstack/infra

• Holds our terraform scripts to provision AWS and cloudflare (and eventually GCP) services for our infrastructure.

cardstack/boxel

• our web UI component library

cardstack/catalog-experiment

• our planned Javascript build tooling and CDN that eliminates the need for running npm/yarn and eliminates the need to maintain a node_modules folder in your web projects

cardstack/animations-experiment

• proof of concept for an animation library that works well with Ember and meets Boxel's motion needs

Project-wide Policy and Community Governance

Cardstack follows semantic versioning. As a young, pre-1.0 project, this means you can continue to expect breaking changes in minor releases. Each package should endeavor to include a CHANGELOG.md once it begins to have a non-trivial number of external users.

We intend to adopt a community RFC governance process for public API changes, based on the Rust and Ember projects. At this pre-1.0 stage, RFCs are optional and changes may still be fast and furious.

Cardstack follows the Ember Community Guidelines, both because we are a proper subset of the existing Ember community and because we wholeheartedly endorse the same values.

cardstack-documentation's Issues

Create editorComponents guides

Split info between here and a README for the plugin, most likely

Add links to recent protocol work

The CARD Protocol Explained https://medium.com/cardstack/the-card-protocol-explained-c78e8e091a72

Building Decentralized Media Registries https://medium.com/cardstack/building-decentralized-media-registries-a953fd36d3d4

Building the Card Catalog https://medium.com/cardstack/building-the-card-catalog-bf034445d05e

Introducing Gitchain https://medium.com/cardstack/introducing-gitchain-add61790226e

Firefox caching holds onto old content

If I visit a freshly deployed page in Firefox vs Chrome, in Firefox I see the old content, and even a hard refresh does not retrieve new content. I have to edit the history tracking and turn it off for this site.

This might be fixable via content caching policy for the files. Needs research.

Add Windows setup information in English

Right now, we give some detailed instructions in Chinese: https://docs.cardstack.com/release/chinese-learning/cardboard-windows-setup-cn/. We should get Hexi's help with a high-level overview of what the prose says, and provide the same info in English.

See also cardstack/cardstack#567 that causes problems in Windows.

Update the Quickstart to use the project template

Right now it uses Cardboard, and it would be much simpler to use project-template as the starting point

https://github.com/cardstack/project-template

Update screenshots to use the latest right edge designs for the movielist tutorial

See the movielist branch of project-template to run the app and get the screenshots.

Some of the written text should also change too, since there is no longer a step to click the edit pencil.

Cookbook - write a tutorial for using git as a data source

We should have a 1-page tutorial showing how someone can set up a local git repo as their data source. The code samples should be copy-pasteable.

Prerequisites:
This tutorial should assume that someone has done the quickstart and the Card Guides, and should not re-explain the content from those areas.

To-do:

• write an outline (bullet points) with the steps someone has to go through to create the files
• add code samples to the outline that are copy-pasteable
• create a branch on the template repo that has the completed demo
• Get a reviewer of the code samples/steps to see if any can be simplified
• Write the prose. A cookbook article should be fairly short. Here's an example of a good cookbook article https://vue-vixens-workshop.netlify.com/workshop/nanos/nano2.html#get-started
• submit a PR as soon as most of the tutorial is sketched out. It doesn't have to be perfect/complete
• get a reviewer and iterate
• double check that code samples work, and add a link to the finished code
• ship it!

Add dev env troubleshooting section

We should have a troubleshooting page that covers the following:

• minimum recommended computer requirements
• windows advice
• configuring for VPS

For VPS, you haver to set the IP in cardstack/config/environment.js:

   fastboot: {
      hostWhitelist: [ /^YOUR_VPS_IP:\d+$/, /^localhost:\d+$/]
    },

This DigitalOcean droplet is enough to run at least the tutorial - thanks to phDooY for investigating this plus the VPS

Some details about windows-build-tools should also go in the troubleshooting guide. They are mentioned in the quickstart, so possibly we should remove the details from the quickstart and instead link to troubleshooting.

Subgroup headers in TOC should use different style from TOC items

Right now they look too similar, but they are not clickable:

We should use different style for them.

Update docs app to the latest guidemaker version

This will give us more flexibility for redirects and TOC structure

Write a grants & auth tutorial

This is already a WIP.

Goal:

• create groups
• create a read grant
• provide write access to certain groups
• Make a resource read-only by certain groups
• Maybe show how to do field-level permissions (buggy, still investigating)
• Show how to connect in a way that leverages Github-auth

Challenges:

• The project template has too many grants in it, which makes it difficult to understand. Need to simplify these
• Fine grained field-level permissions are buggy/trolly
• Card field namespace collisions are a likely source of mistakes
• It makes sense to leverage relationships when teaching real-world scenarios, but it's too overwhelming to combine these concepts without first showing them in isolation.
• It takes a lot of setup to get this tutorial going

Add screenshots to the quickstart and "Creating a card"

Compress screenshots

Some screenshots in this repo are ~1MB. We should compress them and make sure the text is still crisp.

Mobile nav is missing!

Where did it go? There should be a 🍔

Link to tutorial videos

We have the quickstart, and soon the movielist and git tutorials. We should embed these in the guides!

Get Quickstart working for Windows

Right now, Cardboard can't be run on Windows due to our use of nodegit cardstack/cardstack#567

We could:

• refactor the quickstart to not rely on Cardboard/nodegit as an interim step (is it baked into Cardstack or just this app's data layer?)
• Refactor Cardstack to not use nodegit
• Give windows specific instructions

This issue can be closed after someone goes through the tutorial successfully in a Windows dev environment.

You can get an official Windows dev VM for free here: https://developer.microsoft.com/en-us/windows/downloads/virtual-machines

Decide on what the example app is and put it in a styleguide

When we give examples in our documentation, we want them to tell a story about building one kind of project. This lets us be more creative/engaging. We should avoid making the entire guides a linear tutorial, and we should avoid tying the Guides content directly to an example app. Each topic should be readable as a stand-alone example. However, reusing the same resource types and explanation context for our code examples will help lower the mental overhead for new learners.

Here's an example with a breakdown of how various aspects of an app could help us teach Cardstack.

project name:
PostCards

Event:
It’s a photo contest! Submit a photo, and the top 6 submissions receive a set of postcards that have the winners.

Problem space examples:

• Top level card - something that contains the whole "app"
• Cards - each photo submission is an instance of a card (?)
• Authentication - users must register
• Persisting and Relating data - photos are associated with users, so the winner can be contacted
• Saving form data - registration and form submission
• Using existing Cards - the dev does not need to make their own photo taking/uploading functionality. They can use a pre-made Card!
• Using a plugin (s3 file storage of the photo)
• Metadata - approving uploads and marking winners (?)
• Embedded Display - using routing and templates to show a gallery
• Isolated Display - showing how a card can be displayed on its own
• Animation - switch between embedded & isolated views
• Four edges - editing the data about the photo submission
• Server side CPs - has this user reached the submission limit?

Resource types

• User - has contact info that is not publicly visible, and a username that is
• Photo - has the file id to use with S3, description, title, date, owned by a User
• File - cache of S3 data?
• Rating - owned by a contest facilitator, relationship to a photo. Has a score, category, and notes. (category is so we can show enum)
• Contest - deadline, per user limit

Learning curve
Most examples should lean on user/photo/file explanations. Maybe also Contest? Mods & ratings should be saved for more advanced topics/cookbooks.

Integrate more hub v2 content

To-do:

• revisit Hassan's presentation and note which things to write up
• Add that content within existing topics
• Create redirects or "todo" message for outdated sections.
• Update the "core types" section of the card-sdk/index

Improve the data sources guides

Add analytics

It would be useful to know which sections people look at the most in these guides.

This ticket is blocked until we have designs for a GDPR notice.

To-do:

• get notice banner designs
• create a component for the GDPR banner either here or in the template repo
• Add google analytics - maybe use https://github.com/poteto/ember-metrics? Or this might already be implemented in Guidemaker if we just provide our config. Needs research.
• Connect deployed domain in the Analytics console
• Exclude IP addresses of maintainers from metrics
• deploy and test

Clarify in field-editors that only the properties you use will show up in the editor

There is also an option to always show the property, which we should document. It is set in the schema for a Card. Need to research to see where it is. It used to be called "editorial"

Integrate some code comments about grants

This file has code comments with some useful mental model info about grants. However it also has a caveat at the top that it's forward-looking and may not 100% match today's implementation. We should verify which things hold true for the SDK as it is today, and document them.

Copy edits for the Quickstart

The Quickstart and the "Dev Mode" article could use one more round of feedback and revisions. This issue is to track that work.

Quickstart needs update to compile typescript

When following the quickstart steps, I got an error starting the hub and starting ember-cli for the cardhost app due to missing .js files. Running yarn compile from the root of the project created those missing files and allowed me to proceed. Perhaps that step should be added, or alternatively, instructions to execute lerna bootstrap from the monorepo root (as the README steps say).

Refer to the running environment of Cards as "hub"

This will help replace places where we dance around the terms "environment" and "application"

Scaffold out prospective table of contents

Getting started

• Quickstart
• Making a card within an existing app (that we provide)
  • Template, schema, display
• What just happened?
  -You just made a card, and schema, cards can have metadata… Very quick summary of the concepts without losing the thread on the quickstart experience

Developing with Cardstack (Card SDK)

• Creating a Cardstack project
• Creating cards
• Using existing cards
• Schema system
• Relationships
• Server side computed properties (editable???)
• Ember Data - querying, making lists, filtering, reading metadata from other cards (more advanced)
• How do you make templates (isolated/embedded)
• Routing (you won’t create these, but need to understand them. Cards within cards)
• Grants (you won’t create these, but need to understand them)
• Animation (WIP - will be one level of abstraction beyond liquid-fire)

Design

• Overview
• Four edges
• Components (form fields)

Adding new data sources to the Hub

• What is a cardstack plugin - reference https://martinfowler.com/bliki/CQRS.html (uncommon compared to MVC) - lightly mention this, that it is well established
• Making a new data source plugin
• Middleware out of the box - writers, indexers, searchers (Main tone - the data sources are not that special)
• Writing your own middleware (show examples, like reading/writing to a really slow enterprise system w/10 min intervals. Another example is connecting to cloud data feeds, blockchain, authentication like OAuth/Auth0)

Revenue Model

• Overview
• Cardstack protocols - GitChain, Clutch, CardKey, Tally
  Tokens Functions

Cookbook

• Making a page that displays info in a dashboard (landing/summary page)
• Forms! (how do you make pasta in an instapot - only schema config)
• Adding a custom field
• Calling a third party API (email, cloud services, etc)

Cardstack internals

• ??? (target audience is the core dev team)

API documentation

Add Windows setup information in Chinese

Note: This issue already has a volunteer

It would be great to have some learning resources in Chinese! Here are the suggested steps to add a new article to these docs:

• Create a folder called chinese within guides/release
• in that new directory make a file called windows-setup.md or similar, and a file called index.md
• Edit pages.yml to include the section and pages (example below)
• Add content to windows-setup
• In index.md, add one or two sentences that are a welcome message. An index.md file is required for the new section to render.
• Add any images you need in public/images

Example pages.yml

- title: "Chinese Learning Resources"
  url: "chinese"
  pages:
    - title: "Page title goes here"
      url: "index"
    - title: "Page title goes here"
      url: "windows-setup"

Thank you for the help!

Add more screenshots for each stage of tutorials

Devs will wonder if everything is working as expected/if they did it right. We can offer some guidance via screenshots at each stage.

This should be done for the quickstart and movielist tutorial.

Fix the deployment of docs.cardstack.com

This is a very low priority issue and should be limited to 1 hour of time. If it takes any longer than that it should be removed from the project and left in the backlog 👍

We have recently released documentation for the grants system on the documentation site. But when you load the page you will notice that the grants Table of Contents item appears at first and then disappears.

The cause of this is that the data json items are not cleared properly from Cloudfront https://docs.cardstack.com/content/release/pages.json

There is some configuration to perform an invalidation on Cloudfront in the ember-cli-deploy config but it clearly is not working right: https://github.com/cardstack/cardstack-documentation/blob/master/config/deploy.js#L34

I have a feeling that either the right ember-cli-deploy plugin that does cloudfront invalidations isn't installed or the invalidation actually needs to be explicit about the files that it needs to clear.

Movie tutorial - change genre to be an enum list

Right now, you can type in any genre, but really we have only set a few in the styling.

This is an opportunity to show the enum dropdown in the Right Edge.

Internal - Document spaces

Spaces are what connects a route to the card data that it's supposed to render. It requests individual cards in individual formats.

Spaces reads the fieldsets to see what is requested.

Even power users don't need to know about what Spaces is or how it works, just framework devs.

Write a simpler example of custom field editors

In the field editors deep dive, we have an example that relies on get, mut, and action in a way that may be confusing to Ember devs and non-Ember devs alike. Many Ember devs do not understand mut at all.

We should write a new example that looks more like a regular event handler's JavaScript to get and set the values.