Skip to main content
The Lacanians
Engineering9 min read

Introducing Tarot Agent: AI-Powered Tarot Readings with Vue and Nuxt

Tarot Agent combines Nuxt 4, Vue 3, and the Vercel AI SDK to deliver free, streaming tarot readings with a full 78-card pixel-art deck and a dark mystical interface.

A

Abdul Hamid Achik

·Updated

The Best AI Products Are Focused

Most AI products try to do everything. They bolt a chat interface onto a general-purpose model, add a dozen integrations, and call it a platform. The result is a tool that does many things adequately and nothing well.

Tarot Agent takes the opposite approach. It does exactly one thing: AI-powered tarot readings. You type a question, pick a spread, and get a streaming interpretation from an AI reader persona, laid out with a full 78-card pixel-art deck. No account required, no paywalls, no feature bloat. Open the page and ask your question.

This is what focused AI product design looks like.

The Stack

Tarot Agent is built on Nuxt 4 with Vue 3, styled with Nuxt UI and Tailwind CSS 4, and streams its readings through the Vercel AI SDK and Vercel AI Gateway. The deployment target is Vercel.

Nuxt 4 (Vue 3 + Nitro, SSR)
├── Nuxt UI 4 + Tailwind CSS 4 (custom mystic theme)
├── AI SDK 7 via Vercel AI Gateway
├── Neon Postgres (Drizzle ORM)
├── Redis (rate limiting)
├── Resend (emailed readings, archive login codes)
├── Cinzel + DM Sans
└── Vercel (deployment)

The choice of Nuxt over a plain Vue SPA is deliberate. Tarot Agent needs server-side rendering for SEO and social sharing, because when someone shares a reading, the preview card should actually say something meaningful. More importantly, Nitro server routes provide a clean way to call the model without exposing API keys to the client.

How the AI Readings Work

The core interaction is deceptively simple: user asks a question, selects a spread type, and the app streams back a tarot interpretation in real time. Under the hood, this is a Nuxt server route that draws the cards, then streams a model response over server-sent events.

The architecture follows a pattern we use often: the client makes a single request, the server route handles the AI interaction, and the response streams back chunk by chunk. The cards are drawn on the server, so the client cannot pick them.

// server/api/reading.post.ts (simplified)
export default defineEventHandler(async (event) => {
  const parsed = createReadingRequestSchema.safeParse(await readBody(event))
  if (!parsed.success) {
    throw createError({ statusCode: 400, statusMessage: 'Invalid reading request.' })
  }
  const { question, spreadType } = parsed.data

  await assertRateLimit({
    key: `reading:${getOrCreateAnonymousSessionId(event)}`,
    limit: 12,
    windowMs: 60 * 60 * 1000,
    message: 'Too many readings requested. Please try again later.',
  })

  const cards = drawCards(spreadType)
  const stream = await createReadingStream({
    gatewayApiKey: requireAiGatewayApiKey(event),
    question,
    spreadType,
    cards,
    initialEvents: [{ type: 'cards', cards }],
  })

  setResponseHeader(event, 'Content-Type', 'text/event-stream')
  setResponseHeader(event, 'Cache-Control', 'no-cache')
  return sendStream(event, stream)
})

The model call lives in a helper and goes through Vercel AI Gateway, so swapping models is a one-line change:

// server/utils/tarot-agent.ts (simplified)
import { createGateway, streamText } from 'ai'

const gateway = createGateway({ apiKey: gatewayApiKey })

const result = streamText({
  model: gateway('google/gemini-2.5-flash'),
  maxOutputTokens: 2048,
  temperature: 0.85,
  system: buildSystemPrompt(spreadType),
  prompt: buildUserMessage(question, cards, spreadType),
  providerOptions: {
    gateway: {
      models: ['anthropic/claude-haiku-4.5', 'google/gemini-2.5-flash-lite'],
      sort: 'cost',
    },
  },
})

