Building the Card Catalog

Status update & strategy for the Card SDK

Chris Tse


Chris Tse, Founding Director of the Cardstack Project, presents the concept, power, and value of cards for developers and end users — while giving insights into the current state of and the future strategy for the Card SDK and, consequently, the Card Catalog.

A catalog of cards to replace today’s app stores — that’s the goal. How do we plan to build this catalog? Why are cards valuable tools? How can you build cards yourself? And what will the user experience look like? This article answers all these questions.

The Card Catalog is an essential part of the end-user facing software we are working on at Cardstack. It shows which cards have already been built by the community, thus enables developers and end users to leverage those cards, in order to create their own experience in the Cardstack universe.

Cardstack has three audiences

Cardstack can be viewed from three different perspectives, which poses fundamental questions:

What do developers see when they see Cardstack?

Developers (whether they are Web developers, application developers, or JavaScript developers) need to see Cardstack as an open-source card SDK — a software development kit that enables them to build new cards in an open-source way. Using the open-source library, they can create their own open-source cards or something more proprietary.

What do end users see when they see Cardstack?

Developers deliver the cards they’ve built to the end users, who can use them to create their own cards — their own meaning, their own content, their own data, their own assets, their own actions, their own history. Those are what we call My Cards, which is similar to My Documents on a Windows computer. It’s basically everything the users have created over time, using the applications that exist in their ecosystem (their computer, Windows store, etc.). These cards are the kinds of things users would take a screenshot of; for instance, a card could be the memo, note, or reminder a user has written for himself, using a notes app.

What do blockchains see when they see Cardstack?

The blockchain may not be a person, but it is a network of people working together towards a consensus — it represents a particular set of personalities, needs, and wants that we need to address. And that makes it the third audience for Cardstack. Blockchains see the Cardstack software as a service. After all, at its core, even the blockchain itself is a type of Software as a Service. You pay a small transaction fee in gas, hoping that someone will record your data or transaction on the blockchain; in other words, you pay a small amount of money for the service of giving you a permanent record on this amazing ledger. Cloud services belong in the Software as a Service category as well. You pay a subscription fee of a few dollars per month to have someone provide a content management system or run a chat service for you, to name an example. All this is software — instantiated, deployed to a server, and managed professionally. In return for running the software for you, they charge you a fee.

In the Cardstack ecosystem, developers don’t have to worry about the Software as a Service. They just bring the software to the users in the form of cards. The users want to use those cards to build their digital lives or businesses; in order to do that, they want someone else to run this software — these cards — for them as a service. And that’s what we call Tokenized SaaS.

The word “tokenized” refers to the measurement of value. It simply means that the distribution of revenue and rewards — to anybody who has contributed services, software, or maybe even recommendations as a type of lead generation — is done through a calculation that is based on blockchain and tokens. For instance, you can get partial credit for providing one of the cards that someone else uses in a larger workflow.

Developers, end users, and service providers are interlinked through these tokens. The end user pays a service provider a certain amount of money (whether the fee is prepaid, subscription-based, or pay-as-you-go) to run his set of cards for him, thus generating revenue. A portion of that revenue goes towards things like paying the server costs (keeping the lights on, providing storage, etc.); but another portion of it goes to the developers of the tools, cards, and plugins. That’s how we get from the revenue of the SaaS provider, which is paid for by the end user, to the reward going to the people who build the software in the first place. This connection is essentially based on the end user’s willingness to pay for services. If the end users are not willing to pay someone to run those services professionally, there’s no revenue. Without revenue, there’s no portion of that revenue that becomes a reward for the developers.

The idea of revenue and reward in our Cardstack ecosystem is based on two related goals: giving developers the incentive to create new open-source software, while also taking away the incentive to lock users in (this way, they don’t need to force users to stick with them, to make sure they get paid, because they get rewarded fairly and continuously for open-sourcing their software).

Therefore, this Tokenized SaaS creates a symbiosis between the people who are willing to answer calls as service providers, and the developers who want to improve the code. Most of the time, these are not the same people; but the Cardstack system brings them together.

That’s what the developer, the end user, and the blockchain see — that’s what Cardstack is going to do for them.

