AstroAI documentation

AI-native astrology, tarot & numerology companion — Western (tropical) + Vedic (sidereal) — built with Flutter and a Next.js backend.

AstroAI is a single polished Flutter app that bundles three divination systems — Astrology, Tarot, and Numerology — across the Western (tropical) and Vedic (sidereal) traditions. Every reading is generated by a large language model that is grounded in a real, locally-computed chart — not static content, not a human-astrologer marketplace, and not a paid third-party astrology API.

What makes it stand out for buyers and reviewers alike:

• A real computation backbone — public-domain VSOP87 ephemeris charts, nakshatra + Vimshottari dasha, Guna Milan / Ashtakoot scoring, Pythagorean numerology, and a deterministic seeded tarot draw — with an AI narration layer on top. Not a thin GPT wrapper.
• Dual AI provider — OpenAI + Google Gemini, switchable with one server env var. API keys never ship in the app; every model call goes through JWT-authenticated /api/ai/* routes.
• Fully self-contained — no paid astrology/kundli APIs and no AGPL Swiss Ephemeris (its copyleft is incompatible with closed-source apps). Charts are computed on-device.
• Local-first — the entire app runs offline against bundled mock data, so a reviewer can launch it with zero backend.
• AI safety framing — a persistent “for reflection & entertainment” disclaimer, no death/serious-illness/doom predictions, no medical/legal/financial directives, and crisis sensitivity — all enforced in a centralized server-side prompt.

Mobile only (iOS + Android).

• Full Flutter source (lib/) + the full Next.js backend source (backend/).
• The deterministic computation engines (lib/computation/) — ephemeris, Western (whole-sign + Placidus toggle, aspects), Vedic (Lahiri / nakshatra / Vimshottari dasha / Guna Milan), Pythagorean numerology, seeded tarot — all unit-tested.
• A worldwide offline birthplace gazetteer (assets/geo/) — 34,000+ GeoNames cities with the IANA time zone per city, so the birth moment gets the offset that was actually in effect (DST included) rather than one fixed offset per city.
• Hive offline cache (profiles, history, readings) + a mock repository layer so the app runs fully offline; Prisma + Neon Postgres cloud sync for signed-in accounts.
• The Celestial Editorial design system — Material 3 dark ColorScheme, Playfair Display + DM Sans, glassmorphism, pill buttons.
• The Next.js /api/ai/* gateway — dual OpenAI/Gemini, JWT auth, server-side safety prompt, rate limiting, daily-horoscope caching.
• JWT accounts (email/password + native Google/Apple + guest) + cloud sync of profiles and history; RevenueCat subscriptions (+ webhook) and AdMob.
• Seed data (assets/seed/) + the offline demo path. This documentation. 6 months email support, lifetime updates.

Astrology — Western + Vedic

• Western: Sun / Moon / Rising, all planetary placements by sign & house, major aspects; whole-sign houses by default with a Placidus toggle.
• Vedic: Rashi (moon sign), Lagna (ascendant), Nakshatra; D1 kundli; a Vimshottari dasha timeline (current mahadasha/antardasha).
• Tradition filter (Western / Vedic / Both, default Both).

AI readings

• Daily / weekly horoscope — personalized to the chart, cached for offline + demo (free tier).
• Birth-chart deep-dive — long-form interpretation of the full natal chart.
• Compatibility — Western synastry + Vedic Guna Milan (deterministic score) with an AI-written narrative.
• Ask-the-stars chat — context-aware assistant with the user’s chart in context.

Tarot

78-card deck with a deterministic seeded shuffle/draw; single-card, 3-card, and Celtic Cross spreads; AI interpretation; saved history.

Numerology

Pythagorean Life Path, Expression, Soul Urge, Personality, and Birthday numbers, with AI narration. Fully deterministic.

Accounts, sync and monetization

• Email/password + native Google/Apple + guest. Cloud sync of profiles + history for accounts (guests stay local).
• Lean-free gating: only the daily/weekly horoscope is free (with AdMob); everything else is Pro. AdMob banner/interstitial + a rewarded one-off unlock; RevenueCat paywall + restore.

AI safety framing

Persistent “for reflection & entertainment” disclaimer; no death/serious-illness/doom predictions; no medical/legal/financial/mental-health directives (deflects to professionals); crisis sensitivity — enforced in the server-side system prompt.

Three strictly-separated layers: a local deterministic computation layer (no network), a server-side AI narration layer (the Next.js gateway), and the Flutter app layer. Charts compute on-device; the backend is the secure AI gateway + accounts + sync only.

astro-ai/
  lib/
    main.dart, app.dart      MaterialApp.router, theme, root providers
    core/        theme (Celestial Editorial), router, config, monetization, ads, providers
    computation/ deterministic engines (ephemeris, western, vedic, numerology, tarot, zodiac)
    data/        AstroApiClient (mock + live dio/JWT), Hive repos, sync
    features/<area>/{presentation,application,domain}
    domain/models/           freezed DTOs
  backend/       Next.js App Router — /api/{auth,ai,sync,webhooks}, Prisma, jose JWT
  assets/seed/   profiles.json, readings.json
  docs/codecanyon/   buyer documentation (this site)

Quick setup

Fast path:

1. 01
   flutter pub get
2. 02
   dart run build_runner build --delete-conflicting-outputs
3. 03
   Run offline with --dart-define=ASTROAI_BACKEND_URL=
4. 04
   (Optional) stand up the backend on Vercel/Neon (backend setup) and point the app at it.

The backend is a Next.js app under backend/. It holds the AI provider keys, applies the safety prompt, issues JWTs, and stores accounts/sync — the app never sees the keys.

1. 01
   Create a Neon Postgres project; copy the pooled (DATABASE_URL) and direct (DIRECT_URL) connection strings.
2. 02
   Import backend/ into Vercel → Settings → General → Root Directory = backend (Vercel auto-detects Next.js).
3. 03

   Add environment variables (Settings → Environment Variables):

   Vercel environment variablesCopy

   DATABASE_URL   = postgresql://...-pooler...neon.tech/neondb?sslmode=require
   DIRECT_URL     = postgresql://...neon.tech/neondb?sslmode=require
   AUTH_SECRET    = $(openssl rand -base64 32)
   AUTH_TOKEN_TTL = 30d
   AI_PROVIDER    = openai            # or gemini
   OPENAI_API_KEY = sk-...            # or GEMINI_API_KEY=...
   GOOGLE_CLIENT_ID = <web client id>   # native sign-in token verification
   APPLE_CLIENT_ID  = <service / bundle id>
   ENFORCE_PRO = false               # keep false until the RevenueCat webhook is live
   REVENUECAT_WEBHOOK_SECRET =

4. 04
   Deploy. The build runs prisma generate && prisma migrate deploy && next build, so the database schema is created/updated automatically on every deploy.
5. 05
   Verify: GET https://<your-app>.vercel.app/api/health → { "ok": true }.
6. 06

   Point the app at it:

   terminalCopy

   flutter run --dart-define=ASTROAI_BACKEND_URL=https://<your-app>.vercel.app

   (or change the default in lib/core/config/app_config.dart).

Routes

The Dart side is built (LiveAstroApiClient.signInWithProvider → the device ID token is exchanged at /api/auth/oauth for an app JWT). The Apple button is iOS-only (Platform.isIOS). Each buyer wires the providers:

Google

One Google Cloud project + OAuth consent screen, then three OAuth clients:

• Web client — its id goes to --dart-define=GOOGLE_SERVER_CLIENT_ID and the backend GOOGLE_CLIENT_ID. They must match (and the Web id is mandatory on Android).
• iOS client — id → --dart-define=GOOGLE_IOS_CLIENT_ID; add its reversed id as a URL scheme in ios/Runner/Info.plist.
• Android client — register the app’s SHA-1 (debug + release). No Android client id is passed in code.

Apple

• Enable “Sign in with Apple” (Apple Developer) + add the capability to the Runner target in Xcode; set the backend APPLE_CLIENT_ID (Service id / bundle id).
• Apple-on-Android (optional) needs --dart-define=APPLE_SERVICE_ID=… + APPLE_REDIRECT_URI=….

Choose OpenAI (OPENAI_MODEL, default gpt-4o) or Gemini (GEMINI_MODEL, default gemini-1.5-pro) via AI_PROVIDER in Vercel env. Keys live only in Vercel env.

• The server-side SAFETY_SYSTEM_PROMPT (backend/src/lib/ai/prompts.ts) is prepended to every call — centralized, not client-editable.
• Rate limiting (RATE_LIMIT_MAX / RATE_LIMIT_WINDOW_MS) is in-memory per warm instance — back it with Upstash Redis for production.
• Daily-horoscope responses are cached in the HoroscopeCache table by a client-supplied cacheKey.

RevenueCat

• Create the entitlement pro (the identifier must be exactly pro), an Offering with Monthly/Annual/Lifetime packages linked to your App Store / Play products, and paste your per-platform public SDK key into lib/core/monetization/monetization.dart (revenueCatApiKey).
• A RevenueCat Test Store key ships by default so the purchase flow works without store setup; an empty key falls back to a local demo unlock.
• Suggested prices: ~$4.99/mo · ~$29.99/yr · ~$49.99 lifetime.

Server enforcement (optional)

Set ENFORCE_PRO=true + a REVENUECAT_WEBHOOK_SECRET, and point the RevenueCat webhook at POST /api/webhooks/revenuecat (Authorization = that secret). The app calls Purchases.logIn(userId) so the event’s app_user_id matches the backend User.id.

AdMob

Put your banner/interstitial/rewarded unit ids in lib/core/ads/ad_ids.dart (Google test ids by default) and your AdMob app id in AndroidManifest.xml + Info.plist (GADApplicationIdentifier). Ads show on the free tier only.

• Android: flutter build appbundle --release (with your --dart-defines).
• iOS: flutter build ipa --release.
• After freezed/json/riverpod model changes: dart run build_runner build --delete-conflicting-outputs.
• Backend: cd backend && npm install, then vercel deploy (or push to the connected branch — migrations run in the build).

• Android: generate an upload keystore → android/key.properties (gitignored) → add a release signingConfig and point buildTypes.release at it. Register the keystore SHA-1/256 in Google Cloud for Google sign-in on release.
• iOS: Apple Developer → App Store Connect record → Xcode Runner → Signing & Capabilities (Team + Sign in with Apple) → flutter build ipa --release.

1. 01
   Branding — 4 native files + launcher icon.
2. 02
   Theme — lib/core/theme/theme.dart (AppColors).
3. 03
   Neon project + Vercel import (Root Directory backend) + env vars.
4. 04
   Deploy + verify /api/health; point the app at the backend URL.
5. 05
   Native sign-in — Google Web/iOS/Android clients + SHA-1 + iOS URL scheme; Apple capability + APPLE_CLIENT_ID.
6. 06
   AI_PROVIDER + the matching API key in Vercel env.
7. 07
   RevenueCat pro entitlement + offering + per-platform key (+ optional ENFORCE_PRO + webhook secret).
8. 08
   AdMob real unit ids + app id (replace test ids in ad_ids.dart + Info.plist/manifest).
9. 09
   Build + upload.

This item is at its first public version. Updates are free for the life of the item.

Version 1.1.0 · 2026-08-21Accurate birth times + dependency refresh

• New — worldwide birthplace search. The birthplace picker was a 7-city dropdown; it is now a search over 34,000+ cities bundled offline in assets/geo/ (GeoNames, CC BY 4.0), with diacritic-insensitive matching (“zurich” finds “Zürich”). Regenerate the data with dart run tool/generate_gazetteer.dart.
• Fixed — DST is now applied to the birth moment. Each city carries its IANA time zone, and the UTC offset is resolved at the birth instant instead of using one fixed offset per city. A July birth in New York is now EDT rather than EST — the previous one-hour error shifted the Ascendant by roughly 15°, often into a different rising sign, and moved every house cusp.
• Fixed — profile cloud sync. Birth times were sent without a timezone marker, so a backend host running in a non-UTC zone could shift the stored wall-clock time. The wire format is now explicit.
• Fixed — release builds crashed on launch. The ads SDK pulls androidx.work 2.7.0, whose ProGuard rules predate R8 full mode, so R8 stripped a class WorkManager loads reflectively and the app died before its first frame. Debug builds were unaffected. android/app/build.gradle.kts now pins a current WorkManager.
• Changed — dependencies updated to current stable: Next.js 16, Prisma 7 (with the pg driver adapter), OpenAI SDK 7, Zod 4, TypeScript 7, Riverpod 3.4, flutter_secure_storage 11.
• Changed — toolchain requirements: minimum Dart 3.12 (Flutter 3.44+), Android compileSdk 37, backend Node 22.12+ (Vercel Node 24.x).

Version 1.0.0 · 2026-06-16Initial release

Western + Vedic charts, dasha, deep-dive, compatibility, tarot, numerology, Ask-the-stars chat, daily/weekly horoscope, history + offline cache, accounts + cloud sync, RevenueCat + AdMob, Next.js AI gateway.

6 months of email support is bundled with your purchase.

Your Neon + Vercel project, OpenAI/Gemini keys, RevenueCat + AdMob accounts, and Google/Apple OAuth are your responsibility — we provide the setup walkthroughs, not the accounts.

What support covers

• Six months of support from purchase, extendable at checkout
• Support covers bugs in the template and questions about how it is put together
• It does not cover custom feature work, third-party API changes or store review outcomes
• The Regular licence covers one free end product. Charging users for the app itself needs the Extended licence