for await (const text of result.textStream) {
  controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: 'text', content: text })}\n\n`))
}

The default model is Gemini 2.5 Flash, with Claude Haiku 4.5 and Gemini 2.5 Flash-Lite as gateway fallbacks. The model list is isolated in one file, so experiments do not touch the prompt code. The first version of the app called Claude directly through the Anthropic SDK; moving to the gateway made it cheap to compare models without changing the route.

The system prompt is where the personality lives. It casts the model as Aurelia, a reader who has been working the cards for thirty years, and instructs her to weave the drawn cards together in context of the question and spread positions rather than listing them one by one. The prompt engineering matters here: too formal and it reads like a textbook, too casual and it loses the sense of ritual that makes tarot readings feel meaningful.

On the client side, a Vue composable (useTarotReading) manages the streaming state. It posts the question, reads the response body, and parses each server-sent event as it arrives:

// app/composables/useTarotReading.ts (simplified)
const response = await fetch('/api/reading', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ question: question.value, spreadType: spreadType.value }),
})

const reader = response.body!.getReader()
const decoder = new TextDecoder()
let buffer = ''

while (true) {
  const { done, value } = await reader.read()
  if (done) break

  buffer += decoder.decode(value, { stream: true })
  const lines = buffer.split('\n')
  buffer = lines.pop() ?? ''

  for (const line of lines) {
    if (!line.startsWith('data: ')) continue
    const payload = JSON.parse(line.slice(6))

    if (payload.type === 'cards') cards.value = payload.cards
    if (payload.type === 'text') readingText.value += payload.content
    if (payload.type === 'done') isStreaming.value = false
  }
}

The streaming is the key UX decision. A tarot reading that appears all at once feels like a search result. A reading that streams in word by word feels like someone is actually interpreting your cards. The latency becomes a feature.

Six Spread Types

Tarot Agent supports six spread types, each with its own layout and interpretation structure:

  • Single Card (1 card): one card, one answer. Good for quick daily guidance.
  • Yes or No (1 card): binary question, single card with a directional interpretation.
  • Three Card (3 cards): past, present, future. The classic spread.
  • Love (5 cards): you, the other person, the connection, the challenge, and the potential.
  • Career Path (5 cards): current position, the obstacle, hidden influence, the action, and the outcome.
  • Celtic Cross (10 cards): the full spread for deep, nuanced readings.

Each spread defines its positions and its own reading guide, and the AI receives both the cards drawn and the positional context. A card in the “challenge” position of a Celtic Cross reads very differently than the same card in the “outcome” position. Modern LLMs handle this contextual interpretation naturally, which is exactly the kind of task they excel at: synthesizing structured input into coherent narrative.

Pixel-Art Cards and Flip Animations

All 78 cards of the deck, Major and Minor Arcana, have a custom pixel-art illustration. This is not a stock image library. The art style is intentional: pixel art gives the cards a distinctive, slightly retro aesthetic that stands apart from the ornate Victorian imagery most tarot apps use. It also keeps file sizes small and scales cleanly at any resolution.

The card reveal uses a CSS flip animation:

.card-flip {
  perspective: 1000px;
}

.card-flip-inner {
  transition: transform 0.8s cubic-bezier(0.4, 0, 0.2, 1);
  transform-style: preserve-3d;
}

.card-flip-inner.flipped {
  transform: rotateY(180deg);
}

.card-face {
  backface-visibility: hidden;
  position: absolute;
  inset: 0;
}

.card-back {
  transform: rotateY(0deg);
}

.card-front {
  transform: rotateY(180deg);
}

The cards start face down, then flip one after another (staggered by 200 milliseconds in multi-card spreads) to reveal the illustrations as the reading begins. It is a small touch, but it adds the moment of anticipation that makes a tarot reading feel like a tarot reading, not just a text generation exercise.

The Dark Mystical UI

The visual design commits fully to its theme. The base background is a deep navy (#0a0a1a) with gold accents (#d4a853), built as a custom Tailwind CSS 4 theme on top of Nuxt UI:

@theme {
  --color-mystic-900: #0a0a1a;
  --color-mystic-800: #12122e;
  --color-mystic-700: #1a1a42;
  --color-mystic-500: #35357a;
  --color-mystic-300: #8888cc;
  --color-mystic-100: #ddddee;

  --color-gold-500: #d4a853;
  --color-gold-400: #e0be6e;
  --color-gold-300: #ebd48a;
}

Typography pairs Cinzel for headings (a serif with engraved, classical letterforms that evoke the arcane) with DM Sans for body text, keeping the interface readable when the AI is streaming paragraphs of interpretation.

A starfield painted with CSS radial gradients in the background reinforces the mystical atmosphere without distracting from the content. The entire visual language says “this is a place for reflection,” which is exactly the mood you want when someone is asking a question they care about.

One Page, Few Moving Parts

Tarot Agent is built around a single page. There is no feed, no dashboard, no social graph. You arrive, you ask, you read. The whole flow lives on the home page, which is prerendered, with state transitions managed by Vue’s reactivity system.

That does not mean nothing is stored. Every reading is saved on the server, which is what makes the share link work: each reading gets a slug and a public /r/<slug> page whose preview card says something meaningful. From there you can replay a reading, email it to yourself, or create an optional archive (an email address and a six-digit login code, no password) to keep your readings together. The product stays honest about what it is: a place to ask one question at a time, not a journal that demands an account.

From an engineering perspective, the constraint still simplifies a lot. The only real-time interaction is the streaming model call. Rate limiting keeps costs predictable, at twelve readings per hour per visitor. Deployment is a single Vercel project, with environment variables for the AI Gateway key, the Neon database, Redis, and Resend.

Why This Matters

Tarot Agent is not interesting because of its tech stack. Nuxt, Vue, Tailwind, and the AI SDK are all well-established tools. It is interesting because of what it chooses not to do.

The current wave of AI products suffers from feature anxiety. Every product wants to be a platform. Every chatbot wants to handle every domain. The result is a landscape of tools that are technically impressive and practically unfocused.

Tarot Agent picks one domain, builds a complete experience for it, and stops. The AI is not a general-purpose assistant wearing a tarot costume. It is a tarot reader. The UI is not a chat interface with a theme. It is a tarot table. The product does not ask you to sign up, subscribe, or integrate with anything to get a reading. It asks you to ask a question.

This is the model we advocate for when building AI products: find a specific human experience that AI can genuinely enhance, build the minimum product that delivers that experience well, and resist the urge to add everything else. The constraint is the feature.

Try it at tarotagent.app. Ask it something you have been thinking about. The cards are waiting.

A

Abdul Hamid Achik

Founder and lead engineer at The Lacanians. Abdul builds production software, developer tools, and local-first systems from Guadalajara for teams worldwide.