What’s wrong with app stores

The way we look at the software business is not new. In fact, Apple is doing something quite similar. Their developers build apps on the iOS SDK, which is comparable to the Card SDK. It provides the features that are then given to the users, who install the apps on their home screens. This distribution can be done through an app store, monetized through in-app or upfront purchases, or an advertising mechanism.

The app store is basically the business model of the Apple ecosystem. But this variety of tools, which allow the user to do all sorts of things, is not just about what Apple can do for them — it’s about the creativity of many, many developers, who find new ways to address new needs.

But here’s the interesting thing: When you buy an iPhone, the first thing you see is the home screen, which features almost no branded apps. Other than iTunes, for example, most app names describe what the app does — take a photo, show you the weather, see the map. Only after the users have learned to use these tools do they start demanding branded apps. They no longer want a messenger; they want the Facebook Messenger.

That’s actually in conflict with the original vision of the app store. What goes into an app is a certain concept: The camera is about photos and videos; using the camera app, you can create photos and videos. The wallet app is about credit cards and boarding passes; using the wallet app, you can use Apple Pay and board your plane. You use the news app to read articles. You use the Reminders app to track your tasks. You use the calendar app to see your appointments.

This idea of the app ecosystem is really great when you first get your phone. But as you turn these common nouns (books, health, files, camera, etc.) into proper nouns like Facebook and Twitter, your life instantly becomes more complicated. Once your apps are separated by brand name rather than function, you suddenly have to ask yourself, “Where is the message thread with the person I want to talk to? Is it in Messages, iMessages, Facebook Messenger, WhatsApp, Telegram? Or in some other app like Viber that I haven’t touched in ages?” That’s what we call the “app silos”: the way you’re forced to think about which network you are part of before you can start interacting with the app.

Why cards are better than traditional apps

App silos don’t exist in the Cardstack ecosystem. And the idea of cards is not even new. When people screenshot articles they want to share, documents they want to back up, or boarding information from their travel app — then those screenshots are cards, and people have been doing this for a long time.

Herein lies the power of the concept of cards: The end users truly value and care about the things they collect. As they interact with different apps, they want to own certain things, by PDFing them or emailing them to themselves. And we want that to be how people interact. It’s not just about making cards into websites or apps, but also about accumulating things over time, similarly to how people use Dropbox. More and more things will get added to people’s collections, which brings us back to My Cards. We want people to use open-source tools to create meaning; to track, save, archive, and share the things they do without boundaries — without worrying about whether or not their contact is in the same network, whether or not they can share their card with their friend.

What are cards?

Cards are ownable. Once you create a card, it’s like downloading a file to your computer. You own it. Not because it’s on the blockchain, but because you possess this. It is yours.

Card are reusable. When you download a card, it is an editable document, similar to a PDF or a Word doc. You can change the text fields; you can even use something you received from someone else (like a very cool invitation) as a template, and turn that into something you will send to someone else (like an even cooler invitation for your own event). That’s possible because cards are alive; they always retain the source code.

Cards are searchable. Your cards are filed in a file system, much like your Dropbox folder or your iCloud drive. This means that, if you’re looking for a certain card, all you need to do is type the file name or some words the card contains. Since all those files are documents, you’ll find the card quickly. In contrast, if you want to find a note you have taken in some Evernote clone, you first have to figure out where the search engine is, then log on, and then search. It is this idea of collecting all your information in your own hub that makes it easily searchable.

Cards are chainable. Let’s say you have someone fill out a form with his contact information. With one click, you can turn that form into an invoice, by simply copying the information over, because the card’s metadata can be imported. Additionally, we can use the blockchain as a way to chain these cards together; once actions get performed and registered on the blockchain, they trigger the next action, like a payment, revocation, or confirmation.

Cards are verifiable. On the Web, you keep typing the same information again and again — your name, your phone number, your email address. Cards, however, allow you to reuse information that has already been verified. If one site has checked your email address, you can get a contact card containing a verification message. And the next time someone asks you for your contact details, instead of typing them in again, you can just present this contact card.

