Technical details
How Instinct is built.
Next.js, FastAPI, Postgres, and a scraper that runs 4× a day.
← Back to AboutArchitecture
Key facts
Search
Postgres full-text, pg_trgm for typos
Events
OpenAI structured output, LA time
Scraping
4 runs a day, clubs in rotation
Scale
451 clubs indexed
How events get extracted
An LLM reads each caption. Guardrails keep its output consistent and stop quality slipping over time.
Pipelinetools/ai_validation.py
Caption
+ post date, LA time
- { }
Prompt + schema
strict JSON schema
Model
pinned, gpt-6-luna
- { }
Rules + checks
shape check, durations
Postgres
event saved
Guardrails
Schema
Strict JSON schema. Every reply has the same fields and types.
Rules
Start time only: 1 hour. No time: 00:00 + whole days. Applied in code too.
Date context
Post date sent in LA time with its weekday, so “this Friday” resolves the same way.
Validation
Refusals or off-shape replies are errors, not empty results.
No silent drops
Failed parses stay unparsed and retry next run.
Pinned model
gpt-6-luna.
Why the duration rules: 272 of 2,282 events in prod had zero duration (~12%). Repeatability comes from the schema, rules, and evals; no temperature is sent, since gpt-6-luna only accepts the default.
Evaluation
Before changing the model or prompt, run both on the same frozen posts and compare.
Harnessscripts/eval_event_parser.py
Frozen post set
saved once, reused
Side by side
prompts × models
- { }
Metrics + diffs
read-only, never writes
Reported per variant
- zero duration %
- timed zero duration %
- midnight starts %
- all-day whole days %
- bad output
- API errors
- side-by-side diffs
Used to compare gpt-4.1-mini with gpt-6-luna. Run by hand, not in CI; no results are committed. 17 unit tests in tests/test_event_parser.py cover the schema, rules, retries, and an offline dry run of the harness.
Stack
- Next.jsApp Router, PWA
- ReactUI, v19
- Tailwind CSSStyling, v4
- FastAPIREST API
- PythonAPI + scraper
- RedisScrape queue
- SeleniumInstagram scraper
- InstagramSource of posts
- OpenAICaption → events
- SupabasePostgres + auth
- PostgreSQLFTS + pg_trgm
- Google@uci.edu sign-in
- VercelHosts the site
- HerokuHosts the API
- Cloudflare R2Image storage
- DockerAPI + scraper images
- GitHub ActionsCI + API deploy
Next up
- Faster, sturdier scraper
- Better event extraction
- UI polish