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

Endpoint Organization

The 67 API endpoints are organized into functional domains, totaling 7,824 lines of 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), extracts the user ID, and enforces a single-user allowlist for the initial deployment phase.

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: 49 stickers, 32 achievements, a mayor system, streaks, leaderboards, and post-check-in engagement nudges.

Sticker System

49 custom stickers are organized into five rarity tiers: Common, Uncommon, Rare, Epic, and Legendary. 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.

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

Jobs are scheduled via system cron on the Raspberry Pi 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 Raspberry Pi behind a Cloudflare Tunnel, eliminating the need for port forwarding or a static IP. Apache with MPM event and PHP-FPM (PHP 8.2) handles HTTP requests. OPcache with validate_timestamps=0 ensures bytecode is cached aggressively; PHP-FPM is reloaded after each deployment to pick up changes.

Database Layer

MySQL 9.6 runs in a Docker container on a Synology DS923+ NAS, separating database I/O from application processing. The NAS provides redundant storage with automatic snapshots. Connection pooling and query optimization (indexed JOINs, selective column fetches, pagination limits) keep response times under 200ms for most endpoints despite the modest hardware.

CDN & Caching

Cloudflare handles DNS, SSL termination, DDoS protection, and static asset caching with 1-year Cache-Control headers and ?v=N query string cache-busting. Fastly 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 via mod_deflate.

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 cron job batches.