With time, cards get enriched, almost like a passport that gets more and more stamps as you go through different ports of entry, thus building up this verification that makes it more and more valuable. The fact that these cards are editable, versionable, and able to accumulate value over time is powerful.

It makes a card very different from an app. An app doesn’t allow you to own things inside the app; you can’t reuse anything; you can’t really search an app either; and your data is essentially locked inside the app. Therefore, verification is very difficult and you end up entering the same information over and over again. But the card can become a powerful exchange between people and businesses.

What are cards not?

Cards are not stored directly on-chain. Not all cards are stored on the blockchain, simply because people have lots of files on their computers. If every single entry were put on-chain, those files would be much too big for a 100-gigabyte-blockchain (which is a good size for a blockchain). Plus, the blockchain is very public and you don’t want all your information to be visible to other people. However, though it is not stored directly on-chain, it can be anchored on-chain, with a reference for syndication or synching purposes. You can take all your cards and say, “I want to make a record on-chain, showing that these 4,000 cards are owned by me, and anybody who has my key can syndicate them.” The data itself are mostly files located on your computer, or at a service or hosting company you trust.

Cards are not limited in size or features. A card is much more than a screenshot or a document. It’s actually more like an app. It’s like a mini-application — written using the Web platform — that has its own rendering template, but that also stores its own data. That data could be within the card, stored locally, or referencing something on the cloud. Let’s say you upload a four-gigabyte video stream. You don’t need that on the card. You can just reference it; as long as the card can get authenticated and bring that information in, you can have a very rich experience with the card, playing this video. But the card itself could own all the data in the bundle, which would be the equivalent of storing it on Git. Or it could reference information on the cloud, on the blockchain, or on other types of decentralized storage. So, cards are not limited by size or features because they are fully functional apps. They have the programmability of a full application, except that they exist on the edge of the network, not on the blockchain.

Cards are not dead. Because cards are programmable and because they have this template, this logic, this connectivity, and this API access, they are not dead. They’re not like email or screenshots. If you email yourself a boarding pass and the gate changes, that information will not be updated in your email. If you take a screenshot of a receipt, you can’t click on it to trigger a refund. A card, by comparison, can update your boarding gate; and it can have a refund button. That’s why cards are so powerful!

We’ve built test apps for our Card SDK

We want to make sure that the Card SDK (software development kit) — the underlying shared infrastructure for cards — is strong enough to allow us to build many different types of cards. As we remember, the iPhone was a radical invention, combining numerous functions (personal messaging, email, Web browser, personal digital assistant, videos, music, etc.), for which people initially used different devices, in a single device. Just like that, Cardstack can satisfy almost all use cases that you can imagine. With cards, you can do anything you’d want to do in an app, on a desktop, or on a website. To prove that, we built different types of test applications as a way to test our SDK — our ability to build cards.

Card Folio for assets

We built a cryptocurrency-tracking explorer wallet app, using our Card SDK. We wanted to see if the concept of cards allows the encapsulation of wallets, addresses, transaction histories, portfolios, exchange rates, etc. So, we aimed to create a cohesive experience — like a great portfolio tracker that understands crypto. If you make a transaction, your wallet is automatically updated and propagates all the value of your crypto in real time. We released and open-sourced this asset-type application in January 2019.

Card Board for content

Content is the equalizer. Everybody can blog, write a post, express themselves. So, we wanted to see if cards can encapsulate content; not just articles, but images and videos too. That’s why we built a content management system, using our Card SDK. This app turns different types of content into cards, which are combined to create a rich experience — where everything, from the image to the article itself and even the site (which shows an index of all the images and articles) is a card. We released the source code of this content management project in March 2019.

dotBC Registry for data

In collaboration with the partner of a music company, we built a registry, using our Card SDK, to synchronize data around music rights. This includes information about the song title, the songwriter, the copyrights, the audio file, and much more. For these kinds of data management needs, people typically use expensive SaaS options like or the industry equivalent of that. We wanted to show that we can do that too. So, we built a data application that can encapsulate data, forms, and fields; with editable, versionable cards that are able to request permissions and deal with access control — for example, ensuring that you can only get access to a certain field of information if you are a high-level VP.

