Vineward — v1.0.0 (Phase 1: Foundation)

A discipleship & multiplication platform. React Native + Expo + TypeScript + two Supabase projects, offline-first.

Status: Phase 1 (Foundation) is implemented and runnable: navigation, theming, i18n scaffolding, auth screens, local SQLite + sync queue, and both Supabase clients. Tracking, Leadership, Materials, Dashboard, and the network-tree renderer are placeholders — see Roadmap below. Building the entire spec in one pass was explicitly against the build instructions ("do NOT generate the entire app in one uncontrolled pass") — this ships Phase 1 correctly rather than every phase shallowly.

---

0. Before you do anything: rotate your credentials

The uploaded _env.local (from the existing commerce website) contained live secrets in plaintext: a Supabase service_role JWT, an admin password, and two signing secrets. Anyone who has seen that file can fully read/write your commerce database and log into the admin dashboard. Treat all of the following as compromised and rotate them now, independent of anything else in this project:

• Supabase service_role key → Supabase Dashboard → Project Settings → API → regenerate
• ADMIN_PASSWORD → change it, and rotate ADMIN_SESSION_SECRET
• DOWNLOAD_TOKEN_SECRET → regenerate

None of these values were copied into the Vineward project. Only the public GCash display info and product prices were carried forward, per the build spec.

---

1. Prerequisites

• Node.js 20 LTS+
• Java 17 (Android builds)
• Android Studio (Meerkat or newer)
• An Expo account if you plan to use EAS Build
• Two Supabase projects: a new "VINEWARD Core" project, and read-only reference access to the existing commerce project

npm install
npx expo install --fix   # resolves exact versions for your installed Expo SDK
cp .env.local.example .env.local   # fill in real values, see below

2. Environment configuration

Fill in .env.local:

Variable	Where it comes from
EXPO_PUBLIC_VINEWARD_SUPABASE_URL / ..._PUBLISHABLE_KEY	New Core project → Settings → API
EXPO_PUBLIC_COMMERCE_SUPABASE_URL / ..._PUBLISHABLE_KEY	Existing commerce project's public URL/anon key only
EXPO_PUBLIC_GCASH_NUMBER / ..._NAME	Current GCash receiving account
EXPO_PUBLIC_PRODUCT_*_PRICE	Current PHP prices
VINEWARD_SUPABASE_SECRET_KEY / COMMERCE_SUPABASE_SECRET_KEY	Never put these in .env.local for the mobile app. Set them only as Edge Function secrets: supabase secrets set NAME=value

Apply the database schema to the new Core project only:

supabase link --project-ref <core-project-ref>
supabase db push   # applies supabase/migrations/0001_init_core.sql
supabase functions deploy commerce-bridge

3. Choosing and setting up an Android emulator

1. Open Android Studio → More Actions → Virtual Device Manager (or the device icon in the toolbar).
2. Click Create device.
3. Which hardware profile: pick a Pixel 8 or Pixel 7 — mid-spec, well-supported, matches what most real users have. Avoid tablet profiles unless you're specifically testing tablet layout.
4. Which system image: pick the highest numbered API level marked "Recommended" with a Google Play target (not "Google APIs" only) — this matters later if you test Play Billing or Play services. Use an x86_64 or arm64-v8a image matching your host CPU for best emulator speed.
5. Under Show Advanced Settings, give it at least 4 GB RAM and enable Hardware — GLES 2.0 graphics acceleration.
6. Finish, then press ▶ to boot it once from Device Manager before running the app, so the first boot's slower initialization doesn't happen mid-build.

If your machine is low-spec or you'd rather skip the emulator entirely, install the Expo Go app on a physical Android phone and scan the QR code from npx expo start instead — faster iteration, no emulator overhead, but note Expo Go only supports the current Expo SDK and can't test custom native modules (e.g. Skia-based tree rendering in later phases requires a development build either way).

4. Running the app

npx expo start

• Press a to launch on the running Android emulator, or scan the QR code with Expo Go on a device.
• For native modules not supported in Expo Go (this project will need one once Skia lands in Phase 4), build a development client instead:

npx expo run:android

This compiles a real Android app via Gradle and installs it on the emulator/device — required once you add @shopify/react-native-skia, expo-sqlite, or any other native module Expo Go doesn't ship with.

5. Building for release / updating

Development builds (day-to-day):

npx expo run:android          # local debug build via Gradle

Production builds (via EAS, no local Android SDK setup needed):

npm install -g eas-cli
eas login
eas build:configure
eas build --platform android --profile production

Shipping JS-only updates without a new store release (once expo-updates is added):

eas update --branch production --message "Fix tracking sync bug"

Native changes (new native modules, permission changes, app.json native config) always require a new eas build, not just eas update.

Versioning: bump version in app.json for store releases; eas build handles versionCode auto-increment if configured in eas.json.

6. Project structure

src/
  app/            expo-router routes: (auth) stack, (tabs) tabs, root gate
  providers/      AppProviders — theme/i18n/db/auth bootstrap
  features/       screen logic per domain (home, settings, ... more per phase)
  lib/
    supabase/     supabaseCore + supabaseCommerce clients (strict boundary)
    database/     local SQLite cache + sync queue schema
    sync/         idempotent push-to-Core sync engine
    theme/        tokens + ThemeProvider
    i18n/         i18next bootstrap, 7 languages wired (see below)
  stores/         zustand stores (auth)
  types/          hand-authored Core DB types (replace with generated types)
  locales/        en fully translated; fil/ru/pl/ja/hi/de wired but placeholder text
supabase/
  migrations/     0001_init_core.sql — full Core schema + RLS
  functions/
    commerce-bridge/  the only code path allowed to hold both service keys

7. i18n status

en is fully authored. The other six languages (fil, ru, pl, ja, hi, de) are wired end-to-end — namespaces, language switcher in Settings, fallback logic — but currently contain English placeholder text (see each src/locales/<lang>/README.txt). Real ministry terminology needs a human translator; shipping fabricated translations in a discipleship app was judged worse than an honest English fallback.

8. Roadmap (per the build spec's phased plan)

• Phase 1 — Foundation: Expo/TS project, navigation, theme, i18n, both Supabase clients, local DB, secure bridge skeleton
• Phase 2 — Auth + Identity: Google OAuth completion, progressive profiling (7 steps), leader/org/network assignment
• Phase 3 — Tracking Core: Win/Consolidate/Disciple/Send screens wired to live data, Ministry Pulse
• Phase 4 — Leadership: My Journey, My 12 grid, 144/1728 lazy views, Skia network tree
• Phase 5 — Intelligence: Action Center logic, dashboard/ranking, badges
• Phase 6 — Materials: purchase flow UI, receipt upload, commerce-bridge review pipeline, Google Drive delivery
• Phase 7 — Polish: accessibility pass, performance profiling on low-end Android, full offline conflict testing, security review

Each phase should land as its own focused pass rather than all at once, consistent with the original build instructions.