Cryptid Tracker KY

Real-time Kentucky cryptid sighting tracker — built for the Aiven Free Tier Competition.

Applying enterprise streaming architecture to Kentucky's most pressing geospatial problem.

What Is This?

A web application that tracks cryptid sightings across Kentucky. Users submit sightings on an interactive map; sightings stream through Apache Kafka, are validated and stored in PostGIS, cached in Valkey, and rendered on a MapLibre GL frontend showing sighting clusters and county-level "threat levels."

Real historical data from the BFRO (Bigfoot sightings) and NUFORC (UFO reports) seed the map alongside synthetic sightings for Kentucky's documented cryptid menagerie: the Pope Lick Monster, Beast Between the Lakes, Herrington Lake Monster, Bearilla, and more.

Architecture

User → FastAPI → Kafka (sighting-raw) → Consumer → PostgreSQL+PostGIS + Valkey
                                                  → Kafka (sighting-validated)

Frontend (MapLibre GL) ← FastAPI ← PostgreSQL (spatial) + Valkey (cache)

Community features (comments, votes) → MySQL

Four Aiven free tier services, each with a genuine role:

• PostgreSQL + PostGIS — Spatial data store. Sighting geometry, county boundaries, cryptid references. Spatial indexes, ST_Contains for county joins, ST_ClusterDBSCAN for hotspot detection.
• Apache Kafka — Event streaming. Decouples sighting submission from processing. Enables the validation consumer pipeline and real-time generator demo.
• Valkey — Computed cache layer. County threat levels, live stats, recent sightings feed, reporter leaderboard. Eliminates repeated expensive spatial queries.
• MySQL — Community features. User accounts, comments on sightings, credibility votes.

Kentucky Cryptids

Creature	Danger Rating	Known Habitat
Bigfoot	★★★☆☆	Forests statewide
Pope Lick Monster	★★★★★	Pope Lick trestle, Louisville
Beast Between the Lakes	★★★★★	Land Between the Lakes NRA
Mothman	★★★★☆	Bridges, urban areas
Herrington Lake Monster	★★★☆☆	Herrington Lake
Bearilla	★★★☆☆	Nicholas County forests
Hillbilly Beast	★★★★☆	Eastern Kentucky mountains
Sturgis Vampire	★★★★☆	Union County
Spottsville Monster	★★☆☆☆	Henderson County
Giraffe-Possum	★☆☆☆☆	Clark County (rural)
Boonesborough Octopus	★★★☆☆	Kentucky River
UFO / UAP	★★☆☆☆	Statewide

Quick Start

# 1. Clone and install
git clone https://github.com/chrislyonsKY/cryptid-tracker-ky.git
cd cryptid-tracker-ky
pip install -r requirements.txt

# 2. Configure Aiven connections
cp .env.example .env
# Edit .env with your Aiven service URIs

# 3. Set up databases
python -m scripts.setup_db

# 4. Seed data
python -m scripts.seed_bfro
python -m scripts.seed_nuforc

# 5. Start the consumer
python -m src.consumer.main &

# 6. Start the API
uvicorn src.api.main:app --reload

# 7. Open the map
# http://localhost:8000

# 8. (Optional) Stream synthetic sightings
python -m src.generator.main --mode stream

Data Sources

• BFRO Bigfoot Sightings — data.world / GitHub
• NUFORC UFO Reports — GitHub / Kaggle
• KY County Boundaries — US Census TIGER/Line
• Kentucky Cryptid Folklore — Various published sources; see ai-dev/decisions/DL-002-real-data-plus-synthetic.md

Built With

Python (FastAPI) · PostgreSQL + PostGIS · Apache Kafka · Valkey · MySQL · MapLibre GL JS

All managed services on Aiven Free Tier.

---

#AivenFreeTier