While building these applications, we also extended the Card SDK, to support features that should be shared across all application development in the Cardstack ecosystem:

When we built the asset management system (Card Folio), we improved our plugins to Ethereum, so that we can index not only on-chain transactions in Ethereum, but other types of activities as well; we wanted to be able to go back and correlate exchange rate data in plugins, in a synthesized way. So, we released some plugins related to that, but also firmed up the way plugins work across the cloud and blockchain.

For the content management project (Card Board), we improved the Edges, which are the standard editing tools, versioning tools, and configuration tools that are used to create a card. Those capabilities (edit the text, choose variants of it, etc.) are part of the experience. We call it the 4 Edges Design System, the properties of which we will reuse not only for content, but also for data applications.

For the data registry (dotBC), we crunched a lot of different types of interrelated data, which helped us understand the schema. Cardstack is fundamentally a schema-driven model. So, we know the type: What is an asset? What is an account? What is a person? What is an invoice? These are all concepts we understand. And once you know that something has a certain shape and certain required fields (e.g. invoices always have an amount due and a date), you can start chaining things together, so that you can just click a button to pay an invoice. That payment card doesn’t need to be inside the invoice, as long as they both exist in the Cardstack universe. They recognize each other’s schemas, which allows us to chain the cards together to create those workflows, so that you don’t have to log into 16 websites to get a bill paid. So, we learned a lot about the schema, and we’re doing some major revisions on the schema infrastructures.

We’re building a Card Catalog

What we get along the way, as we’re building up this SDK, is a set of cards — a set of reusable components that are a consequence of building a portfolio system, for example. We have a portfolio that sums up everything you own in your wallet. We have a wallet that’s mapped to a particular key and address. And we have a transaction as an on-chain record that tells us when something happens — when you have some currency coming in and some currency going out. This obviously works for crypto assets, but it can be extended to non-crypto assets as well, by sending the transaction to an e-banking system as a back-end rather than a blockchain.

When we’re building in the Card Board system, we have the concept of a site, an article, and an image. However, if you need to insert an image in the data registry, to model cover art, it uses the same image card. The image upload and permission is shared across all these applications. So, underneath these test apps, we’re building a cohesive catalog of cards. In the dotBC application, for instance, we do a lot of approval — approval for someone to see a field or to accept a change. And that’s all deeply ingrained in the schema system. Obviously, the UI can be adjusted. But the basic idea is what we’re collecting: the core cards for this Card Catalog.

Apps are just cards

These apps — Card Board, Card Folio, dotBC Registry — are actually just cards. There’s a top-level card called Site, which includes the underlying articles and images. There’s a card called Portfolio, where you can go to the URL, but transactions and assets are embedded inside it. There’s a card called Board, which is a dashboard of songs that can include organization requests, approvals, and other music metadata related to it. These cards are the lower-level building blocks composing the apps people know.

Cards can be at rest or in motion

Our codebase is the accumulation of containers and cards that are all built on top of this common Card SDK.

Cards have two modes:

A card can be at rest — as something that records some truth, which you can collect, like an article.

A card can be in motion — when you’re submitting an article for a competition, requesting someone to invite you to his organization, or signing a transaction, for example.

The idea of messages and forms, requests and approvals, is a very interesting aspect of cards. Because cards are composed from the bottom up, they can exist in what looks like a website; you double-click on the card and it opens up. But they can also get attached like files in email streams. Let’s say you create a job application form. You can go back and forth via messaging as long as you want, to get the form right; and all that time, you’re actually version-controlling it. This idea that cards can participate in an organizational workflow is extremely important to us.

Card picking, counting, triggering, archiving, mapping, tracking

We want to bring more and more capabilities of cards into the Card SDK. For example, you usually want to select an image from your library when you write an article. So, you would like everything to be attachable, selectable, uploadable — like an image. Turns out, any card that is like a media item can have a thumbnail, and you can put it in. This could be a real image or a computer-generated animation — that doesn’t matter. Once you implement the media boundary, you can do that. It’s the same with assets/accounts, whether that’s a crypto asset or a bank account. Once you have a balance, a date, and some recent transaction, it participates in the Cardstack ecosystem; you can count and aggregate them. Same thing with triggering actions, archiving snapshots, mapping metadata from one card to another, or tracking versions. We’re adding these capabilities to the Card SDK, to create a stronger and more powerful SDK that gives you these features of media browsing, asset tracking, action chaining, receipts/snapshots, metadata, and versioning for free. And with that capability, we can start thinking about what the core catalog of cards would be.

