Listy Gifty Monorepo

Listy Gifty is a monorepo with:

• apps/api: Rails API
• apps/web: Next.js web app
• apps/mobile: Expo/React Native mobile app
• packages/types: shared TypeScript types
• packages/api-client: shared API client
• packages/services: shared service layer

1) Prerequisites

• Node.js 22.x and npm 10.x
• Ruby 3.4.x and Bundler
• Docker with Compose for the local preview stack
• Pulumi CLI for infrastructure previews and deployments
• gcloud CLI
• For mobile: run dependency install inside apps/mobile (it is intentionally decoupled from root workspaces)

2) Monorepo setup

From repository root:

npm install
npm run build

For API:

cd apps/api
bundle install
bin/rails db:prepare

For mobile (separate dependency tree):

cd apps/mobile
npm install --legacy-peer-deps

For TestFlight, merge a reviewed pull request, wait for the production Deploy run for that exact merge commit, then comment /testflight on the merged PR. The production profile targets Internal Testers for [email protected]. App Store review is a separate Mobile Release dispatch after validation. See the mobile release runbook.

3) Local development

Boot an isolated PostgreSQL container plus the Rails and Next.js development servers:

bin/local-preview up

The web app runs at http://localhost:3000 and the API at http://localhost:3001. Use bin/local-preview status, test, e2e, logs, restart, down, or reset to manage the stack. The e2e command uses five dedicated users in the Clerk development instance to exercise a complete gift-exchange invitation and joining flow.

After a successful E2E run, open the resulting exchange as any test user:

bin/local-preview e2e-open owner
bin/local-preview e2e-open participant-1

Run API:

cd apps/api
bin/rails server -p 3001

Run web:

cd apps/web
npm run dev

Run mobile:

cd apps/mobile
npx expo start

4) Environment variables

Web (apps/web/.env.local):

NEXT_PUBLIC_API_URL=http://localhost:3001
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
ANDROID_APP_LINK_SHA256_CERT_FINGERPRINTS=AA:BB:... # optional, comma/newline separated

Mobile (apps/mobile/.env):

EXPO_PUBLIC_API_URL=http://localhost:3001
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...

API:

• use Rails credentials and/or runtime environment variables

5) Testing guide

Root workspace checks:

npm run build
npm run test
./bin/lint

API checks:

cd apps/api
bin/rails test

Web checks:

cd apps/web
npm run build

Mobile checks:

cd apps/mobile
npm test -- --runInBand
npx tsc --noEmit

6) Feature development workflow

Use this sequence to add features cleanly across the monorepo:

1. Add or update shared types in packages/types/src/index.ts.
2. Add or update API contracts in Rails (routes/controllers/blueprints).
3. Add or update shared services in packages/services.
4. Rebuild packages from root: npm run build.
5. Implement UI in web and/or mobile using shared types/services.
6. Add or update tests in affected apps.
7. Run app-level checks and local browser flows, then use the reviewed pull request flow. Production deploys automatically after merge; staging is disabled.

Guidelines:

• Prefer shared types/services over duplicating request logic in UI layers.
• Keep UI code focused on presentation/state orchestration, not low-level HTTP.
• Extract repeated formatting/UI patterns into shared modules (apps/mobile/lib/*, reusable components, etc.).

7) Deployment

Deployments are split by shipped surface. Use Pulumi for the Cloud Run API/web stack, and use the Mobile Release workflow for TestFlight and App Store control.

Deployable Surfaces

Surface	What Ships	Owner	Primary Release Path
API	Rails API, migrations, runtime secrets, Cloud SQL connection	Pulumi + Cloud Run	npm run deploy
Web	Next.js app, public web env, app-link metadata	Pulumi + Cloud Run	npm run deploy
Mobile TestFlight	Expo iOS store build, production API/web URLs, app assets from apps/mobile/app.json	GitHub Actions + EAS	/testflight on a merged PR or a main dispatch of Mobile Release
App Store Production	Promotion of a validated TestFlight build to App Review	GitHub Actions + App Store Connect	Mobile Release workflow with app_store_review

Cloud Run API And Web

Project:

• Project ID: listygifty
• Project number: 906707282968
• Region: us-central1
• Pulumi state: gs://listygifty-pulumi-state

Canonical deploy commands:

gcloud config configurations activate listygifty
source .gcp/listygifty-deploy.env

npm run deploy

Staging is turned off pre-PMF (see infra/pulumi/README.md to re-enable). Pull-request CI runs API, web, shared client/service, MCP and mobile tests, builds, static checks and dependency scans. The Deploy workflow runs on relevant main pushes; it relies on the reviewed merge and branch protection for those checks. The local deploy wrapper itself does not run the test suites.

Each Pulumi deploy:

1. Builds API and web images with Cloud Build.
2. Rolls the web revision and updates the Rails migration job image.
3. Runs migrations before rolling the API revision.
4. Smoke-tests the new API/web revisions.
5. Prints deployed URLs and the source SHA.

Preview the current production stack configuration:

npm run deploy:preview

npm run deploy deploys API/web only. npm run deploy:mobile additionally queues an iOS build after migrations, rollout and smoke checks succeed.

Validate production data after migration-heavy deploys:

source .gcp/listygifty-deploy.env
ENVIRONMENT=production HEROKU_APP=niftygifty-production npm run infra:verify-db

See infra/pulumi/README.md for bootstrap, imports, rollback, and resource ownership.

This is the beginning of the README. Read the rest at the original. Read the full README ↗