DEV Community

Birdircik
Birdircik

Posted on • Originally published at Medium

I Shipped a Tarot Card API to Every Major Package Registry in One Day

#api #opensource #showdev #sideprojects

Last week I had a simple idea: what if tarot card meanings were available as a developer resource on every major platform? Not as a SaaS product behind a paywall, but as free, open-source packages that anyone could npm install or pip install and start building with.

24 hours later, the same tarot card dataset — all 78 cards with upright meanings, reversed meanings, love interpretations, career guidance, and yes/no energy — was live on 10 different package registries, a Docker container, 6 AWS services, and had a live public API.

Here's exactly how I did it, and what I learned about developer distribution along the way.

The Dataset: 78 Cards, Structured for Machines

The tarot deck has a beautiful structure that maps perfectly to data:

  • 22 Major Arcana — The Fool through The World, representing life's spiritual lessons
  • 56 Minor Arcana — Four suits (Cups, Pentacles, Swords, Wands), each with Ace through King
  • Every card has: upright meaning, reversed meaning, love interpretation, career guidance, yes/no energy, keywords, and elemental association

I originally built this dataset for Deckaura, where we offer free interactive tarot reading tools — including a daily tarot card, yes or no tarot, and a birth card calculator. But I realized the data itself could be useful to thousands of developers building chatbots, Alexa skills, Discord bots, mobile apps, and AI-powered divination tools.

So I decided to make it available everywhere.

Stop 1: NPM (JavaScript/TypeScript)

The natural starting point. JavaScript runs everywhere.

npm install tarot-card-meanings
const tarot = require('tarot-card-meanings');
const card = tarot.getRandomCard();
console.log(`${card.name}: ${card.upright}`);

The package includes all 78 cards with full TypeScript types. It's zero-dependency and works in Node.js, browsers, and serverless functions.

Live: npmjs.com/package/tarot-card-meanings

I also published a CDK construct that deploys a complete tarot API to AWS with three lines of code:

npm install cdk-tarot-reading-api

Live: npmjs.com/package/cdk-tarot-reading-api

Stop 2: PyPI (Python)

Python is the go-to for data science and AI projects. Perfect for anyone building tarot-themed AI features.

pip install tarot-card-meanings
from tarot_card_meanings import get_random_card
card = get_random_card()
print(f"{card['name']}: {card['upright']}")

Live: pypi.org/project/tarot-card-meanings

Stop 3: Go Module

Go's module system made this incredibly clean. Tag a release, and pkg.go.dev picks it up automatically.

go get github.com/gokimedia/tarot-card-meanings-go
import tarot "github.com/gokimedia/tarot-card-meanings-go"

card := tarot.DailyCard()
fmt.Printf("%s: %s\n", card.Name, card.Upright)

The daily card function uses a date-seeded algorithm — everyone gets the same card on the same day, just like our Daily Tarot Card tool.

Live: pkg.go.dev/github.com/gokimedia/tarot-card-meanings-go

Stop 4: Crates.io (Rust)

Rust's type system is perfect for structured card data. Every card is a compile-time constant with zero runtime allocation.

cargo add tarot-card-meanings
use tarot_card_meanings::random_card;

let card = random_card();
println!("{}: {}", card.name, card.upright);

Live: crates.io/crates/tarot-card-meanings

Stop 5: JSR (Deno/TypeScript)

JSR is the new JavaScript registry with first-class TypeScript support and cross-runtime compatibility.

import { randomCard } from "jsr:@deckaura/tarot-card-meanings";

const card = randomCard();
console.log(`${card.name}: ${card.upright}`);

Live: jsr.io/@deckaura/tarot-card-meanings

Stop 6: Docker Hub

For people who want a ready-to-run API without installing anything:

docker pull gokimedia/tarot-card-meanings-api
docker run -p 8080:8080 gokimedia/tarot-card-meanings-api

Hit localhost:8080/card/random and you get a JSON response with a random tarot card. The API also supports /card/daily, /reading/yesno (3-card majority vote), and /reading/three (Past/Present/Future spread).

Live: hub.docker.com/r/gokimedia/tarot-card-meanings-api

Stop 7: AWS — Six Services Deep

This is where it got interesting. I didn't just deploy to one AWS service — I deployed to six:

AWS Lambda + API Gateway

A live, public API anyone can call right now:

curl https://m488bttpa3.execute-api.us-east-1.amazonaws.com/card/random

AWS Serverless Application Repository (SAR)

One-click deploy to anyone's AWS account. I published six SAR applications — one for the main tarot API, plus individual apps for numerology, zodiac compatibility, angel numbers, moon phases, and spirit animal quiz.

AWS ECR Public Gallery

The Docker image is also on Amazon's container registry, with full documentation and usage instructions.

AWS App Runner

A fully managed container deployment — auto-scaling, HTTPS, zero DevOps.

AWS Amplify

A static demo site showcasing the interactive tarot reading experience.

AWS CloudFront

CDN-backed static sites for each tool — fast loading from edge locations worldwide.

The Live API

The crown jewel: a free, public tarot card API with these endpoints:

Endpoint What it does
GET / HTML docs page with all info
GET /card/random Draw a random card with full meaning
GET /card/daily Today's card (same for everyone)
GET /reading/yesno Yes/No reading via 3-card vote
GET /reading/three Past/Present/Future spread
GET /cards All 22 Major Arcana

Every response includes the card's upright and reversed meanings, love and career interpretations, yes/no energy, keywords, and elemental association.

What I Learned

1. Write Once, Distribute Everywhere

The core data structure is identical across every language. I defined the 78-card dataset once and translated it into JavaScript, Python, Go, Rust, TypeScript, Ruby, PHP, and Dart. The business logic (random draw, daily card, yes/no voting) is maybe 50 lines in any language.

2. Package Registries Are Free Real Estate

Every registry gives you a public page with your README rendered in full. That's a permanent, indexed page on a high-authority domain. If your README is useful and well-structured, people find it through search.

3. AWS Has More Deployment Surfaces Than You Think

S3 static websites, SAR, ECR Public Gallery, App Runner, Amplify, CloudFront, Lambda Function URLs, API Gateway — each one is a different way to serve the same content, and each creates a different public URL.

4. APIs Should Have HTML Homepages

I made the mistake of initially serving only JSON at the root endpoint. Search engines can't do much with JSON. Adding an HTML homepage with proper meta tags and internal links made the API discoverable.

What You Can Build With This

  • Tarot chatbots — Slack, Discord, Telegram, WhatsApp
  • Alexa/Google Assistant skills — Voice-activated tarot readings
  • Mobile apps — iOS/Android tarot apps with real card data
  • AI tarot readers — Combine with GPT/Claude for personalized interpretations
  • Daily horoscope features — Use the /card/daily endpoint for content
  • Tarot journaling apps — Track readings over time
  • Educational tools — Teach tarot card meanings interactively

Try It Yourself

Use the packages:

  • JavaScript: npm install tarot-card-meanings
  • Python: pip install tarot-card-meanings
  • Go: go get github.com/gokimedia/tarot-card-meanings-go
  • Rust: cargo add tarot-card-meanings
  • Deno: import from "jsr:@deckaura/tarot-card-meanings"
  • Docker: docker pull gokimedia/tarot-card-meanings-api

Use the live API:

curl https://m488bttpa3.execute-api.us-east-1.amazonaws.com/card/random

Try the interactive tools:

Source code: github.com/gokimedia/tarot-reading

Built by Deckaura — free tarot reading tools and premium tarot decks with free worldwide shipping. Every package is MIT licensed. Use it however you want.

Top comments (0)