Charlotte Watch
Real-time dashboard for Charlotte, NC metro area
Monitor weather, traffic alerts, transit, power outages, news, and markets — all in one place.
Live: clt.watch
Table of Contents
What is Charlotte Watch?
Charlotte Watch is a real-time monitoring dashboard for residents of the Charlotte, NC metro area. It aggregates critical information from multiple sources into a single, customizable interface.
Widgets
Each widget is an independently updating panel on the dashboard. Widgets can be rearranged and resized, and each refreshes on its own schedule so data stays current without a page reload.
| Widget | Description |
|---|
| Alerts | Unified feed from 9 sources with AI-powered BLUF summary and interactive map |
| Weather | Current conditions, NWS alerts, forecast, radar map, air quality, and pollen |
| LYNX Transit | Real-time vehicle positions on Blue and Gold Lines, service alerts |
| News | Charlotte-area RSS news parsed and categorized by AI |
| Markets | Real-time stock quotes for CLT-area public companies |
Alert Sources
The Alerts widget aggregates from 9 sources simultaneously:
- NWS — National Weather Service warnings and advisories
- FAA — CLT airport delays and ground stops
- NCDOT — Traffic incidents and construction
- Duke Energy — Power outage reports
- CATS — Charlotte Area Transit service disruptions
- CMPD — Charlotte-Mecklenburg Police advisories
- CFD — Charlotte Fire Department alerts
- CMS — Charlotte-Mecklenburg Schools notifications
- HERE — Real-time traffic flow incidents
For Developers
Quick Start
Option 1: Basic development (no API functions)
npm install
npm run dev
# Open http://localhost:5173
Most widgets work without API keys. Stocks, AI summaries, air quality, pollen, and some alert feeds require keys.
Option 2: Full development (with API functions)
npm install
cp .env.example .dev.vars # Then fill in your API keys
npm run dev:pages
# Open http://localhost:8788
This mode uses Wrangler to run Cloudflare Pages Functions locally, which is required for AI summaries, stock quotes, and any endpoint that needs API keys.
Prerequisites
Available Scripts
# Development
npm run dev # Vite dev server only (no serverless functions)
npm run dev:pages # Full dev with Cloudflare Pages Functions (requires wrangler)
# Build
npm run build # TypeScript compile + Vite production build
npm run preview # Preview the production build locally
# Quality checks (run after every change)
npm run check:fix # Format + lint (auto-fix) + type-check
npm run check # Format + lint + type-check (read-only)
# Individual checks
npm run type-check # TypeScript type checking (frontend)
npm run type-check:functions # TypeScript type checking (functions/)
npm run lint # ESLint
npm run lint:fix # ESLint with auto-fix
npm run format # Prettier format
npm run format:check # Prettier check (no write)
# Tests
npm test # Run all tests once
npm run test:watch # Run tests in watch mode
# Workers
npm run deploy:cache-warmer # Deploy the cache warmer worker to Cloudflare
Always run before committing:
npm run check:fix
Environment Variables
Copy .env.example to set up your local environment:
.env.local — used by npm run dev (Vite dev server). Vite loads these via loadEnv(...), and the values are read only by server-side dev middlewares/proxies..dev.vars — used by wrangler pages dev and Cloudflare Pages Functions/Workers in deployment.
Environment variables are never bundled into client-side code. They are only read in server-side contexts (Vite dev server middleware and Cloudflare Functions) and are not exposed directly to the browser.
| Variable | Purpose | Required |
|---|
AI_PROVIDER | AI provider: openai or anthropic | For AI summaries |
OPENAI_API_KEY | OpenAI API key | If AI_PROVIDER=openai |
ANTHROPIC_API_KEY | Anthropic API key | If AI_PROVIDER=anthropic |
FINNHUB_API_KEY | Stock quotes (Markets widget) | For Markets widget |
RAPIDAPI_KEY | CATS Twitter, CFD Twitter, CMS Twitter | For transit/alerts |
HERE_API_KEY | Real-time traffic flow | For HERE traffic alerts |
GOOGLE_API_KEY | Air quality and pollen data | For Weather widget extras |
DRIVENC_API_KEY | NCDOT traffic incidents (DriveNC) | For NCDOT alerts |
TRANSIT_LAND_API_KEY | CATS Blue/Gold Line vehicle positions | For LYNX transit map |
DUKE_OUTAGE_URL | Duke Energy outage API endpoint | For Duke outage alerts |
DUKE_OUTAGE_AUTH | Duke Energy auth (Base64-encoded) | For Duke outage alerts |
Where to Get API Keys
Project Structure
charlotte-watch/
├── src/
│ ├── components/
│ │ ├── widgets/ # Dashboard widgets (Weather, Alerts, etc.)
│ │ └── common/ # Reusable UI primitives
│ ├── services/ # API client functions
│ ├── alerts/ # Per-source alert fetchers (NWS, FAA, NCDOT, etc.)
│ ├── hooks/ # Custom React hooks
│ ├── utils/
│ │ └── queryKeys.ts # Centralized TanStack Query keys
│ ├── data/
│ │ └── transitRoutes.ts # Blue/Gold Line geometry and station coordinates
│ ├── types/ # TypeScript type definitions
│ ├── stores/ # Zustand state (layout, theme)
│ ├── prompts/ # AI system prompts (JSON)
│ └── assets/icons/ # Material Design SVG icons
├── functions/ # Cloudflare Pages Functions (serverless API proxies)
│ ├── api/ # API routes (/api/*)
│ └── _lib/ # Shared utilities for functions
├── workers/
│ └── cache-warmer.ts # Cloudflare Worker — pre-warms KV cache for news
├── public/
│ └── _headers # CSP and security headers
└── docs/ # Documentation
├── DEVELOPMENT.md
├── DEPLOYMENT.md
├── CONVENTIONS_*.md
└── GUIDE_*.md
Architecture
Frontend: React 18 + TypeScript, TanStack Query, Styled Components, Radix UI, Vite
Backend: Cloudflare Pages Functions (17 serverless API routes), Cloudflare KV for response caching (30 seconds to 6 hours depending on endpoint)
Cache Warmer: A separate Cloudflare Worker (workers/cache-warmer.ts) pre-fetches and LLM-parses RSS news feeds on a schedule, writing results to KV so the News widget loads instantly.
Key Patterns:
- Centralized query keys (
src/utils/queryKeys.ts) — never inline query key strings
- All API keys server-side only — never in client code or
.env files loaded by Vite
- CSP enforced via
public/_headers
Contributing
Contributions are welcome. Before you start:
- Read AGENTS.md for coding conventions and critical rules
- Check
docs/ for relevant guides (widgets, API integration, accessibility, etc.)
- Run
npm run check:fix before committing
- Write tests for new features — test failures block CI
For AI coding agents: See AGENTS.md for full instructions including query key conventions, accessibility requirements (WCAG 2.2 AAA), and API patterns.
Deployment
Deploys automatically via GitHub Actions on push to master (production) and on pull requests (preview deployments).
Quick checklist:
- Create a Cloudflare Pages project (Direct Upload method)
- Set GitHub secrets:
CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_PAGES_PROJECT
- Set environment variables in the Cloudflare Pages dashboard (same keys as
.dev.vars)
- Push to
master or open a PR
See docs/DEPLOYMENT.md for full instructions, including the cache warmer worker deployment.
License
MIT
Acknowledgments
Built for the Charlotte community.
