Built for the AstroLive Product & Growth Hackathon Challenge
A live business solution engineered to solve AstroLive's top-of-funnel acquisition, engagement, retention, and monetization bottlenecks.
AstroLive is a fast-growing astrology consultation and divination platform where thousands of users connect via real-time calls and chats with expert astrologers every single day. Operating at scale, AstroLive faces classic marketplace bottlenecks: high customer acquisition costs (CAC), passive horoscope consumption, drop-offs during onboarding, and friction in converting cold-traffic visitors into high-intent paid astrologer consultations.
"Review AstroLive in its current form and identify one or more product opportunities to address. Your solution should focus on building structural virality that drives organic growth, creating a habit-forming user experience that encourages users to return naturally, unlocking new revenue opportunities beyond the current business model, or defining a compelling Unique Selling Proposition (USP) that makes your solution the preferred choice over other platforms."
AstroLens is an end-to-end working prototype that tackles all four core hackathon pillars by transforming the user's physical hand into an interactive, biometric cosmic gateway:
┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ASTROLENS VALUE MATRIX FOR ASTROLIVE │
├──────────────────────────┬──────────────────────────────────────────────────────────────────────┤
│ 🌟 1. Compelling USP │ Real-Time CV Palmistry (MediaPipe + OpenCV) + Google Gemini AI. │
│ (Defensible Moat) │ Replaces tedious birth-time forms with 5-second tangible biometric │
│ │ analysis, eliminating "Barnum Effect" skepticism with 300%+ trust. │
├──────────────────────────┼──────────────────────────────────────────────────────────────────────┤
│ 🚀 2. Structural Virality│ Dual Viral Loops: High-res downloadable Aura Cards for social media │
│ (Organic K-Factor) │ + URL-safe base64 `?compare=` viral compatibility invites that turn │
│ │ 1-player readings into multiplayer relationship challenges. │
├──────────────────────────┼──────────────────────────────────────────────────────────────────────┤
│ ⚡ 3. Habit-Forming │ Daily Cosmic Pulse: 60-second morning alignment ritual with 4-tier │
│ Retention Loop │ streak milestones, tomorrow's teaser signals, and a Longitudinal │
│ │ Cosmic Timeline charting aura evolution over weeks and months. │
├──────────────────────────┼──────────────────────────────────────────────────────────────────────┤
│ 💰 4. New Revenue & │ 2-Tier Monetization: Instant ₹399 Digital Cosmic Blueprint unlock │
│ AstroLive Funnel │ + High-intent Contextual Escalation Funnel directly into ₹2,999– │
│ │ ₹9,999 live AstroLive 1-on-1 human astrologer consultations. │
└──────────────────────────┴──────────────────────────────────────────────────────────────────────┘
For hackathon judges and evaluators, AstroLens includes instant test modes and bypasses:
| URL Parameter / Mode | Purpose & Experience | Target Evaluation |
|---|---|---|
Default (/) |
Full interactive web application with real-time webcam palm scanning. | End-to-end user journey & CV accuracy |
?demo=true |
Instant Judge Mode: Pre-loaded biometric scan result (bypasses webcam). | Rapid UX, AI reading & UI inspection |
?compare=ENCODED |
Viral Recipient Mode: Personalized invitation landing page for partners. | Viral K-factor onboarding & social loop |
?dashboard=true |
Product Impact Control Center: Live analytics, North Star CAU & funnels. | Business metrics, retention & unit economics |
- 21 3D Hand Landmark Tracking: Powered by MediaPipe Hands to detect wrist, knuckles, and fingertips in real-time.
-
Palm ROI Normalization: Geometric affine transformation to extract a standardized
$256 \times 256$ region of interest. - Computer Vision Extraction Pipeline: Adaptive CLAHE histogram equalization, Gaussian blur filtering, and Canny edge contour detection.
- Biometric Line Prominence: Quantifies the Life Line (vitality), Head Line (intellect & focus), and Heart Line (emotional resonance).
-
Aura Score & Archetype: Dynamically computes Aura Score (
$0\text{--}100$ ) and assigns celestial archetypes (Crimson Trailblazer, Indigo Visionary, Gold Luminary, etc.).
- Deep Biometric Prompt Engineering: Injects calculated line prominence metrics into Google Gemini (
gemini-2.0-flash) for deeply contextual, structured JSON readings. - Aura Cards & Web Share API: Generates high-fidelity shareable graphic cards via
html2canvasfor Instagram Stories and WhatsApp sharing.
- Daily 60-Second Ritual: Morning habit check-in offering daily theme, energy resonance, and focus alignment.
- 4-Tier Streak Progression: Gamified milestones (3-Day Cosmic Explorer, 7-Day Pattern Seeker, 14-Day Deep Observer, 30-Day Cosmic Insider).
- Tomorrow Preview Teaser: Unlocks predictive celestial hints upon completing today's check-in.
- Multi-Vector Resonance: Calculates energetic, intellectual, and emotional compatibility between user palm metrics and partner signs.
- Base64 Invite Generation: Generates zero-backend, privacy-safe
?compare=links containing encoded profile coordinates. - Recipient Onboarding Flow: Seamless landing page prompting the recipient to scan their palm and unlock their mutual connection score.
- 12-Section Deep Dossier: Comprehensive astrological breakdown (Core Energetics, Palm Line Topology, Planetary Alignments, Karmic Trajectories).
- Key Pattern Surfacing: Automatically highlights unresolved energetic polarities and karmic tensions detected in the biometric scan.
- Contextual AstroLive Funnel: Connects high-intent users directly to verified AstroLive human astrologers (₹2,999 – ₹9,999) with their biometric blueprint pre-attached.
- Reverse-Chronological Spine: Visualizes the user's ongoing astrological evolution across successive readings.
- Aura Evolution Tracker: Trajectory delta (
69 → 72 → 78), direction badges, and line prominence trends over time. - Cosmic Shift (Before vs. Now): Side-by-side comparative analysis synthesizing tangible energetic shifts.
- Internal Control Center: Accessible via
?dashboard=trueor directly from My Universe. - North Star Metric: Cosmically Active Users (CAU) — tracking weekly habit-forming engagement.
- 8-Stage Funnel Telemetry: Measures conversion across Discovery → Scan → Result → Pulse → Viral Share → Compatibility → Blueprint → AstroLive Consultation.
- Live Local Telemetry vs. Benchmark Mode: Toggle between browser-stored user behavior and cohort baselines.
[ Webcam Stream / User Frame ]
│
▼
[ MediaPipe Hands (21 Landmarks) ]
│
▼
[ Affine Crop to Palm ROI (256x256) ]
│
▼
[ CLAHE + Gaussian Blur + Canny Edges ]
│
▼
[ Line Prominence Evaluator (Life/Head/Heart) ]
│
▼
[ Aura Score (0-100) + Celestial Archetype ]
│
▼
[ Google Gemini 2.0 Flash AI API ]
│
┌───────────┴───────────┐
▼ ▼
[ Personalized Reading ] [ 12-Section Deep Blueprint ]
│ │
▼ ▼
[ Viral Social Cards ] [ AstroLive Consultation Funnel ]
AstroLens/
├── backend/ # FastAPI Python Computer Vision & AI Backend
│ ├── app.py # Server entry point, CORS & routing
│ ├── cv_pipeline.py # MediaPipe + OpenCV palm extraction & edge scoring
│ ├── llm_service.py # Google Gemini API structured prompt engine
│ ├── routers/
│ │ ├── scan.py # POST /api/scan | GET /api/demo
│ │ └── blueprint.py # POST /api/blueprint (Gemini Deep Dossier)
│ ├── requirements.txt # Python dependencies
│ ├── Dockerfile # Container configuration
│ └── railway.toml # Cloud deployment manifest
└── frontend/ # React 19 + Vite Frontend SPA
├── src/
│ ├── App.jsx # Root router, query param handlers & navigation
│ ├── index.css # Cosmic design system tokens & glassmorphism
│ ├── components/
│ │ ├── CosmosCanvas.jsx # Interactive celestial canvas background
│ │ ├── StarField.jsx # Ambient constellation particle layer
│ │ ├── LandingPage.jsx # Hero presentation & value proposition
│ │ ├── Scanner.jsx # Live webcam capture & landmark guide
│ │ ├── ResultCard.jsx # Biometric score presentation & aura ring
│ │ ├── ShareCard.jsx # High-resolution social share card generator
│ │ ├── History.jsx # Local scan chronicle
│ │ ├── Universe.jsx # My Universe & Longitudinal Cosmic Timeline
│ │ ├── Compatibility.jsx # Cosmic resonance & viral invite creator
│ │ ├── InviteLanding.jsx # Viral compare recipient experience
│ │ ├── PremiumBlueprint.jsx # 12-section dossier & AstroLive funnel
│ │ └── GrowthDashboard.jsx # Product impact & growth control center
│ ├── utils/
│ │ ├── profileStorage.js # Cosmic profile state persistence
│ │ ├── pulseStorage.js # Daily Palm Pulse retention logic
│ │ ├── compatibilityEngine.js# Multi-vector astrological calculation
│ │ ├── compatibilityInvite.js# URL-safe base64 invite codec
│ │ ├── blueprintEngine.js # Dossier generation engine with fallback
│ │ ├── timelineEngine.js # Longitudinal trajectory analysis
│ │ └── growthMetrics.js # Telemetry & funnel metrics tracker
│ └── services/api.js # Resilient API client with mock fallbacks
└── vite.config.js
| Layer | Technologies & Libraries |
|---|---|
| Frontend Framework | React 19, Vite |
| Styling & Design System | Vanilla CSS (CSS Variables, Glassmorphism, Responsive Grid, Cosmic Gradients) |
| Computer Vision | MediaPipe (mp.solutions.hands), OpenCV (cv2), NumPy |
| Generative AI | Google Gemini API (gemini-2.0-flash) via google-genai |
| Backend API | FastAPI, Uvicorn, Python 3.11+ |
| Sharing & Graphics | html2canvas, Web Share API, HTML5 Canvas 2D |
| Privacy & Storage | Local-First Architecture (localStorage), Zero Persistent Biometric Tracking |
- Node.js: v18+ (v20+ recommended)
- Python: 3.10+ (3.11 recommended)
- Gemini API Key: Free key from Google AI Studio (Optional: app operates with graceful fallback if no key provided)
cd backend
# Create and activate virtual environment
python -m venv venv
venv\Scripts\activate # Windows
# source venv/bin/activate # macOS / Linux
# Install dependencies
pip install -r requirements.txt
# Configure environment variables
cp .env.example .env
# Open .env and set your GEMINI_API_KEY
# Launch FastAPI server
python app.py
# → Running at http://localhost:8000cd frontend
# Install dependencies
npm install
# Launch Vite development server
npm run dev
# → Running at http://localhost:5173| Variable | Location | Description | Default | Required |
|---|---|---|---|---|
GEMINI_API_KEY |
backend/.env |
Google AI Studio API key | "" |
Optional (graceful fallback) |
GEMINI_MODEL |
backend/.env |
Gemini model name | gemini-2.0-flash |
No |
ALLOWED_ORIGINS |
backend/.env |
CORS allowed origins | * |
No |
VITE_API_URL |
frontend/.env |
Backend API URL for frontend | http://localhost:8000 |
No |
| Hackathon Criterion | AstroLens Implementation & Proof Points |
|---|---|
| 1. Compelling USP & Defensible Moat | Replaces generic birthdate forms with physical palm computer vision (MediaPipe + OpenCV), establishing immediate user trust and tangible personal connection. |
| 2. Structural Virality | Dual-share mechanism: (a) Downloadable high-res Aura Cards for Instagram/WhatsApp, and (b) URL-safe ?compare= viral invitations for multiplayer compatibility matching. |
| 3. Habit-Forming Retention | 60-second Daily Palm Pulse morning ritual with 4-tier milestone streaks, preview teasers for tomorrow, and a Longitudinal Cosmic Timeline tracking palm and aura evolution over time. |
| 4. New Revenue & AstroLive Escalation | 2-tier monetization model: ₹399 instant digital blueprint download + ₹2,999–₹9,999 contextual 1-on-1 AstroLive astrologer consultation conversion funnel. |
| 5. Live Operational & Business Impact | Embedded Growth Dashboard (?dashboard=true) showcasing North Star metric (Cosmically Active Users), 8-stage conversion funnel, and cohort metrics. |
| 6. Technical Feasibility & Production Readiness | Clean decoupling of React 19 frontend and FastAPI CV/AI backend with Docker and Railway deployment configs. Zero-friction ?demo=true mode for instant evaluation. |
AstroLens — Built for the AstroLive Product & Growth Hackathon Challenge · Powered by MediaPipe, OpenCV & Google Gemini AI