One-click instant deep-dive location reports powered by OpenAI.
PlacePulse AI turns any place into a structured cultural intelligence dossier. Scan your coordinates or search manually — the Location Intelligence Agent synthesizes history, must-visit spots, local flavors, practical tips, and fun facts into a polished, scrollable report you can save and export as PDF.
Built for the Codex Community Challenge with agentic development patterns (AGENTS.md, SKILLS.md) and meaningful OpenAI platform integration.
- PlacePulse AI
Live Site: https://placepulse-ai.onrender.com
(Note: The demo is hosted on Render's free tier and may take a while to load on the first request due to cold starts.)
https://www.loom.com/share/96c11e96a6184cbf82c1b512bf94eb0e
| Feature | Description |
|---|---|
| Scan Geolocation | Browser GPS → reverse geocode (English, district + country) → instant report |
| Manual search | Enter any city, district, landmark, or region |
| AI location dossier | 8 structured sections: title, subtitle, soul narrative, history, must-visit, local flavors, tips, fun facts |
| Structured JSON outputs | Strict OpenAI json_schema — every field validated before render |
| Report caching | Database-backed cache avoids repeat API calls for the same query |
| Regenerate | Force a fresh AI analysis on demand |
| PDF export | Download a formatted intelligence dossier |
| User accounts | Register/login to persist report history |
| Dark mode | System-aware toggle with local persistence |
| Responsive UI | Tailwind CSS 4, mobile-first layout |
- Backend: Laravel 13, PHP 8.3+
- Frontend: Blade, Tailwind CSS 4, Vite, Inter font
- AI: OpenAI Chat Completions (
gpt-5-mini) viaopenai-php/laravel - Geocoding: OpenStreetMap Nominatim (no API key required)
- Database: SQLite
- Cache: Redis (production via Upstash, database cache in local dev)
- PDF: DomPDF
- PHP 8.3+ locally · 8.4 in Docker (Render)
- PHP extensions (local):
sqlite3,pdo_sqlite,mbstring,openssl,curl - Composer
- Node.js 18+ and npm
- An OpenAI API key
git clone https://github.com/Atia-Farha/PlacePulse-AI.git
cd PlacePulse-AIcomposer setupThis installs PHP dependencies, creates .env, generates an app key, runs migrations, installs npm packages, and builds frontend assets.
Open .env and set your OpenAI credentials:
APP_NAME="PlacePulse AI"
OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL=gpt-5-mini
OPENAI_MAX_COMPLETION_TOKENS=8000
OPENAI_REASONING_EFFORT=lowEnsure SQLite is ready (usually created automatically):
touch database/database.sqlite
php artisan migrateOption A — development (hot reload for CSS/JS):
composer devStarts the Laravel server, Vite, queue worker, and log tail concurrently.
Option B — simple server (after npm run build):
php artisan serveVisit http://127.0.0.1:8000
composer install
cp .env.example .env
php artisan key:generate
touch database/database.sqlite
php artisan migrate
npm install
npm run build
php artisan serve- Click Scan Geolocation (allow location permission), or type a place and submit.
- Wait ~30–60 seconds while the Location Intelligence Agent generates the dossier.
- Click Regenerate to force a fresh AI analysis on demand.
- Click Download PDF to download a formatted intelligence dossier.
- Optionally, register an account to save history.
Travel and local discovery content is scattered, generic, or shallow. Getting a rich, structured picture of a place — its history, culture, food, and practical advice — usually requires hours of research across multiple sources.
- Travelers exploring unfamiliar cities or districts
- Students and Researchers needing quick cultural context
- Remote Workers relocating or visiting new areas
- Local Communities rediscovering their own region through AI-curated narratives
PlacePulse AI democratizes location intelligence: one click or one search produces a magazine-quality dossier that would be impractical to assemble manually. It is especially valuable for lesser-known districts where mainstream travel guides offer little depth.
Category fit: Creative Applications, Education & Learning, Local Problem Solving, AI Agents.
PlacePulse AI uses OpenAI as the core intelligence layer — not as a bolt-on chat widget.
| Setting | Value |
|---|---|
| Model | gpt-5-mini |
| Endpoint | Chat Completions |
| Response format | Strict json_schema (structured outputs) |
| Max completion tokens | 8000 |
| Reasoning effort | low |
| SDK | openai-php/laravel |
Reports must render reliably in Blade templates and PDF exports. A strict JSON schema guarantees every section (title, subtitle, soul, history, must_visit, local_flavors, practical_tips, fun_facts) is present and typed correctly — no fragile markdown parsing.
gpt-5-mini is a reasoning model. Internal reasoning tokens count against the completion budget. With the default 4000-token limit, the model could exhaust its budget on reasoning and return empty content. Setting reasoning_effort=low and max_completion_tokens=8000 ensures the full dossier is generated.
- Input: User provides a location via browser geolocation (reverse-geocoded to English district + country) or manual text search.
- Agent invocation:
OpenAIReportServicesends a system prompt defining the PlacePulse Intelligence Agent persona (travel writer, cultural anthropologist, historian) plus the user's location. - Structured output: OpenAI returns a strict JSON object with eight required sections:
title,subtitle,soul,history,must_visit,local_flavors,practical_tips,fun_facts. - Validation & cache: JSON is parsed and validated; results are stored in SQLite to avoid duplicate API calls.
- Delivery: Laravel renders the dossier in a responsive Blade UI and supports PDF export via DomPDF.
| Artifact | Role |
|---|---|
AGENTS.md |
Documents runtime Location Intelligence Agent architecture, Mermaid workflows, and configuration |
SKILLS.md |
Defines geocoding, structured dossier synthesis, PDF layout, and UI skills |
| Codex agents | Co-engineered the Laravel app using agentic pair programming patterns |
See AGENTS.md for the runtime agent persona, workflow diagrams, and configuration reference. See SKILLS.md for geocoding, schema synthesis, and design-time agent capabilities.
app/
├── Http/Controllers/
│ ├── ReportController.php # Report generation, geocoding, PDF
│ ├── AuthController.php # Login / register
│ └── HistoryController.php # Saved reports
├── Services/
│ └── OpenAIReportService.php # OpenAI agent + JSON schema
resources/
├── js/app.js # Geolocation, report UI, API calls
├── views/ # Blade templates
config/openai.php # Model, tokens, reasoning effort
Dockerfile # Production container (Render)
render.yaml # Render Blueprint (free tier)
docker/render-start.sh # Migrate, cache, serve
AGENTS.md # Agent architecture (Codex challenge)
SKILLS.md # Agent capabilities (Codex challenge)
Developed by Atia Farha (@atia-farha)