Refining the first batch of core cards

Developers can not only distribute their features or cards in the ecosystem, but also work with each other to figure out what new cards, features, and functionalities are most valuable to the community. A big part of participating in the Cardstack ecosystem is to collaborate, helping to roadmap the catalog of cards that will allow us to unlock their value in the world.

For the end user, the number of cards they can use (invite cards, approval cards, payment cards, etc.) can be infinite. The key is that, once we have delivered the first batch of core cards to the end users, they will get the idea of what an ownable, reusable, searchable, chainable, and verifiable card is. Hopefully, that will inspire them to say, “Hey, could you add this feature?”

Getting developers involved

As a smallish team at Cardstack, we need the community of Web developers to help us build more cards based on the Card SDK.

Our SDK is designed to be very flexible, in terms of what type of stuff you can turn into a card. It’s not just an SDK for blockchain. With our plugin system and our use of the Ember.js framework, there is no restriction on what you can do. As long as you can call an API and persist the data in Git, which you can put on GitHub or your computer or Gitchain, you have a lot of flexibility in what you do.

Furthermore, the Card SDK is both a front-end and a back-end technology. When you build a card and have a schema for a new type of legal form, for example, you can create a back-end that connects to HelloSign. That’s all part of the packaging of the card. Besides, you can write JavaScript or TypeScript in the card itself, which is quite unique. So, when you deploy a card, the browser with the front-end stuff, and the Hub (a server providing the API access) with the back-end stuff are all bundled together.

We don’t expect developers to build entire apps from scratch. Just like you would use Wordpress as a starting point for building a new content management system, you can use the starter kits we provide to build new cards or features. If you like the article idea, for example, and you want to add a podcast option, you could use the infrastructure for searching, media management, and file upload to make a podcast card.

The detailed developer documentation is coming. We want to show how we build what we build; how developers can extend this set of cards. Developers can learn from our experience of being our own guinea pig, building against our own SDK. And once we have this SDK, we will create a hosting service called, so you can play around with these things as end users, and learn directly from examples as developers.

Jen Weber, who spearheaded a lot of work at the Ember Learning Core Team, focuses on how to teach the Ember.js framework to more developers. She has a great understanding of the right depth, mode, and timing to bring this fairly complicated (yet sensible) SDK to the development community. Putting this documentation out there is something we are committed to doing, once we feel like the API is not going to change dramatically.

Our first important business model for providing the tools that have been built within the card ecosystem is “hosting”. You host Cardstack, and within your Cardstack, you can use any cards you want from the catalog. This is a global catalog, from which you can pick anything you want to use in your daily life. And developers can add to this catalog, by learning how to build, augment, and create cards.

If developers are ready to go deeper into the SDK, they can expand on and improve the core framework itself, rather than just build on top of this nice layer. You can’t do that in iOS. You can build within the iOS SDK; but you need to be employed by Apple to make improvements to the SDK itself. With our open-source approach at Cardstack, we see that most developers are very interested in building on top of the SDK. But in the Ember and the Node communities, people tend to want to get deeper into it, to make some fundamental performance, security, features, or ergonomics improvements for developers. It’s an exciting way of collaborating between the developer user space and the framework space underneath.

Here’s what we try to avoid in designing the Card SDK:

Firstly, we don’t want to lock you into a particular vendor. Let’s say a vendor provides a card for you to do invoicing. One day, they go out of business. It would be bad if all the data you have in that invoicing system were locked inside their database. The same thing can happen to a blockchain. Say you build this amazing application on the blockchain. One day, the blockchain gets forked or hacked and doesn’t work anymore. What happens to all your data? That’s pretty dangerous. And that’s why, with Cardstack, you can always keep a copy of everything you put into the cloud or submit to the blockchain.

