Local setup, provider lifecycle, and sandbox payments

Purpose

Local-first setup lets operators and builders validate the marketplace before production provider activation. The repository includes a Laravel API, Next.js web app, Expo mobile app, Docker Compose configuration, seeded demo/fallback content, and provider-safe status surfaces. Documentation must never publish secret values, webhook signing secrets, API keys, private Firebase credentials, storage credentials, or admin passwords.

Local-first startup checklist

1. 1Install dependencies for backend, frontend, and mobile using each package manager described in the repository READMEs.
2. 2Create local environment files from examples or deployment notes. Keep secrets outside Git and avoid pasting credentials into CMS pages or support tickets.
3. 3Start the backend API and confirm /api/v1/health returns the creator-commerce-api status.
4. 4Start the Next.js frontend with NEXT_PUBLIC_API_URL pointing at the local /api/v1 endpoint.
5. 5Run the Expo mobile app against the same API base URL when validating mobile parity.
6. 6Use admin-seeded accounts or local registration to verify buyer, creator, influencer, and admin journeys.

Provider lifecycle states

• ✦ Not configured: the UI may show readiness notices, fallback copy, or demo-safe behavior until provider keys are supplied outside source control.
• ✦ Sandbox: provider endpoints, webhooks, OAuth redirects, push tokens, and checkout sessions are wired to non-production projects for safe testing.
• ✦ Ready for production: public settings show enabled/ready status while secret values stay server-side and hidden from public APIs.
• ✦ Degraded: support/admin should route users to safe fallback instructions when a provider is temporarily unavailable.
• ✦ Disabled: feature flags or admin settings keep unavailable provider features from being advertised as live.

Sandbox payments

Checkout supports provider-backed sessions and local/demo provider flows used in tests. Razorpay, Stripe, and PayPal webhook endpoints exist server-side; production use requires gateway accounts, sandbox keys first, webhook URL registration, webhook signing validation, and test payment reconciliation. Buyer help should describe payment options only as available where provider configuration supports them.

Provider readiness checklist

• ✦ Payments: configure Razorpay, Stripe, or PayPal in sandbox first; validate checkout session creation, webhook idempotency, paid-order status, invoice view, refund request route, and Library downloads.
• ✦ OAuth: Google/GitHub buttons currently display configuration readiness notices until provider credentials and redirect URLs are connected.
• ✦ AI: product description, marketing copy, recommendations, and support drafts use safe fallback behavior when model keys are absent; review all AI output before publication.
• ✦ Notifications: Expo push registration and notification preferences exist; production push requires public-safe mobile configuration and device token registration.
• ✦ Storage/downloads: signed download links depend on file metadata, scan status, entitlement checks, and storage disk configuration.
• ✦ Search/content: marketplace discovery and CMS pages should use public-safe APIs with bounded query parameters and fallback navigation.

Common local setup issues

• ✦ Frontend cannot load content: confirm NEXT_PUBLIC_API_URL points to the backend /api/v1 base URL and the backend server is running.
• ✦ Mobile shows cached or fallback content: refresh public content and confirm the API base URL is reachable from the simulator/device.
• ✦ Checkout stays pending: confirm the sandbox webhook was delivered or use demo/test webhook flows in local validation.
• ✦ OAuth buttons do not sign in: expected until real provider apps, callback URLs, and server-side credentials are configured.
• ✦ Downloads fail after purchase: check order paid status, file scan status, primary file metadata, download limit, and signed URL expiry.