# rahul300rkv/arcana-ai architecture

> Architecture diagram of the GitHub repository rahul300rkv/arcana-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rahul300rkv/arcana-ai
- Repository: https://github.com/rahul300rkv/arcana-ai

## Overview

AstroFree is a multilingual tarot-reading and Vedic-numerology web app. Users enter through routed pages, choose a reading or calculator, and receive card interpretations or number-based results; tarot and numerology AI endpoints are documented with deterministic fallback. Guides, card meanings, daily-card content, and personal reading areas extend the core tools. The graph separates experience, domain logic, and server integrations. Some screens and AI service code were not sampled, so their links are shown only where documented or marked unverified.

Main entry points: [`src/screens`](https://github.com/rahul300rkv/arcana-ai/tree/main/src/screens) (Tarot Screens), [`server.ts`](https://github.com/rahul300rkv/arcana-ai/blob/main/server.ts) (API Server), [`src/routes/index.tsx`](https://github.com/rahul300rkv/arcana-ai/blob/main/src/routes/index.tsx) (Landing Page), [`src/lib/i18n.ts`](https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/i18n.ts) (Translations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web Experience"]
  node_routing["Route Registry<br/>[routeTree.gen.ts]"]
  node_app["App Router<br/>[App.tsx]"]
  node_landing["Landing Page<br/>[index.tsx]"]
end

subgraph group_tarot["Tarot Readings"]
  node_tarot_pages["Tarot Screens"]
  node_tarot_cards["Card Meanings"]
  node_tarot_engine["Deck and Draw<br/>[engine.ts]"]
  node_tarot_spreads["Spread Definitions<br/>[spreads.ts]"]
  node_tarot_interpret["Interpretations<br/>[interpret.ts]"]
  node_tarot_history["Reading History<br/>[history.ts]"]
  node_tarot_data["Card Content"]
end

subgraph group_numerology["Numerology"]
  node_numerology_pages["Numerology Screens"]
  node_numerology_engine["Number Engine<br/>[engine.ts]"]
  node_numerology_interpret["Number Meanings<br/>[interpret.ts]"]
  node_numerology_data["Numerology Content"]
end

subgraph group_content["Guides and Content"]
  node_guides["Guides and Articles"]
  node_daily["Daily Card<br/>[DailyCard.tsx]"]
  node_ads["Article Ads<br/>[InArticleAd.tsx]"]
end

subgraph group_platform["Server and Shared"]
  node_server["API Server<br/>[server.ts]"]
  node_numerology_ai["Numerology AI<br/>[ai.server.ts]"]
  node_tarot_ai["Tarot AI<br/>[ai.server.ts]"]
  node_translations["Translations<br/>[i18n.ts]"]
  node_language["Language State<br/>[language.ts]"]
  node_site["Site Metadata<br/>[site.ts]"]
  node_ads_config["Ad Configuration<br/>[adsense.ts]"]
end

node_visitor(("Visitor"))
node_gemini["Google Gemini"]

node_visitor -->|"opens app"| node_app
node_app -->|"loads routes"| node_routing
node_visitor -.->|"visits"| node_landing
node_landing -.->|"links to"| node_tarot_pages
node_landing -->|"links to"| node_numerology_pages
node_tarot_pages -.->|"draws cards"| node_tarot_engine
node_tarot_pages -.->|"uses spreads"| node_tarot_spreads
node_tarot_pages -.->|"shows meanings"| node_tarot_interpret
node_tarot_cards -.->|"shows meanings"| node_tarot_data
node_tarot_pages -.->|"stores readings"| node_tarot_history
node_server -->|"looks up spread"| node_tarot_spreads
node_server -->|"looks up cards"| node_tarot_engine
node_server -->|"requests generation"| node_gemini
node_numerology_pages -->|"calculates numbers"| node_numerology_engine
node_numerology_pages -->|"requests reading"| node_numerology_ai
node_numerology_pages -.->|"uses reference data"| node_numerology_data
node_server -->|"calculates numbers"| node_numerology_engine
node_numerology_ai -.->|"calls API"| node_server
node_tarot_ai -.->|"calls API"| node_server
node_guides -->|"renders ad"| node_ads
node_daily -.->|"uses card content"| node_tarot_data
node_tarot_pages -.->|"localizes interface"| node_translations
node_numerology_pages -->|"localizes interface"| node_translations
node_translations -->|"reads language"| node_language
node_guides -->|"uses site metadata"| node_site
node_ads -->|"uses ad settings"| node_ads_config

click node_routing "https://github.com/rahul300rkv/arcana-ai/blob/main/src/routeTree.gen.ts"
click node_app "https://github.com/rahul300rkv/arcana-ai/blob/main/src/App.tsx"
click node_landing "https://github.com/rahul300rkv/arcana-ai/blob/main/src/routes/index.tsx"
click node_tarot_pages "https://github.com/rahul300rkv/arcana-ai/tree/main/src/screens"
click node_tarot_cards "https://github.com/rahul300rkv/arcana-ai/blob/main/src/screens/TarotCardScreen.tsx"
click node_tarot_engine "https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/tarot/engine.ts"
click node_tarot_spreads "https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/tarot/spreads.ts"
click node_tarot_interpret "https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/tarot/interpret.ts"
click node_tarot_history "https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/tarot/history.ts"
click node_tarot_data "https://github.com/rahul300rkv/arcana-ai/tree/main/src/data/tarot-cards"
click node_numerology_pages "https://github.com/rahul300rkv/arcana-ai/tree/main/src/screens"
click node_numerology_engine "https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/numerology/engine.ts"
click node_numerology_interpret "https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/numerology/interpret.ts"
click node_numerology_data "https://github.com/rahul300rkv/arcana-ai/tree/main/src/data"
click node_guides "https://github.com/rahul300rkv/arcana-ai/tree/main/src/screens/guides"
click node_daily "https://github.com/rahul300rkv/arcana-ai/blob/main/src/components/app/DailyCard.tsx"
click node_ads "https://github.com/rahul300rkv/arcana-ai/blob/main/src/components/ads/InArticleAd.tsx"
click node_server "https://github.com/rahul300rkv/arcana-ai/blob/main/server.ts"
click node_numerology_ai "https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/numerology/ai.server.ts"
click node_tarot_ai "https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/tarot/ai.server.ts"
click node_translations "https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/i18n.ts"
click node_language "https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/language.ts"
click node_site "https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/site.ts"
click node_ads_config "https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/adsense.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_routing,node_app,node_landing toneBlue
class node_tarot_pages,node_tarot_cards,node_tarot_engine,node_tarot_spreads,node_tarot_interpret,node_tarot_history,node_tarot_data toneAmber
class node_numerology_pages,node_numerology_engine,node_numerology_interpret,node_numerology_data toneMint
class node_guides,node_daily,node_ads toneRose
class node_server,node_numerology_ai,node_tarot_ai,node_translations,node_language,node_site,node_ads_config,node_visitor,node_gemini toneIndigo
```

## Components

### Web Experience

- [Route Registry](https://github.com/rahul300rkv/arcana-ai/blob/main/src/routeTree.gen.ts): `src/routeTree.gen.ts`
- [App Router](https://github.com/rahul300rkv/arcana-ai/blob/main/src/App.tsx): `src/App.tsx`
- [Landing Page](https://github.com/rahul300rkv/arcana-ai/blob/main/src/routes/index.tsx): `src/routes/index.tsx`

### Tarot Readings

- [Tarot Screens](https://github.com/rahul300rkv/arcana-ai/tree/main/src/screens): `src/screens`
- [Card Meanings](https://github.com/rahul300rkv/arcana-ai/blob/main/src/screens/TarotCardScreen.tsx): `src/screens/TarotCardScreen.tsx`
- [Deck and Draw](https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/tarot/engine.ts): `src/lib/tarot/engine.ts`
- [Spread Definitions](https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/tarot/spreads.ts): `src/lib/tarot/spreads.ts`
- [Interpretations](https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/tarot/interpret.ts): `src/lib/tarot/interpret.ts`
- [Reading History](https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/tarot/history.ts): `src/lib/tarot/history.ts`
- [Card Content](https://github.com/rahul300rkv/arcana-ai/tree/main/src/data/tarot-cards): `src/data/tarot-cards`

### Numerology

- [Numerology Screens](https://github.com/rahul300rkv/arcana-ai/tree/main/src/screens): `src/screens`
- [Number Engine](https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/numerology/engine.ts): `src/lib/numerology/engine.ts`
- [Number Meanings](https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/numerology/interpret.ts): `src/lib/numerology/interpret.ts`
- [Numerology Content](https://github.com/rahul300rkv/arcana-ai/tree/main/src/data): `src/data`

### Guides and Content

- [Guides and Articles](https://github.com/rahul300rkv/arcana-ai/tree/main/src/screens/guides): `src/screens/guides`
- [Daily Card](https://github.com/rahul300rkv/arcana-ai/blob/main/src/components/app/DailyCard.tsx): `src/components/app/DailyCard.tsx`
- [Article Ads](https://github.com/rahul300rkv/arcana-ai/blob/main/src/components/ads/InArticleAd.tsx): `src/components/ads/InArticleAd.tsx`

### Server and Shared

- [API Server](https://github.com/rahul300rkv/arcana-ai/blob/main/server.ts): `server.ts`
- [Numerology AI](https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/numerology/ai.server.ts): `src/lib/numerology/ai.server.ts`
- [Tarot AI](https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/tarot/ai.server.ts): `src/lib/tarot/ai.server.ts`
- [Translations](https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/i18n.ts): `src/lib/i18n.ts`
- [Language State](https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/language.ts): `src/lib/language.ts`
- [Site Metadata](https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/site.ts): `src/lib/site.ts`
- [Ad Configuration](https://github.com/rahul300rkv/arcana-ai/blob/main/src/lib/adsense.ts): `src/lib/adsense.ts`

### Other components

- **Visitor**
- **Google Gemini**

## Connections

- Visitor → App Router: opens app
- App Router → Route Registry: loads routes (evidence: `src/App.tsx`)
- Visitor → Landing Page: visits
- Landing Page → Tarot Screens: links to
- Landing Page → Numerology Screens: links to (evidence: `src/routes/index.tsx`)
- Tarot Screens → Deck and Draw: draws cards
- Tarot Screens → Spread Definitions: uses spreads
- Tarot Screens → Interpretations: shows meanings
- Card Meanings → Card Content: shows meanings
- Tarot Screens → Reading History: stores readings
- API Server → Spread Definitions: looks up spread (evidence: `server.ts`)
- API Server → Deck and Draw: looks up cards (evidence: `server.ts`)
- API Server → Google Gemini: requests generation (evidence: `server.ts`)
- Numerology Screens → Number Engine: calculates numbers (evidence: `src/screens/NumerologyIndexScreen.tsx`)
- Numerology Screens → Numerology AI: requests reading (evidence: `src/screens/NumerologyIndexScreen.tsx`)
- Numerology Screens → Numerology Content: uses reference data
- API Server → Number Engine: calculates numbers (evidence: `server.ts`)
- Numerology AI → API Server: calls API
- Tarot AI → API Server: calls API
- Guides and Articles → Article Ads: renders ad (evidence: `src/screens/guides/GuideNumerologyScreen.tsx`)
- Daily Card → Card Content: uses card content
- Tarot Screens → Translations: localizes interface (evidence: `src/screens/NumerologyIndexScreen.tsx`)
- Numerology Screens → Translations: localizes interface (evidence: `src/screens/NumerologyIndexScreen.tsx`)
- Translations → Language State: reads language (evidence: `src/lib/i18n.ts`)
- Guides and Articles → Site Metadata: uses site metadata
- Article Ads → Ad Configuration: uses ad settings (evidence: `src/components/ads/InArticleAd.tsx`)
