Contact person: React Native Game App Development & Optimization

Phone:Show

Email:Show

Location: Nottingham, Greece

Budget: Recommended by industry experts

Time to start: As soon as possible

Project description:
"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/[login to view URL] 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." (client-provided description)