React Native Game App Development & Optimization
Budget: €1,500 – €3,000 EUR
Finish & Ship a Gyroscope‑Driven Marble Reading App (React Native + Backend)
1) What this app does (high level)
An interactive, physics‑based “marble board” experience:
The user types a question.
On a circular board with nine positions, the user places nine colored marbles—either by tilting the phone (gyroscope) or via manual drag.
Once all marbles are placed, the app generates a personalized reading. The reading is composed from (a) deterministic rules already in code and (b) an AI service that turns those results into a polished narrative.
(You will not author the interpretive content; your job is to pipe data to/from the AI safely and reliably.)
Your goal: turn the working prototype into a secure, performant, store‑ready mobile app with accounts, subscriptions, redemption codes, analytics, and an admin backoffice.
2) What’s already built (and where)
Working canvas prototype (web) with the full board game loop: intro - question - board (tilt/manual) - reading screen - share/copy/download - local history. The game physics, collisions, placement, rotation control, mode switching, and reading UI are all implemented in index.html.
Notes: Gyroscope support is present; manual drag mode is smooth; board state is encoded and triggers reading generation when all marbles lock into a position.
Rule engine & mapping data: a JS data module maps each marble/position combination to deterministic snippets used in the reading (already loaded locally in the client).
AI call (prototype): the client currently calls an AI provider directly to turn the rule‑based output into a nicely written result (includes an exposed API key—this must be moved server‑side).
High‑level architecture guidance: a 3‑tier design (Mobile App - API - DB/Caching) plus auth, rate‑limits, payments, and observability; recommended mobile stack is React Native. The architecture diagram on page 1 shows the front‑end, backend API, and infra layers; the doc also outlines phased delivery and quality gates we’ll adopt in a trimmed form.
Roadmap draft (Greek): details practical next steps you’ll implement: move AI to server, add auth (Firebase/Auth0), set up DB with entitlements/usage, anti‑abuse (rate limits/queues/CAPTCHA), payments (RevenueCat/Stripe), redemption codes, tests/CI, admin dashboard, app‑store compliance, and roll‑out.
I also have a separate gyroscope/tilt implementation; you’ll integrate/polish that during the React Native port.
3) What you will build (deliverables & acceptance criteria)
A. Production Backend (API + Infra)
Goal: move all sensitive logic off the client and provide a stable surface for the mobile app.
Secure AI endpoint (server‑side)
Receive: {question, boardState}; Return: structured reading text (plus any meta)
Remove client key exposure, rotate existing key, and keep all secrets in env/Key Vault.
Add request validation, timeouts, retry with jitter, idempotency keys; log cost per call and outcome.
Acceptance: AI key never ships in the app; endpoint survives transient provider failures; structured JSON contract defined and documented.
Auth & accounts
Implement Email/Password + Google + Sign in with Apple (required on iOS when social login exists).
Token‑based sessions; refresh flow; basic roles.
Acceptance: new users can register/login; tokens refresh; protected endpoints require auth.
Database & entitlements
Model users, readings, plans/subscriptions, usage/credits, redemption codes, benefit packs.
Atomic consumption of a credit/usage with transactions; automated backups.
Acceptance: server enforces daily limits/credits; usage ledger is consistent; audits possible.
Anti‑abuse & performance
Rate limiting (IP + user/device), CAPTCHA/Turnstile step‑up on suspicious patterns, request queue (e.g., Redis/BullMQ) to smooth spikes.
Response caching where safe.
Acceptance: limits enforced; no key leakage; queue keeps P95 latency stable under load.
Infra & observability
Staging + Production environments; structured logging; metrics for DAU/MAU, error rates, AI spend/token usage.
Acceptance: dashboards exist; on‑call can identify errors/spend quickly.
Tech options (flexible):
Backend: Node.js (Express/Nest) + Prisma + PostgreSQL + Redis or ASP.NET Core + EF Core + Azure SQL + Redis. Choose your strength; both are acceptable given the architecture guidance.
Hosting: Azure, AWS, or Render/Fly.io with managed Postgres.
B. Mobile App (React Native, Expo)
Goal: port the working game to mobile, wire it to the new API, and finish the product surface.
RN project setup + navigation
Expo (TS), app navigation (Auth flow + main), secure token storage, config per env, crash reporting (Sentry) & analytics.
Acceptance: builds run on iOS/Android; crashes reported; events tracked (question asked, board completed, reading received).
Port the game to RN + polish
Re‑implement the board, physics, collisions, locking, manual drag, and gyroscope mode using RN libraries (e.g., expo-sensors, react-native-gesture-handler, react-native-reanimated, optionally react-native-skia for rendering).
Integrate your existing tilt code; calibration UI; maintain 60fps; identical behavior to the web prototype.
Acceptance: both modes work; all 9 marbles lock predictably; board rotation control; complete placement triggers reading. (The engine is already working in the prototype—this step is “port + polish”, not a ground‑up rewrite.)
API integration & local UX
Replace client‑side AI call with server API; implement resilient request layer; loading/empty/error states; offline safeguards for history.
Persist reading history (server‑side), and keep a recent cache on device; implement share/copy/download parity with the prototype.
Acceptance: a reading is generated via the backend API; history syncs to server; user can copy/share; errors recover gracefully.
Out of scope for you: altering the interpretive dataset or prompt content. The app already has a deterministic mapping and a prompt; you will only pipe board state to the API and render the result.
C. Monetization, Codes, and Operations
Subscriptions & purchases
RevenueCat for iOS/Android in‑app subscriptions; Stripe for web payments (if a simple web flow is desired).
Implement real‑time webhooks/RTDN to sync entitlement state (renewals, cancellations, refunds).
Acceptance: buy/restore works on both platforms; entitlements update server‑side automatically.
Redemption codes (physical products)
Server stores only hashed codes; one‑time redeem to user account; adds credits/benefit pack.
Deep links: app://redeem?code=… to drive in‑app flow.
Acceptance: secure code generation/validation; clear user feedback; audit trail.
Admin dashboard & metrics
Lightweight backoffice (Retool or small internal app) for KPIs (MRR, DAU/MAU, conversion, AI spend), user support, and code management.
Acceptance: ops can search users, adjust entitlements, inspect logs/metrics.
QA, CI/CD, and compliance
Unit tests for the server formatter/validators and usage logic; basic E2E for the happy path (Detox/Playwright).
CI/CD: GitHub Actions + EAS Build/Submit (mobile), auto‑deploy API to staging/prod.
App Store/Play compliance (Privacy/Data Safety forms, “for entertainment purposes only” disclaimer), beta via TestFlight/Internal testing, staged rollout.
Acceptance: green CI, test coverage on critical flows, builds submitted, store metadata/assets complete.
4) Known issues / immediate fixes (from the prototype)
Security: AI provider key embedded in client script—must be removed and rotated; all AI calls must be server‑side.
Persistence: readings are only in localStorage; migrate to server history with device cache.
Gyroscope permissions (iOS): current code tries to initialize without a user gesture; add permission prompt & calibration flow in RN.
Resilience: add request timeouts/retries/fallback messaging around AI calls (prototype has a basic timeout; productionize).
State management & navigation: port the existing multi‑screen flow (intro - question - game - reading) to RN stacks/tabs; standardize resets when switching modes.
5) Tech stack & tools (suggested, not mandatory)
Mobile: React Native (Expo, TypeScript), expo-sensors, react-native-reanimated, react-native-gesture-handler, optional react-native-skia.
Backend: Node.js (Nest/Express) + Prisma + PostgreSQL + Redis or ASP.NET Core + EF Core + Azure SQL + Redis (aligns with the architecture guide).
Auth: Firebase Auth or Auth0.
Payments: RevenueCat (iOS/Android), Stripe (web).
Ops: Sentry, GitHub Actions, EAS Build/Submit, Retool (admin), Application Insights or OpenTelemetry.
6) What I will provide
The working web prototype and existing tilt/gyro code.
The deterministic mapping rules (already in code). (Not asking you to change the logic/content.)
The narrative prompt/content used by the AI. (Out of scope to edit—only plumb it through the backend.)
7) Ideal freelancer
Strong React Native (Expo) + sensors/animations experience; comfortable achieving 60fps with gestures and tilt.
Practical backend engineering (Node or .NET), auth, payments, rate‑limiting, and cloud deployments.
Product‑minded: can close the gap from prototype - shippable with clean UX, error handling, and store compliance.
1) What this app does (high level)
An interactive, physics‑based “marble board” experience:
The user types a question.
On a circular board with nine positions, the user places nine colored marbles—either by tilting the phone (gyroscope) or via manual drag.
Once all marbles are placed, the app generates a personalized reading. The reading is composed from (a) deterministic rules already in code and (b) an AI service that turns those results into a polished narrative.
(You will not author the interpretive content; your job is to pipe data to/from the AI safely and reliably.)
Your goal: turn the working prototype into a secure, performant, store‑ready mobile app with accounts, subscriptions, redemption codes, analytics, and an admin backoffice.
2) What’s already built (and where)
Working canvas prototype (web) with the full board game loop: intro - question - board (tilt/manual) - reading screen - share/copy/download - local history. The game physics, collisions, placement, rotation control, mode switching, and reading UI are all implemented in index.html.
Notes: Gyroscope support is present; manual drag mode is smooth; board state is encoded and triggers reading generation when all marbles lock into a position.
Rule engine & mapping data: a JS data module maps each marble/position combination to deterministic snippets used in the reading (already loaded locally in the client).
AI call (prototype): the client currently calls an AI provider directly to turn the rule‑based output into a nicely written result (includes an exposed API key—this must be moved server‑side).
High‑level architecture guidance: a 3‑tier design (Mobile App - API - DB/Caching) plus auth, rate‑limits, payments, and observability; recommended mobile stack is React Native. The architecture diagram on page 1 shows the front‑end, backend API, and infra layers; the doc also outlines phased delivery and quality gates we’ll adopt in a trimmed form.
Roadmap draft (Greek): details practical next steps you’ll implement: move AI to server, add auth (Firebase/Auth0), set up DB with entitlements/usage, anti‑abuse (rate limits/queues/CAPTCHA), payments (RevenueCat/Stripe), redemption codes, tests/CI, admin dashboard, app‑store compliance, and roll‑out.
I also have a separate gyroscope/tilt implementation; you’ll integrate/polish that during the React Native port.
3) What you will build (deliverables & acceptance criteria)
A. Production Backend (API + Infra)
Goal: move all sensitive logic off the client and provide a stable surface for the mobile app.
Secure AI endpoint (server‑side)
Receive: {question, boardState}; Return: structured reading text (plus any meta)
Remove client key exposure, rotate existing key, and keep all secrets in env/Key Vault.
Add request validation, timeouts, retry with jitter, idempotency keys; log cost per call and outcome.
Acceptance: AI key never ships in the app; endpoint survives transient provider failures; structured JSON contract defined and documented.
Auth & accounts
Implement Email/Password + Google + Sign in with Apple (required on iOS when social login exists).
Token‑based sessions; refresh flow; basic roles.
Acceptance: new users can register/login; tokens refresh; protected endpoints require auth.
Database & entitlements
Model users, readings, plans/subscriptions, usage/credits, redemption codes, benefit packs.
Atomic consumption of a credit/usage with transactions; automated backups.
Acceptance: server enforces daily limits/credits; usage ledger is consistent; audits possible.
Anti‑abuse & performance
Rate limiting (IP + user/device), CAPTCHA/Turnstile step‑up on suspicious patterns, request queue (e.g., Redis/BullMQ) to smooth spikes.
Response caching where safe.
Acceptance: limits enforced; no key leakage; queue keeps P95 latency stable under load.
Infra & observability
Staging + Production environments; structured logging; metrics for DAU/MAU, error rates, AI spend/token usage.
Acceptance: dashboards exist; on‑call can identify errors/spend quickly.
Tech options (flexible):
Backend: Node.js (Express/Nest) + Prisma + PostgreSQL + Redis or ASP.NET Core + EF Core + Azure SQL + Redis. Choose your strength; both are acceptable given the architecture guidance.
Hosting: Azure, AWS, or Render/Fly.io with managed Postgres.
B. Mobile App (React Native, Expo)
Goal: port the working game to mobile, wire it to the new API, and finish the product surface.
RN project setup + navigation
Expo (TS), app navigation (Auth flow + main), secure token storage, config per env, crash reporting (Sentry) & analytics.
Acceptance: builds run on iOS/Android; crashes reported; events tracked (question asked, board completed, reading received).
Port the game to RN + polish
Re‑implement the board, physics, collisions, locking, manual drag, and gyroscope mode using RN libraries (e.g., expo-sensors, react-native-gesture-handler, react-native-reanimated, optionally react-native-skia for rendering).
Integrate your existing tilt code; calibration UI; maintain 60fps; identical behavior to the web prototype.
Acceptance: both modes work; all 9 marbles lock predictably; board rotation control; complete placement triggers reading. (The engine is already working in the prototype—this step is “port + polish”, not a ground‑up rewrite.)
API integration & local UX
Replace client‑side AI call with server API; implement resilient request layer; loading/empty/error states; offline safeguards for history.
Persist reading history (server‑side), and keep a recent cache on device; implement share/copy/download parity with the prototype.
Acceptance: a reading is generated via the backend API; history syncs to server; user can copy/share; errors recover gracefully.
Out of scope for you: altering the interpretive dataset or prompt content. The app already has a deterministic mapping and a prompt; you will only pipe board state to the API and render the result.
C. Monetization, Codes, and Operations
Subscriptions & purchases
RevenueCat for iOS/Android in‑app subscriptions; Stripe for web payments (if a simple web flow is desired).
Implement real‑time webhooks/RTDN to sync entitlement state (renewals, cancellations, refunds).
Acceptance: buy/restore works on both platforms; entitlements update server‑side automatically.
Redemption codes (physical products)
Server stores only hashed codes; one‑time redeem to user account; adds credits/benefit pack.
Deep links: app://redeem?code=… to drive in‑app flow.
Acceptance: secure code generation/validation; clear user feedback; audit trail.
Admin dashboard & metrics
Lightweight backoffice (Retool or small internal app) for KPIs (MRR, DAU/MAU, conversion, AI spend), user support, and code management.
Acceptance: ops can search users, adjust entitlements, inspect logs/metrics.
QA, CI/CD, and compliance
Unit tests for the server formatter/validators and usage logic; basic E2E for the happy path (Detox/Playwright).
CI/CD: GitHub Actions + EAS Build/Submit (mobile), auto‑deploy API to staging/prod.
App Store/Play compliance (Privacy/Data Safety forms, “for entertainment purposes only” disclaimer), beta via TestFlight/Internal testing, staged rollout.
Acceptance: green CI, test coverage on critical flows, builds submitted, store metadata/assets complete.
4) Known issues / immediate fixes (from the prototype)
Security: AI provider key embedded in client script—must be removed and rotated; all AI calls must be server‑side.
Persistence: readings are only in localStorage; migrate to server history with device cache.
Gyroscope permissions (iOS): current code tries to initialize without a user gesture; add permission prompt & calibration flow in RN.
Resilience: add request timeouts/retries/fallback messaging around AI calls (prototype has a basic timeout; productionize).
State management & navigation: port the existing multi‑screen flow (intro - question - game - reading) to RN stacks/tabs; standardize resets when switching modes.
5) Tech stack & tools (suggested, not mandatory)
Mobile: React Native (Expo, TypeScript), expo-sensors, react-native-reanimated, react-native-gesture-handler, optional react-native-skia.
Backend: Node.js (Nest/Express) + Prisma + PostgreSQL + Redis or ASP.NET Core + EF Core + Azure SQL + Redis (aligns with the architecture guide).
Auth: Firebase Auth or Auth0.
Payments: RevenueCat (iOS/Android), Stripe (web).
Ops: Sentry, GitHub Actions, EAS Build/Submit, Retool (admin), Application Insights or OpenTelemetry.
6) What I will provide
The working web prototype and existing tilt/gyro code.
The deterministic mapping rules (already in code). (Not asking you to change the logic/content.)
The narrative prompt/content used by the AI. (Out of scope to edit—only plumb it through the backend.)
7) Ideal freelancer
Strong React Native (Expo) + sensors/animations experience; comfortable achieving 60fps with gestures and tilt.
Practical backend engineering (Node or .NET), auth, payments, rate‑limiting, and cloud deployments.
Product‑minded: can close the gap from prototype - shippable with clean UX, error handling, and store compliance.