Haunts.io:
Architecture of a Full-Stack Check-In Platform

Endpoint Organization

The 120+ API endpoints are organized into functional domains, totaling roughly 27K lines of endpoint PHP:

Authentication & Security

Every API request requires a valid Firebase ID token in the Authorization: Bearer header. The firebase-auth.php middleware verifies the token using the Firebase Admin PHP SDK (kreait/firebase-php) and extracts the user ID that scopes every query, with visibility rules enforced per check-in, trip, and profile across the full social graph.

The api-security.php layer adds rate limiting (per-endpoint configurable), CORS enforcement with explicit origin whitelisting, content-type validation, and request size limits. All database queries use parameterized statements to prevent SQL injection.

Response Patterns

All endpoints return a consistent JSON envelope: {"success": true, "data": ...} on success, or {"success": false, "error": "message"} on failure with appropriate HTTP status codes. Paginated endpoints include total, page, and limit metadata. The API supports both GET query parameters and POST JSON bodies depending on the operation semantics.

The gamification engine is the heart of the Swarm replacement experience: 54 stickers, 32 achievements, a mayor system, streaks, leaderboards, and post-check-in engagement nudges.

Sticker System

54 custom stickers span four rarity tiers (Common, Rare, Epic, and Legendary), plus dedicated Flight and Road sets. Each sticker has a set of contextual rules that determine when it is awarded. Rules evaluate venue category (coffee shop, bar, airport, gym), time of day (morning, late night), visit frequency (first visit, 10th visit, 50th visit), and special conditions (checked in during rain, visited 5 countries).

The sticker rule engine runs as both a real-time post-check-in evaluation and a batch cron job (jobs/contextual_stickers.php) that retroactively evaluates all historical check-ins against newly added rules. This ensures that importing 6,700+ Swarm check-ins immediately populates the sticker collection without requiring manual check-ins.

Achievement System

32 achievements with XP values track cumulative progress: venue count milestones, city/country exploration targets, streak lengths, photo counts, and category-specific goals (visit 20 coffee shops, check in at 10 airports). The achievement evaluator (jobs/evaluate_achievements.php) runs on a schedule and compares current stats against threshold definitions, awarding new achievements and broadcasting unlock events to the social feed.

Mayor System

The mayor system tracks the user with the most check-ins at each venue. Mayor status is recalculated on each check-in and displayed on venue pages with competitive context ("You need 3 more visits to become mayor"). Mayor crowns appear on profile stats and contribute to the overall gamification score.

Engagement Nudges

After each check-in, the API evaluates near-miss achievements and returns contextual nudges: "You’re 2 check-ins away from Explorer Level 3!" or "First time in this city!" These nudges drive continued engagement without requiring the user to navigate to the achievements page.

30+ PHP cron jobs handle enrichment, evaluation, routing, media, AI, and notification tasks that would be too expensive or slow to run inline with API requests.

Jobs are scheduled via system cron on the web server. Each job is a standalone PHP script that connects to both databases, processes a batch of records, and logs its results. Jobs are designed to be idempotent and resumable: if interrupted, they pick up where they left off on the next run.

Server Architecture

The production stack runs on a dedicated application server behind an edge layer that handles DNS, TLS termination, and DDoS protection. A persistent application server with bytecode caching keeps response times tight, and the cache is reloaded after each deployment so new code takes effect immediately.

Database Layer

The database runs on a dedicated host, separating storage I/O from application processing. Redundant storage with automatic snapshots protects against data loss. Connection pooling and query optimization (indexed JOINs, selective column fetches, pagination limits) keep response times under 200ms for most endpoints.

CDN & Caching

The edge layer handles DNS, TLS termination, DDoS protection, and static asset caching with 1-year Cache-Control headers and a ?v=N query string for cache-busting. A separate image CDN serves user-uploaded photos with on-the-fly resizing (original, cap300, cap600, 500x500 variants). Static web assets (JS, CSS, fonts) are served with gzip compression.

Performance Optimization

A dedicated performance pass on Day 3 addressed 21 identified bottlenecks: batched database queries replacing N+1 patterns, React.memo and useMemo for expensive component renders, lazy loading for below-the-fold images, query result memoization in the API layer, and connection reuse across background job batches.

The sprint left a working platform. The weeks after built the systems underneath it. Each one below was added and hardened after launch, alongside the Pulse social feed and a public profile atlas that mirrors the web client on mobile.

Road Trips

A road trip is declared like a live trip, then classified by kind. Endpoints store the route geometry, snap it to real roads through a directions provider, and compute distance and the states or provinces crossed from ISO 3166-2 codes. Shared road trips union every member’s route into one canonical record, draw a colored line per driver, and rank everyone on a road-distance leaderboard.

Photo & Video Albums

Trip albums accept photos and videos. Small videos upload directly. Large ones use a resumable session protocol that splits the file into chunks, hashes each chunk, and finalizes server-side. A transcode worker flips uploads from pending to ready, and a retention worker prunes the originals on a schedule. Album media hydrates onto the public trip share page once it is ready.

Live Swarm Sync

Beyond the one-time import, an ongoing connection keeps pulling new Swarm check-ins on a rate-capped schedule. A worker processes due connections under a global ceiling, dedupes against existing rows, soft-deletes superseded records on match, and surfaces a reconnect action when a connection stalls.

AI Layer

Claude Sonnet writes the trip recaps. Claude Haiku handles the lighter, higher-volume work of trip titles, year-in-review blurbs, and venue review summaries. Generation runs in background workers with usage logging, so the write-ups are prebuilt and cached rather than generated on the request path.

Trash & Soft Delete

Trips, check-ins, album media, comments, and flights all soft-delete with a deleted_at timestamp and a 30-day recovery window. A purge worker hard-deletes past the window. Soft-deleted rows are excluded from every read path, background detector, and aggregate, so a deleted record never resurfaces in a feed or a count.

Venue Data & Discovery

Nearby discovery serves known venues straight from the Haunts database when enough are in range, falling back to external providers otherwise, with provider attributions stacked per venue. A nightly mirror enriches under-served regions from an alternate places dataset, and member-editable coordinates carry an audit trail under an own-data-first precedence rule.