Felicity Intelligence (WorldMap)
A real-time global intelligence dashboard built to track macro events, market shifts, and geopolitical movements — and translate them into actionable real estate opportunities in Dubai. This is not just data. This is decision-making power.
Live: https://felicity-world-map.vercel.app · Deploys automatically from main.
Environment Variables (Vercel → Settings → Environment Variables)
| Variable | Required | Purpose |
|---|
ANTHROPIC_API_KEY | Yes | Powers Ask Felicity, country intel, stock AI briefs, and the Mon/Thu newsletter brief (Claude) |
RESEND_API_KEY | Yes | All email: welcome, lead notifications, and the newsletter broadcast |
FINNHUB_API_KEY | Yes | Cockpit equity quotes, fundamentals and news; general-market headlines for the brief and Ask Felicity |
FROM_EMAIL | Recommended | Sender for all email, e.g. Felicity Intelligence <[email protected]>. Without it, emails send from Resend's test address, which only delivers to the Resend account owner. Verify the domain in Resend → Domains first. |
OWNER_EMAIL | No | Where lead/subscriber notifications go (default [email protected]) |
STRIPE_SECRET_KEY | For payments | Stripe Checkout subscriptions |
STRIPE_WEBHOOK_SECRET | For payments | Stripe webhook verification |
STRIPE_PRICE_PRO, STRIPE_PRICE_INSTITUTIONAL | For payments | Stripe Price IDs for the two plans |
ANALYTICS_KEY | For analytics | The owner's key for the private visitor dashboard at /analytics.html. Without it the stats endpoint refuses; visits are still recorded |
LIVE_LAYERS_TOKEN | Recommended | Shared secret for the live-layer relay. OpenSky and GDELT drop connections from Vercel's networks, so .github/workflows/live-layers.yml fetches aircraft, conflict-news locations and Hormuz headlines from a GitHub runner every 20 minutes and pushes them to POST /api/data?layer=ingest. Set the same value as a GitHub Actions secret and as a Vercel env var; without it the map says NO FEED |
OPENSKY_CLIENT_ID, OPENSKY_CLIENT_SECRET | No | OAuth2 client credentials from a free OpenSky account: raises the live-aircraft allowance from 400 to 4,000 credits/day (a global pull costs 4). Set them as GitHub Actions secrets too — the relay is what actually calls OpenSky |
CRON_SECRET | No | If set, /api/brief only accepts scheduled runs from Vercel Cron |
RESEND_AUDIENCE_ID | No | Pin the newsletter audience; otherwise auto-resolved by name |
DATABASE_URL | Recommended | Neon Postgres. Backs /api/data, and stores the newsletter list — without it the list can only live in a Resend Audience, which a send-only API key cannot write to |
UNSUB_SECRET | No | HMAC key for unsubscribe links; falls back to RESEND_API_KEY |
SITE_URL | No | Absolute origin used in unsubscribe links (default the Vercel URL) |
Strait of Hormuz Transit Monitor
The Hormuz tab has two layers. The live wire (GET /api/invest/hormuz-wire, 10-minute cache, polled while the page is open)
shows front-month Brent and WTI and the newest online headlines mentioning
the Strait (GDELT). The daily transits are the IMF PortWatch series
for portid='chokepoint6' via GET /api/invest/hormuz (no key, one-hour
cache; every pull is stored in Postgres and a daily cron re-pulls it, so a
PortWatch outage serves the last stored pull marked as such). Counts are
AIS-visible transits only — a floor, not every ship — published weekly
with a lag and revised, so the page shows the date of the last row rather
than "today". Means and the year-earlier comparison are computed from the
rows served and marked as Felicity arithmetic. There is no free, licensed
real-time ship count, so none is shown. Attribution: Source: International
Monetary Fund, PortWatch, https://portwatch.imf.org/pages/chokepoint6.
World Map live layers
GET /api/data?layer=flights returns OpenSky Network ADS-B positions of
every aircraft the network can hear (20-minute cache); ?layer=events
returns GDELT GEO locations of conflict-related news in the last 24 hours
(15-minute cache). Ships stay a labelled reference set — no free AIS feed
exists.
Dubai Market Data (the Felicity Price Index)
js/pix-data.js holds a snapshot of official Dubai Land Department
registered-transaction evidence, published as the Felicity Price Index
(the pix prefix in file and variable names is internal and never shown):
- Felicity Price Index — residential / apartment / villa levels, YoY, MoM,
median PSF, monthly transaction counts, plus a 13-month trend series.
- Per-area registry medians for all 19 tracked areas — median registered
sale PSF, median registered price, median registered annual rent, and a
gross yield computed as registered rent PSF ÷ registered sale PSF for
the same property-type cohort in the same community, over the last 12
complete months. Separate villa cohorts are carried where volume supports it.
buildDeskContext() renders this into the system prompt for both
Ask Felicity (api/desk/ask.js) and the newsletter brief (api/brief.js),
so the AI quotes registry numbers rather than assuming market direction.
Card values marked reg are registered DLD evidence; est marks a
Felicity desk estimate used only where the registry has no rental evidence
in the window (currently Jumeirah, DIFC, Dubai Islands).
Refreshing: the snapshot is manual and dated. DLD data closes by calendar
month, so monthly is the natural cadence — ask Claude to "refresh the price index
data" and it will re-query the registry tools and regenerate js/pix-data.js
and js/pix-signals.js. Update PIX_AS_OF, PIX_WINDOW and
PIX_SIGNALS_AS_OF when you do.
Investing Cockpit (Invest tab)
A 145-instrument multi-asset research desk: 105 S&P 500 stocks, 10 indices,
10 crypto, 10 FX pairs, 10 commodities.
- Live prices routed per asset class — Finnhub (equities), Yahoo Finance
(indices/FX/futures), CoinGecko (crypto). All server-side, no CORS proxies.
- Daily news per instrument — Finnhub company-news for equities, filtered
category news for everything else, last 7 days.
- TradingView chart for every instrument, plus a live ticker tape
across the top and three full-width market views: S&P 500 heatmap
(sector-grouped, market-cap sized), crypto heatmap, and a real
economic calendar covering the US, eurozone, UK, Japan, China,
Germany, UAE, India and Korea.
- Watchlist — star any instrument (stored in your browser). Two batch
actions: Sweep runs Felicity Bot across every holding with live
progress, and Daily news pulls the last 7 days for every holding into
one consolidated feed, ordered so the busiest names surface first.
- Investor profile — optional. Capital, currency, risk tolerance,
horizon, experience, max acceptable loss and existing constraints. With it
set, Felicity Bot sizes positions in real money and shows the arithmetic;
without it, sizing stays a percentage of risk budget. Stored in the
browser's localStorage only — never persisted or logged server-side.
- Felicity Bot (
POST /api/invest/advise) fetches the live quote and real
headlines first, then produces a positioned call: direction, conviction,
horizon, position size as % of risk budget, invalidation level, target,
thesis, bear case and catalysts. It is prompt-constrained never to invent a
price or a news event, and refuses to analyse if the live price is
unavailable.
Requires FINNHUB_API_KEY (quotes + news) and ANTHROPIC_API_KEY (analysis).
Newsletter
Subscribers are stored in a Resend Audience ("Felicity Intelligence Brief").
A Vercel Cron (vercel.json) hits /api/brief every Monday & Thursday
04:00 UTC (08:00 Dubai); Claude writes the brief and Resend broadcasts it
with per-contact unsubscribe links. Preview without emailing the list:
GET /api/brief?test=1 (sends only to OWNER_EMAIL).
Newsletter not arriving? Open /api/subscribe?diagnose=1 on the deployed
site. It reports which keys are set, which sender domains Resend has verified,
whether the audience resolves, and how many subscribers are stored — without
exposing any secret. Add &probe=1 to send one real test message to OWNER_EMAIL — with a send-only API key that is the only way to confirm the sender domain is verified. The most common cause is an unset or unverified FROM_EMAIL: mail then
goes out from Resend's test address, which only delivers to the Resend account
owner, so every other subscriber silently receives nothing.
Features
- Interactive World Map — Leaflet.js choropleth showing Country Instability Index (CII) scores for 100+ countries
- Conflict Zone Tracking — 14 active conflict zones with severity indicators
- Live Flight Monitoring — 15 tracked flights (commercial + military) with animated position updates
- Maritime Tracking — 11 vessels including cargo, tankers, and dark vessel detection
- Market Ticker — Real-time scrolling ticker with 8 major instruments (crypto, commodities, indices)
- News Feed — Categorized intelligence feed (Conflict, Politics, Markets, Energy)
- Dubai RE Signals — Geopolitical events translated into Dubai real estate opportunity signals
- AI Intelligence Briefs — Per-country intelligence summaries (requires Anthropic API key)
- Modal System — Proper modal dialogs replacing basic alerts
- Responsive Design — Desktop, tablet, and mobile layouts
Tech Stack
- HTML/CSS/JS — Vanilla, no build tools required
- Leaflet.js — Interactive mapping
- Inter + JetBrains Mono — Typography (Google Fonts)
- ES Modules — Modular JavaScript architecture
- CSS Custom Properties — Full design token system
- Neon PostgreSQL — Serverless database for dashboard data
- Vercel Serverless Functions — API routes connecting frontend to Neon
Project Structure
Felicity-WorldMap/
├── index.html Main entry point
├── vercel.json Vercel deployment config
├── package.json Dependencies (@neondatabase/serverless)
├── api/
│ └── data.js Vercel serverless function → Neon queries
├── db/
│ ├── schema.sql Database table definitions
│ ├── seed.sql Initial data population
│ └── setup.js Script to run schema + seed on Neon
├── css/
│ ├── tokens.css Design tokens (colors, spacing, typography)
│ ├── base.css Reset, global styles, utilities
│ ├── layout.css App grid, responsive breakpoints
│ ├── topbar.css Header bar, ticker, logo
│ ├── nav.css Navigation tabs
│ ├── map.css Map container, overlays, Leaflet overrides
│ ├── sidebar.css Sidebar, tabs, card components
│ ├── panels.css Country panel, modal system
│ ├── statusbar.css Bottom status bar
│ └── animations.css Keyframes, transitions
├── js/
│ ├── app.js Main init + orchestration
│ ├── data.js Data layer (API fetch + hardcoded fallback)
│ ├── map.js Leaflet map, GeoJSON, layers, markers
│ ├── sidebar.js Tab switching, card rendering
│ ├── ticker.js Market ticker logic
│ ├── panels.js Country panel, modal system
│ └── utils.js Clock, color helpers, formatting
└── assets/
└── favicon.svg Globe favicon
Run Locally
No build step needed. Just serve the files:
npm install # install dependencies (only needed once)
npm run dev # serves at http://localhost:3000
The dashboard works fully with hardcoded data locally. When deployed to Vercel with a Neon database, it fetches live data from the API instead.
Note: ES modules require a local server — opening index.html directly via file:// won't work due to CORS restrictions.
Deploy to Vercel + Neon
1. Create a Neon Database
- Sign up at neon.tech
- Create a new project and database
- Copy your connection string (looks like
postgresql://user:[email protected]/dbname?sslmode=require)
2. Seed the Database
DATABASE_URL="your-neon-connection-string" node db/setup.js
3. Deploy to Vercel
npm i -g vercel # install Vercel CLI
vercel # deploy (follow prompts)
vercel env add DATABASE_URL # add your Neon connection string as env var
vercel --prod # deploy to production
Or connect your GitHub repo in the Vercel dashboard — it will auto-deploy on push.
Architecture
Browser → Static HTML/CSS/JS (Vercel CDN)
↓ fetch('/api/data')
→ Vercel Edge Function (api/data.js)
↓ SQL queries
→ Neon PostgreSQL
If the API is unavailable (local dev, no Neon), the frontend falls back to hardcoded data seamlessly.
Design System
The dashboard uses a comprehensive design token system defined in css/tokens.css:
- Dark theme with deep backgrounds (#06080c → #141c2b)
- Accent: Cyan (#00d4ff) with glow effects
- Glass-morphism panels with backdrop-filter blur
- 4px spacing grid with consistent scale
- Semantic colors for status indicators (red/green/amber/blue)
License
Proprietary — Felicity Properties