That allows you to recreate everything, by bringing those invoices to a competing vendor that supports the Cardstack invoice standard. It’s the same thing with a blockchain. You can take all the metadata records from this blockchain, move to a new blockchain, and replay the history from the beginning. That is why we’re using Git, with this idea of version control at the file level — so that we are able to recreate these kinds of global states, whether it’s in a centralized database or on a decentralized blockchain.

This is an important part of our defense against the possibility that a cloud service or blockchain network may not be around, trustworthy, or reliable forever. It is a defensive move for the user. Plus, developers could save the same card to different blockchains or to the cloud. That expands the potential market of the great user experience they provide.

Secondly, we don’t want to force you to use plugins. Cards have a front-end, so they are basically Web applications you can access, or widgets you can embed within the Web page. They have a back-end, an API, but they do not require plugins. A lot of decentralized applications require users to download a piece of software, like a Chrome plugin, before they can use something. That leaves a lot of interested people unable to experience blockchain first-hand. Of course, you always have the option to use a plugin if you like. Yet, to introduce the idea of cards, card chaining, and registering certain data on the blockchain, we should try to eliminate that. Therefore, Cardstack, by default, does not require a plugin.

If you want to run everything yourself, Cardstack is just a Docker container. The full node and all the databases can be run on the desktop. So, we can actually package Cardstack as a desktop application, which will become your on-ramp node. And since you are your host, you host your own data. But as a starting point, we want to introduce the idea that you don’t have to install the software before you can experience Web 3.0 for the first time.

What’s next?

1. At the framework level, we are refactoring the Card SDK, to enable multi-party workflows that cross data source boundaries. In the sample apps like Card Board and Card Folio, you have one website that has one repository and that’s it. It has permissions, login, authorization, grants, access control, etc. But we want to make sure the cards can truly move between different workflows, different sites, different hosts, and different hubs. That is tricky, but we have figured out what is missing. It’s largely just about knowing where the card came from and allowing for version control across boundaries. So, we will use this new SDK, this new schema, these new metadata constructs, in our new sample apps.

2. As we move out of the framework space into the user space, by building the first set of cards, we are migrating to a scenario-driven design and development process, to ensure a smooth on-boarding experience for end users. This scenario-driven approach is a way for us to figure out what the workflows for end users would look like, from beginning to end. It should all make sense, regardless of whether or not the workflows are based on the blockchain. There are a lot of specific use cases we are imagining. But they are not what we are building; eventually, we would like the community to build them, based on the templates we provide.

3. We can finally put cards in motion through Card Flow, letting cards move between people and organizations, carrying value and facilitating transactions. With the current state of Card Space, the framework, and the Card SDK, we can attach the same card multiple times in the same flow, without risking that the application might get confused. This idea of versioning, sequencing, mapping, copying, isolating, snapshotting, saving, moving, and allowing things to be deleted — this is something the framework is finally ready to do.

Card Flow will likely be the main way people experience cards for the first time. As much as we want people to use Cardstack to build Web 3.0 apps or websites, they will probably be using the Card Flow system — to take something from one app or dApp and lift it into this conveyor belt, send it to someone based on a wallet or email address, invite that person into a multiparty workflow, negotiate with them, then click “OK”, and have it settled, either in a centralized database or on-chain.

That layer is currently missing. In the world of cloud, we get IFTTT and Zapier, but that’s mostly for automation; you set it once and have it repeat over time. It doesn’t facilitate decision-making, approval requests, and negotiation. We believe that this basic infrastructure is the core of business. That is why Card Flow is so important. It will allow us to turn Cardstack into not only an application-building tool (which is valuable), but a workflow-building tool. Workflows are the basic concept that business is made of, and if we can support new types of business — boundaryless, flexible, low-friction business — a lot more people will look at Cardstack as a way to go beyond the enterprise data center, or even centralized SaaS, into a much more collaborative, open-source way of building software and value.

Learn More

Join our Discord channel and star Cardstack on GitHub to follow updates on the Cardstack framework, Gitchain, and a suite of standard cards.



Chris Tse

Technologist, designer, and founding director of the open-source @Cardstack Project. Building the experience layer of Web 3.0.