Creating Open Source Cannabis - Kushy Case Study
We live in a seamless world aided by the effortless and seemingly endless integration of technology into our lives. But as a consumer and professional in the cannabis industry, it can feel like I'm living in communist country, with a handful of companies controlling cannabis-related software and data.
The major problem? Cannabis data has been capitalized. All the big players have strict policies against using their data, and few work together, leading to a lack of centralized data. Then there's the poor integration of data into 3rd party services (unless they're exclusive paid deals). Which all surmounts to an inequality in resources based on monetary thresholds set by each service (pay to play).
So then what's the solution? An open source API and dataset that the cannabis community can openly contribute to. Whether it's through our frontend or backend interfaces, or even other applications using our API. Anyone is open to use this API (with rate limits), and people seeking greater scale can pay us or download our data and DIY their own API.
This is quite a lengthy journey, so here's a table of contents to guide your way (using CTRL/CMD+F).
- Research and Strategy
- Data Mining
- User Flow
- Wordpress MVP
- Lo-Fi & Hi-Fi Sketches
- Pivoting Point + Deploy v2
- Ceast and Desist
- Open Source
- What now?
Before we begin planning, we start by dreaming. We set goals for ourselves and envision the future we'd like to create, helping establish a more clear roadmap. We set a kind of mission for the company itself:
- Create a directory for all cannabis data, from products to strains to brands
- Always free at the lowest tier (Freemium model)
- Better UX than current competitors
This led to the structuring of the different release stages. Our first phase would be our proof of concept and MVP (minimum viable product), phase 2 would focus on the API, and so on. I defined base features for the MVP:
With a better idea of what we wanted to create, it was time to buckle down and study up.
Research and Strategy
Developing a brand from the ground up requires an immense amount of research and strategizing. From competitor and market analysis, to analyzing marketing and social media strategies, to learning the legalities region by region.
Brands to Inspire
The first thing I did was start to look at pre-existing companies with business models similar to what we were looking to adapt: SaaS (software as a service). The four tech giants we chose to dissect were Netflix, Airbnb, Yelp, and Grubhub. I researched each up and down, from pitch decks to job listings to Crunchbase, to observe the mistakes and advantages they've had.
I studied Airbnb and their explosive growth as a SaaS over the last decade. I was inspired by their progressive development team on frontend React-based interfaces and backend optimizations. And I planned on forking their engineering style guides from Github when we need to manage and unify more developers.
Netflix was chosen for it's scalability, and it's focus on slaying monoliths with cloud-based micro-services. It's an excellent architecture to learn from, the fact their stack can handle video delivery to multiple platforms on a global scale shows it's strengths. We'd want to offer a similar experience with our API eventually operating at a massive scale.
And Grubhub and Yelp were the leading directory, marketplace, and community for retail services -- so we'd be foolish not to learn from their successes dominating the food industry. I researched both brands thoroughly, from their business model to features to site policies to their tech stack (basically Python / Java moving towards Angular/React). I break down their business models in greater detail in the next section.
I looked at Eat24 (owned by Yelp), Grubhub, Seamless (absorbed by Grubhub), and MealJunction. All were services that allow users to search for food online and purchase it for pickup or delivery.
- Eat24 = 12.5% on total order + 3% credit card transaction fees
- Grubhub = 10-15% on total order OR payment system (see below)
- Seamless = 12-18% on total order + delivery + tip
- MealJunction = No commission until you reach certain sales quota
What we observed, is that the average mainstream food business is willing to pay a SaaS 11.5-15% of their revenue in exchange for customer acquisition. In some cases, like Grubhub, companies were willing sacrifice more than 20% of their revenue in exchange for sponsored listings.
Our pricing model? The goal was to stay free for all users and businesses at the base level. A store/brand/product listing on our website would always be free. We'd charge a 15% commission on any online purchases through our interface (just like food giants). And for businesses looking for additional, premium services, we'd have monthly packages available for set costs.
Since Kushy is such a diverse platform, we overlap with a myriad of other companies attempting to bundle similar services. We primarily planned to offer:
- Directory + Maps + Menus
- E-Commerce (B2C and B2B)
- Cannabis Data Services (e.g. POS & S2S integration)
- Patient Verification
To give us an idea of the landscape of the current marketplace, I made a graph illustrating the different services and what companies were in each sector.
Since there are so many competitors, and so much data, I'll drop a few interesting points from some. If you're interested in the tech stacks of some of the companies here, check out our an in-depth breakdown on our blog.
- Meadow and Eaze are the only major companies selling weed legally online. Meadow is like Grubhub, allowing any delivery to create their own e-shop. Eaze is more like Amazon, purchasing all the product and delivering it under the same uxample in our blog hmbrella.
- CannaSOS sells cannabis online, but uses a "pachinko" style money laundering scheme. They convert cash to their own propriety blockchain "PerksCoin", which customers use to buy cannabis products.
- Massroots, Leafly, and WeedMaps (as well as several other companies) are all moving towards expanding their sites to allow for e-commerce.
- Everyone is adopting ReactJS. Well, not everyone, but most of companies either had React in their stack or were hiring developers.
When working in any way with cannabis, even if you don't "touch the plant", you always have to understand local, state, and federal legislation that effects your business. That's really the case with any business though.
We wanted to offer delivery cannabis to consumers, either directly if possibly (like Grubhub), or facilitate 3rd party orders. But of course, if that's illegal in a certain county or state, it makes it difficult. Currently, there are only a handful of cities that allow for cannabis delivery.
We also wanted to offer credit card merchant services through our website, to create greater accessibility past cash transactions. We contacted at least 100 or so payment processors and banks across the world, and discovered a handful that would allow for the sale of cannabis with a credit card (not one of those e-check scammers).
Those were really the key areas where we'd cross any questionably legal lines. Every other part of the business was basically a software company that never actually touched weed.
Name / Branding
I decided to leave the branding for later. In order to test our MVP and gauge general reception, I added the site to our cannabis network publication WeedPornDaily, under it's umbrella as it's "Business Finder". We'd already integrated a type of business finder into the WPD site using Wordpress custom posts, so this was an easy transition for the brand.
My goal was create a directory for every single cannabis business, brand, product, strain -- everything. But before any designing, we need data. And I had something better in mind than wasting resources hiring college interns to manually scrape away into spreadsheets.
As a curator of cannabis content for WeedPornDaily, I've amassed a large collection of canna-related links. Many of these were old lab testing companies, or message board communities with treasure troves of dank data. With a little bit of engineering and ingenuity, I whipped together PhantomJS scripts to parse through the websites. They search for cannabis data to pump into JSON files that make importation into any schema simple.
Since one of our focuses was to improve the UX of current SaaS solutions, I broke out one of the tools of the UX trade -- user stories. I gave myself a couple different scenarios where both everyday consumers and business staff could flow through the site to efficiently achieve all their goals.
One realistic look at our feature set and you'd see a titanic amount of code we'd have to write from scratch. User registration, commenting, a custom API -- you name it, each small component quickly stacked more development time on top of the project.
Rather than wasting time coding an service the public might not even want to use, we opted for a more simple approach. Wordpress and a shit load of plugins. Here's a look at the stack we ended up with:
The total cost of all plugins and theme were under $300. And with that, we had the architecture for the website we needed. Buddypress offered community profiles and Facebook-style activity. WC Vendors empowered users to sell in our marketplace, while the POS plugin gave each vendor their own online register. And WP Job Manager and WooCommerce created the infrastructure for our business and product data.
Wordpress comes packaged with an API out of the box, and with minimal modification you can add additional data or custom fields. I added the OAuth server for an extra security layer, as well as Wordfence, which blocked invasive IPs.
Lo-Fi & Hi-Fi Sketches
We finally get to the design part of our process! I sketched out the primary website pages, as well as all possible components we'd want to occupy it. I worked in tandem with my Sketch file, creating hi-fi mockups of the lo-fi sketches.
It was important to work with both lo-fi and hi-fi, as we were still developing a style for the website. It helped give empty wireframes more character, since we could know what colors or feelings we'd convey.
At this point in the process, the website was basically done. Between our Wordpress, the plugins, and our customization and data -- we had a fully functioning directory website that rivaled some of our competitors (like WeedMaps or Leafly). And we were able to test the product with our audience of half a million subscribers on Tumblr, with our fans signing up and reviewing on the site.
Proving successful with our initial tests, we kept pushing forward with the project. We could finally settle on a name, invest in a domain, and develop branding.
A few mood boards and a week later, we'd had a rough style guide for the new brand. Logotype, colors, fonts, and styling. Handled. Kushy was born.
This round we also focused on SEO and website structuring. I added landing pages for each state and county, creating a wealth of backlinks for spiders to discover each dynamic portion of the website. Hubspot refers to this marketing technique as "Topic Clustering", where we create pillar content (state pages) that link to cluster content (city archives).
We also tested out some new features that we actually had to code ourselves. You know it's a good feature if it isn't a plugin though. In this case, we created a HIPPA compliant patient verification system that worked with Wordpress. And we began testing the ability to integrate with other cannabis APIs, to synchronize our data with one another.
Ceast and Desist
I awoke one morning to an email from the WeedMaps lawyer who served us an official C&D. They claimed we used their API without their permission, and threatened to pursue litigation if we persisted use.
We had already moved past the integration, because we knew it wouldn't go through. We already knew that WeedMaps, and the rest of the greedy SaaS brands holding onto public data, would not consider for a second to give data away for free. WeedMaps write in their Terms of Service that they own any data companies submit to them (something people decried about Facebook in the past).
API integrations come with contracts with exchanges of cash, with the data never leaving the closed loop system. But that's what we were here to change, and it wasn't surprising in the least that we'd begun to disrupt the market.
We were sick and tired of the corrupt corporate regimes ruling over online cannabis directories. And it's corrupt companies doing this, because we have leaders like Yelp taking their dataset and releasing it to the public. There's no excuse for a company to keep information like strain data private - particularly when they're crowdsourced. It'd be like Wikipedia refusing to let developers use their API for free.
It was time for there to be an open source option for developers looking to integrate cannabis data into their applications. And how do you convince developers to use your platform?
Create a great service and even better tools to utilize it (documentation, guides, tutorials, etc).
I immediately went to work on the next phase of Kushy. We had an MVP with Wordpress, but it was slow and clunky, not the exact product we were looking to offer clients in the long run. The goal was to recreate the entire website from scratch (like we originally envisioned). We'd create components and modules that we could eventually piece together into a final product.
The Wordpress API was decent, but since it sat on top of an already bloated CMS, the load times were less than ideal. We wanted to be able to scale efficiently, but we also had resource constraints (I can't spend all day coding). The solution was the Directus API and SDK. Directus allowed us to create a PHP-based REST API with mySQL tables. It's SDK was an efficient library that made querying the API in our apps easier (see an example in our blog here).
Over night we had a fast API that allowed us to start creating the modules for the new site. And an API that anyone could use since it was open source.
Git me that ganja
I also had bigger plans for our data. We'd be the first company to release our cannabis data openly to the public on Github. Rather than forcing someone to use our rate-limited API (only so many server resources!), you can download our data and import it into your own API on your own servers. Take what you need, leave the rest. And when we get new data, like new products or strain info, we'll update the Github.
Utilizing git means data can be easily contributed by anyone, and it makes version controlling effortless. Someone edits a strain and accidentally commits wrong information? We can revert back to the previous iteration.
I created a couple test React applications to play with the framework and judge it's usability for our needs. React looked like a great tool, but like Netflix, I could see how it'd overcomplicate more simple site pages. But we'd use ReactJS mainly, because of our ability to recycle components and logic for React Native (when we actually have time and money for mobile apps).
Our stack would end up being a balance of PHP, vanilla JS, and React for complex state management. We'd always have a server side fallback for JS failing, due to the inconsistent nature of the browsing experience (user hardware, software, etc).
The easiest way to increase adoption of your software is documentation. If people don't know how to use it, they won't care to. The Directus API and SDK had documentation that was lacking, and didn't cover our data structure. So I set off to make our own.
I outlined our API docs in an Evernote file and looked for an out of the box solution for documentation. The first and most popular option I found was Slate, a Ruby gem, which didn't work well for me. I opted instead for a ReactJS static-site generator, GatsbyJS. It allowed me to easy break out the documentation different sections or "components".
This project is also open sourced, allowing for faster adaption through community contributions.
Our Wordpress MVP of Kushy is still online, and is indexing higher on Google than other similar cannabis directories. We've disabled registration to test private features like our patient verification - but you can browse over 1800 cannabis dispensaries, headshops, doctors, and more.
Our Directus API is also online and publicly accessibly at api.kushy.net. And our API documentation is temporarily available through Github Pages. If you're interested in authorization to contribute data to our public API, send us an email and we'll send you an API key. Please feel free to contribute, or critique our open source work - we only grow greater with more feedback.
Tell your friends, colleagues, and coworkers in the cannabis industry -- we're creating the future of cannabis data.