A GPS-based mobile RPG where real-world quests earn XP, level up your character, and pay out HERO tokens on-chain.
Players create a Cyber-Fantasy character, walk outside, accept GPS-anchored quests (photo, video, text, multi-photo proofs), and get verified by AI + community voting. Completed quests earn XP → levels → HERO tokens. Tokens are real on-chain assets with a 2-phase economy: off-chain ledger first, ERC-20 bridge post-PMF.
PostGIS ST_DWithin query. Quests anchored to real locations within configurable radius.
Gemini 3 Flash with few-shot calibration. Photo/video/text. Per-category weights. Temperature 0.1.
24–72h voting window. Social graph exclusion. Anti-gaming: voter level ≥3, daily XP cap, blind voting.
Off-chain ledger → ERC-20. Earned by quests, spent in token_shop. B2B sponsored quests bypass app store tax.
Cyber-Fantasy "Neon & Mana" universe. Techno-Mag, Chrom-Paladin, Widmo-Biegacz, Bio-Szaman and 4 more.
Season pass (free + 200 HERO paid), weekly challenges, guild weekly objectives. Retention Day 1→60+.
| Module | Detail |
|---|---|
| Firebase Auth | Google + Apple Sign-In |
| AI Onboarding | Aldric, 3–4 turns, class selection |
| GPS Quest Discovery | PostGIS, 30 seeded templates |
| Photo Proof Upload | expo-camera → Cloudflare R2 |
| AI Verification | Gemini 3 Flash, few-shot §35 |
| XP + HERO Award | BullMQ, idempotency_key |
| Push Notifications | Quest result via FCM/APNs |
| Leaderboard | Top 20 weekly by XP |
| Module | Reason |
|---|---|
| Community Voting | AI alone sufficient to validate |
| Guilds / Seasons | Retention — needs user base first |
| IAP / Token Shop | Monetize after PMF |
| Sponsored Quests | Requires B2B sales motion |
| Social (follow/tips) | Needs critical mass |
| UFS Fraud Scoring | Basic rate limit ok for alpha |
| Video proof | Photo first, video sprint 2 |
| AI Quest Generation | Seeded templates on alpha |
| Phase | Scope | Days |
|---|---|---|
| 1 — Setup | Turborepo, Hono skeleton, Drizzle + PostgreSQL/PostGIS, Docker Compose, Zod env config | 1 |
| 2 — Auth + Character | Firebase middleware, auth endpoint, AI onboarding (Aldric), character creation | 2 |
| 3 — Quest System | Migration subset, 30 seeded quest_templates, nearby endpoint (PostGIS), quest accept | 2 |
| 4 — Proof + AI | Presigned URL (R2), proof submit, BullMQ verifyProof worker, Gemini few-shot, XP award (idempotent) | 2 |
| 5 — Push + Leaderboard | FCM push (quest result), weekly leaderboard, character profile endpoint | 1 |
| 6 — Mobile | Expo setup, Auth, Onboarding chat, Map, Quest detail, Camera + upload, Proof status, Profile, Leaderboard | 4 |
| 7 — Deploy + QA | VPS deploy, HTTPS, real device testing (GPS + camera), bugfixes, seed data | 2 |
| Total | ~14 days | |
Backend verifies Firebase Bearer token directly. No refresh token table, no token rotation complexity. Firebase SDK auto-renews client-side.
Both xp_ledger and token_ledger have idempotency_key UNIQUE NOT NULL. BullMQ job retries can never double-award XP or HERO tokens.
Phase 1: PostgreSQL token_ledger. Phase 2: ERC-20 bridge post-PMF. Avoids gas cost UX friction during growth phase.
User Fraud Score 0–100. 11 weighted signals. 5 action tiers: monitoring → review queue → soft limits → shadow_ban → hard ban.
Speed check (impossible travel), accuracy radius validation, temporal liveness challenge. PostGIS for all geo queries.
Few-shot anchor examples per category (photo/text/video). Temperature 0.1. responseMimeType JSON. Per-category confidence weights.
€200–500/quest. Brands pay directly (no app store). Quests marked is_sponsored, separate table. Avoids Apple/Google 30% cut.
Ghost proofs (no voters before deadline) default to rejected. Prevents token farming in low-traffic areas. Configurable per zero_vote_outcome.
10 documents, ~16 000 lines. Click to read full spec.
Full DDL — Migrations 001/002/003. All tables, indexes, enums. Project structure (Turborepo). AI model decision with cost breakdown.
All endpoints with Zod schemas. Auth, onboarding, quests, proofs, voting, social, guilds, seasons, IAP, admin fraud queue, GDPR deletion.
Onboarding AI (Aldric, 2-turn fast-track), quest generation prompts, proof verification policy engine, avatar generation, §35 calibration.
Quest discovery flow, upload URL generation, XP/leveling (idempotent), BullMQ workers, community voting with social graph exclusion, push notifications.
Zod env config, all game_config values, social graph (follow/tips/reactions), guilds §11.6, seasons §11.7, weekly challenges §11.8, retention §11.9, monetization §10.
Error handling (pino), weather service, admin panel, Vitest test suite, full seed data — token_shop catalog, showcase proofs §19.6 for cold start.
drizzle-kit migration files, Docker Compose setup, group quests (post-MVP), Expo mobile architecture §25 — screens, navigation, state, react-native-iap.
Rate limiting, content moderation, GPS anti-spoofing §30, liveness §30.4, safety policy engine §31, UFS fraud scoring §34, GDPR deletion §33, Prometheus metrics §32.
P0–P3 priority backlog — stack issues already resolved, security gaps, remaining idempotency items, GPS spoofing hardening, auth simplification decisions.
What's in / out of MVP. DB subset, 30 seeded quests, 7 mobile screens. Phase-by-phase 14-day schedule. Definition of done checklist.