B

Build Pro HQ Roadmap

v1 launch preparation

0 / 0
Overview

From Round-2 complete to App Store launch

Round 2 is shipped — eight clean commits in v5. Next: build the multi-tenant foundation, harden for production, and prepare both stores. No deadline, no shortcuts — every step taken now saves a multiple of itself later.

⏱
Currently waiting on

Pty Ltd registration → Apple Developer Program enrolment ($A150/year). Apple's review of new dev accounts is currently 2–6 weeks. Use that time productively (Phases 1–4 below).

Recommended sequencing

  1. Multi-tenant refactor

    Restructure Firestore so each construction company is a top-level Organisation. Projects and action items become subcollections. Per-org roles, per-org membership. Done before real customer data exists — migrating later is dramatically more work.

  2. Production hardening

    Sentry error monitoring. Account deletion flow (Apple requirement). Tightened Firestore security rules. Photo upload retry/resume for site network conditions. Network resilience audit.

  3. Assets & polish

    Final logo (pending colour decision). Icon generation at every required size. Splash screens. App Store and Play Store screenshots designed in Figma. Listing copy written.

  4. Automated testing

    Jest unit tests on critical utilities (item status, date logic, role checks). Detox E2E smoke test on the core happy path. CI on every PR. Minimum coverage on the parts that break silently.

  5. TestFlight rollout

    After Apple Dev account lands. Build via EAS, upload to App Store Connect, internal testing track, invite friends across the device matrix. Iterate on real-device feedback.

  6. App Store + Play Store submission

    Submit to both stores in parallel. App Privacy questionnaire, Data Safety form, content ratings, screenshots, listing metadata. Respond to first-pass rejections.

  7. Billing & subscriptions

    Stripe per-seat subscription model. Each company pays per active user (1 manager + N foremen). Trial period. Webhook handling for lifecycle events. Receipt validation.

Tenant model — the architecture

Build Pro HQ sells to construction companies. Each company is an Organisation with one manager (admin) and N foremen (regular users). The manager creates projects, assigns foremen to projects at their discretion, and manages the seat count via the Build Pro HQ subscription.

Build Pro HQ itself manages many Organisations. v1 must comfortably handle at least 5 Organisations with multiple users each.

// Firestore data model organizations/{orgId} name: string // e.g. "Acme Construction Pty Ltd" ownerUid: string // the Manager / billing contact memberUids: string[] // for security rule lookups createdAt: Timestamp // Billing fields — only Cloud Functions write these (rules block client writes) stripeCustomerId: string // cus_XXXX stripeSubscriptionId: string // sub_XXXX subscriptionStatus: 'trialing' | 'active' | 'past_due' | 'canceled' | 'unpaid' seatLimit: number // mirrors Stripe subscription.quantity trialEndsAt: Timestamp | null currentPeriodEndsAt: Timestamp billingInterval: 'month' | 'year' members/{uid} role: 'manager' | 'user' // per-org, not global addedAt: Timestamp projects/{projectId} name: string levels: string[] // ordered (drag-to-reorder shipped in v5) trades: string[] memberUids: string[] // subset of org members createdAt: Timestamp actionItems/{itemId} title, trade, level, assignedTo, ... // existing fields // orgId/projectId no longer needed as document fields — implied by path users/{uid} displayName, initials, email organizationIds: string[] // orgs this user belongs to currentOrgId: string // last-selected (for org switcher in UI) // Internal collection — webhook idempotency tracking processedWebhookEvents/{eventId} type: string // e.g. 'customer.subscription.updated' processedAt: Timestamp

Key design choices

  • 1
    Roles are per-organisation, not global
    Sebastian might be a Manager in Org A and a User in Org B (e.g. as a consultant). Role lives on the members subcollection, not on the user document.
  • 2
    Org membership is the security boundary
    Firestore rules check request.auth.uid in get(orgDoc).data.memberUids for any access under organizations/{orgId}/**. One company cannot see another's data, period.
  • 3
    Seat-based billing — Stripe handles the count
    Manager subscribes to N seats via Stripe. seatLimit on the org enforces it client-side; Cloud Function syncs from Stripe webhook. Adding a foreman beyond seatLimit prompts a seat upgrade.
  • 4
    Org switcher UI for users in multiple orgs
    Most users will only ever be in one org. For those who aren't, the dashboard top bar gets a small org switcher. Mirrors the project switcher pattern that's already built.
Phase 1

Multi-tenant refactor

Restructure Firestore so every construction company is an isolated tenant with its own projects, members, and roles. The most consequential single piece of work before launch — and easiest to do now while there's no real customer data.

0 of 0
Design & types
  • Fields: id, name, ownerUid, memberUids[], seatLimit, subscriptionStatus, stripeCustomerId, stripeSubscriptionId, createdAt.
  • Fields: uid, role: 'manager' | 'user', addedAt, addedBy. Lives at organizations/{orgId}/members/{uid}.
  • Role moves to per-org. Remove role field from the user document.
  • Replace the existing flat data model with the nested organisations/projects/actionItems hierarchy. Include the diagram.
Firestore migration
  • Migrate the existing single-tenant project doc into a "default" organization for dev data continuity.
  • Subcollection. Path becomes organizations/{orgId}/projects/{projectId}.
  • Path: organizations/{orgId}/projects/{projectId}/actionItems/{itemId}. Drop orgId and projectId fields from the document — implied by path.
  • Seed 2 example organisations with 2 projects each and a handful of action items per project. Useful for testing the org switcher UI.
  • Modify firestore.indexes.json — collection group queries on actionItems may need rebuilding.
Code refactor
  • Mirror ProjectContext's pattern. Persists last-selected org to AsyncStorage.
  • Provider order matters — Org must resolve before Project queries can scope correctly.
  • fetchActionItems, createActionItem, updateActionItem, fetchProjects, createProject, etc.
  • Decision pending client feedback. Architecture supports it (organizationIds[] on user, currentOrgId on user doc), but in v1 the UI shows the user's single org with no switcher. If multi-org is locked in later, this task ships in v1.1.
  • Member list (replaces existing Users section) with role + Remove button. "Invite foreman" button → opens InviteForemanModal. Seat usage indicator. Existing Projects/Trades/Levels stay below as per-project.
  • Role pill reflects currentMemberRole from OrganizationContext, not a global user role. Format: "Acme Construction Pty Ltd · Manager".
Cold-download UX & foreman invites App Store-required
  • firebase init functions. Functions live in functions/src/index.ts.
  • Validates manager role + seat capacity. Creates invites/{inviteId} doc with 7-day expiry. Triggers email send.
  • Renders HTML email with deep link build-pro-hq-v5://invite/{inviteId}. Uses Firebase Trigger Email Extension (or direct SendGrid/Postmark SDK).
  • Validates not expired, not consumed, caller email matches invite. Adds caller to org's members + memberUids. Marks invite consumed.
  • Email input → calls createInvite. Success/error states. Disabled if at seat limit.
  • Handles build-pro-hq-v5://invite/{inviteId}. If logged out → routes to accept-invite signup. If logged in → calls acceptInvite directly.
  • Email pre-filled from invite, password input. Creates Firebase Auth user, calls acceptInvite, routes to dashboard.
  • For randoms who download from App Store without an invite. Headline: "Build Pro HQ is for construction companies." Body: explain web-first signup. Buttons: "Open buildprohq.com.au" (uses expo-web-browser) + "I have an account". Required for App Store Guideline 2.1 compliance.
  • Edge case: foreman lost the email or got the code via SMS. Single text input, "Continue" → routes to invite handler.
  • Existing login form + new "Get started" CTA + "Have an invite code?" small link below. No pricing language anywhere (anti-steering).
  • scheme: "build-pro-hq-v5" already set; verify linking config in expo-router handles /invite/[inviteId] route.
  • New subsection in Section 12 noting review@buildprohq.com.au account must exist in production Firebase before submission. Actual seeding happens in Phase 3/5 — this is just the documentation reminder.
Security rules & testing
  • Helper functions isOrgMember(orgId) and isManager(orgId). Members subcollection writes blocked client-side (Cloud Functions only). Org-doc writes restricted to name by manager.
  • allow get: if true (the inviteId is the secret), allow list: if false, allow write: if false.
  • firebase init emulators. Pick Firestore + Functions + Auth.
  • User from Org A cannot read or write anything in Org B. Use @firebase/rules-unit-testing.
  • Foreman attempts must be rejected. Manager attempts must succeed.
  • Manager attempting to update seatLimit or subscriptionStatus must be rejected (only Cloud Functions write these via Admin SDK).
  • firebase deploy --only firestore:rules --project build-pro-hq-v5---dev-only.
  • Manually create a second org via Firebase Console with a different test user. Log in as each user, confirm they only see their own org's data.
Phase 2

Production hardening

Everything that separates "works on my simulator" from "ready to take real customer money." Error monitoring, account deletion (Apple-required), tightened security, network resilience for site conditions.

0 of 0
Error monitoring (Sentry)
  • Free tier handles ~5,000 errors/month. Plenty for early-stage.
  • npx expo install @sentry/react-native. Configure in app.json via the Expo plugin.
  • Wrap RootLayout in Sentry.wrap(). Set tracesSampleRate: 0.2 for performance monitoring.
  • Falls back to a "Something went wrong — please restart" screen. Reports the error to Sentry.
  • Throws a test error so you can verify the Sentry pipeline is wired up.
  • Sentry.setUser({ id: uid, email, orgId: currentOrgId }) — makes triaging much easier.
Account deletion flow Apple-required
  • Below the Log Out button, in a "Danger zone" section with red border. Subtitle: "This permanently deletes your account and removes you from all organisations."
  • Standard pattern — user must type "delete" exactly to enable the delete button. Prevents accidental tap.
  • Block with "Transfer ownership or delete the organisation first." Provides a path: an "Transfer to..." picker.
  • Removes user from all orgs' memberUids, deletes their assigned action items (or reassigns to manager), deletes their user doc. Then calls auth.deleteUser(uid).
  • Show a brief "Account deleted" toast on the login screen.
  • Create test user, populate data, delete, verify nothing remains. Required evidence for App Store review.
Photo upload reliability
  • Resize to max 2048px on the long edge, JPEG quality 0.8. Reduces upload time and storage cost dramatically.
  • expo-image-manipulator strips EXIF by default in re-encoding. Document this for the privacy questionnaire.
  • 3 retries with 1s, 4s, 16s delays. Don't retry on 4xx errors (client mistake won't get better).
  • Queue: { itemId, localUri, attempts }[]. Survives app force-quit. Resume on next launch.
  • Subtle progress dot or spinner while photos are uploading. Failed indicator if all retries exhausted.
  • Manual QA: start upload, toggle airplane mode on, watch retry, toggle off, confirm upload completes.
Network resilience
  • Complete/reopen already does this. Verify create, edit, delete, photo, drag-reorder all follow the pattern.
  • Use @react-native-community/netinfo. Show a non-intrusive banner: "Offline — changes will sync when you reconnect."
  • enableIndexedDbPersistence(db). Caches reads, queues writes, automatic. Works out of the box on RN.
  • Open app, toggle airplane mode, navigate around, create items. Should feel functional. Toggle off, watch sync.
Security & privacy
  • Cross-reference: this is the Phase 1 rules work. Confirmed deployed before any submission.
  • iOS 17+ requirement. Expo's plugins handle most of it; verify Firebase's privacy manifest is included.
  • Be specific in the strings — generic permission text is a frequent App Store rejection.
  • Production logs leak through to native console / Sentry breadcrumbs. No PII in production logs.
  • EAS production profile should set this. Verify via the EAS Build config.
Empty / loading / error states
  • v5 already does this for most screens. Verify Account, Management/Organisation, project list.
  • Skeletons feel faster. SkeletonRow is already in components/; verify usage everywhere.
  • No "fatal" dead-ends. The existing error banner pattern (tap to retry) should be everywhere.
Phase 3

Assets & polish

App icons, splash screens, App Store screenshots, listing copy. The visual layer between your code and the customer's first impression.

0 of 0
⏱
Currently waiting on

Final logo + colour decision. Most of this phase can start once that's locked in.

App icon
  • Apple applies the rounded-rectangle mask. Ship a square PNG with the design extending to the edge.
  • Set icon in app.json → Expo handles the matrix. Verify with npx expo prebuild.
  • Foreground = logo on transparent. Background = solid colour or gradient. Already configured in app.json; replace the placeholder PNG.
  • Detail loss at small sizes is the most common icon problem. View on a real Home Screen, not just in design tools.
Splash & launch
  • Already configured in app.json. Replace placeholder splash icon when logo finalised.
  • Set userInterfaceStyle: "dark" (already done) prevents the iOS auto-light flash on launch.
Marketing screenshots — App Store
  • Each with a bold heading: "Track every action item," "Share to your team in seconds," "Manager view across the whole crew," etc. Headings convert; raw screenshots don't.
  • Required minimum. Use iPhone 15 Pro Max simulator or a real device.
  • Required for any app marked as iPad-compatible. Show landscape on at least one.
  • Apple stopped requiring 6.5" but accepting it; fine to skip.
Marketing screenshots — Play Store
  • 2–8 images. Most apps use 1080×1920. Same Figma templates as App Store work fine.
  • If you support tablets (you do, supportsTablet=true), Google requires tablet shots for the listing.
  • Same.
  • Hero image at the top of the listing. Brand-forward.
Listing copy
  • "Build Pro HQ" — 12 chars, fits.
  • e.g. "Site action items for trades" (29 chars). Tells the buyer who it's for.
  • Updatable without a new build. Use for launches, sales, news.
  • Lead with the problem (chasing site defects across multiple foremen). Then the solution. Then features as a list. Close with social proof if available.
  • "construction, builder, tradie, action items, site management, defects, snag list, punch list, project management"
  • Different from App Store subtitle — Google's appears below the icon in search results.
Accessibility
  • Share icon, search icon, account icon, multi-select, etc. Required for VoiceOver. Apple sometimes rejects for missing accessibility.
  • Use contrast-ratio.com or Stark in Figma. colors.textMuted on colors.bg is borderline — verify.
  • Triple-click home button (or settings) to enable. Walk through every flow.
  • Settings → Accessibility → Display & Text Size → Larger Text. Watch for clipped labels.
Phase 4

Automated testing

Right-sized for where the project is. Critical-path coverage that catches catastrophic regressions, not exhaustive component tests that you'll never maintain.

0 of 0
Jest unit tests
  • npx expo install jest jest-expo @types/jest. Configure jest.config.js with preset: "jest-expo".
  • Open vs overdue vs due-today vs completed × with/without dueDate. ~12 cases. Fastest way to catch a date-math regression.
  • Verify isTablet() returns correctly for iPhone, iPad, Android phone (small), Android tablet (large).
  • Extract the format function to utils/shareFormatter.ts first. Test every branch: with/without notes, photos, due date.
  • Adding a foreman beyond seatLimit must throw / be rejected.
Detox E2E (smoke only)
  • npm i -D detox. Config in .detoxrc.js. Build for testing with EAS.
  • Catches catastrophic regression. Add more later, only when motivated.
  • Don't pollute dev Firestore with test data. Emulator resets cleanly each run.
CI (GitHub Actions)
  • Currently 8 commits sitting locally. Set up GitHub repo, push.
  • ~30 lines of YAML. Catches type breaks immediately.
  • macOS minutes are expensive on GitHub Actions free tier. Consider running only on PRs to main.
Phase 5

TestFlight rollout

After Apple Dev account lands. Real-device testing across the matrix, friends and colleagues, iterate.

0 of 0
⏱
Blocked on

Apple Developer Program enrolment. Cannot start TestFlight without it.

App Store Connect setup
  • Bundle ID, primary language, app name, default platform.
  • Production bundle ID should drop the version. Suggest au.com.buildprohq.app (Australian convention).
  • Required for EAS to upload builds. Settings → Users and Access → Keys → App Store Connect API.
  • eas credentials. Stores the key encrypted in EAS so future builds upload automatically.
Build & upload
  • eas build --platform ios --profile production. Takes 15–30 min on EAS cloud.
  • eas submit --platform ios. Apple processes it (~30 min).
  • No review required. Up to 100 internal testers.
  • Apple reviews the build first (~24 hours). Then up to 10,000 external testers.
Testing & iteration
  • Aim for at least one tester on each Tier 1 device: iPhone 14/15, iPhone SE, iPad Pro 11", iPad 9th gen.
  • Tag by device + severity. Triage daily during the test period.
  • First TestFlight always surfaces 5–10 issues. Don't submit on TestFlight Build #1.
Phase 6

App Store submission

Apple-specific submission checklist. Privacy questionnaire, age rating, export compliance, screenshots, listing fields. Most rejections happen on first submission — plan to iterate.

0 of 0
Listing fields (App Store Connect → App Information)
  • e.g. https://buildprohq.com.au/privacy. Required.
  • e.g. https://buildprohq.com.au/support or a contact form. Required.
  • Marketing site homepage.
  • High effort, marginal conversion. Add in a later release.
App Privacy questionnaire
  • Firebase Auth.
  • Display name from Firestore.
  • If you set Sentry.setUser with email, this becomes "linked to identity" — be precise.
  • Means no IDFA prompt needed. Verify Firebase Analytics is configured to NOT collect IDFA.
Other questionnaires
  • B2B construction app, no concerning content.
  • ITSAppUsesNonExemptEncryption: false already set in app.json. Verify.
Review test account Required
  • Dedicated reviewer account. Don't reuse a real customer email. Strong password stored in your password manager.
  • In production Firebase. Set seatLimit: 99 manually so the reviewer never hits a limit during exploration.
  • Variety: open / completed / overdue / due-today. Some with photo attachments, some with notes. Mix of trades and levels. Demonstrates the app's range to a reviewer in 60 seconds.
  • Manager role lets the reviewer see the full app surface (Management screen, member list, draggable levels, etc.).
  • Called "Test Org B" with 1 project and a few action items. Reviewer never logs into it but you reference it in App Review notes to prove isolation.
Pre-submission verification
  • Test on a fresh simulator with the production build. Apple will log in. If it fails, instant rejection.
  • Reviewer might tap "Get started" instead of logging in with provided credentials. The explainer screen + "Open buildprohq.com.au" must work.
  • Apple checks for it specifically. Frequent first-submit rejection cause.
  • Common rejection. Production listing must look production.
  • Suggested text: "B2B SaaS for construction companies. Real customers sign up at buildprohq.com.au. Test credentials provided. App is multi-tenant — Test Org B exists separately to demonstrate isolation. Tap 'Get started' on the login screen to see the explainer for new users."
  • Email: review@buildprohq.com.au. Password: from password manager. Apple stores these encrypted.
Submit & iterate
  • Review takes 24–48h typically.
  • ~30% first-submission rejection rate. Plan for 1–2 cycles.
  • Approved doesn't mean live. "Manual" gives you control over the launch moment.
Phase 7

Play Store submission

Google Play Console submission. Generally faster review than Apple but with a 14-day closed-test requirement before production for new developer accounts.

0 of 0
Account & setup
  • Verification can take a few days. Identity verification + business verification.
  • Service account JSON from Google Cloud → Play Console linkage.
  • eas build --platform android --profile production. Outputs an AAB.
Listing
Reviewer access (same test account as App Store)
  • Same review@buildprohq.com.au account created for App Store. Google asks for these in App access → "All or some functionality is restricted." Tick that box.
  • Google reviewers are less rigorous than Apple's but read it anyway. Saves you a back-and-forth.
Required compliance forms
  • Auto-rates across regional systems. Honest answers — they're trivially easy to verify.
  • Same data, different form. Be consistent across the two stores.
Testing tracks
  • Google now requires this before allowing graduation to production for new dev accounts. Plan around it.
Phase 8

Billing & subscriptions

Per-seat Stripe subscription, one Stripe Customer per construction company. Stripe holds the source of truth for seat count and status; the app reads via webhook-synced fields on the org doc and enforces accordingly. Australia-first launch — GST handled via Stripe Tax.

0 of 0
ⓘ
The architecture in one sentence

You have one Stripe account. Each construction company is a Stripe Customer with one Subscription. quantity on that subscription = seat count. Cloud Functions sync subscription state to organizations/{orgId} via webhooks. The app reads seatLimit + subscriptionStatus from the org doc; client never writes those fields.

✓
Apple App Store — covered by Guideline 3.1.3(b)

This pattern (web billing, app shows status) is explicitly allowed under "Multiplatform Services." It's how every B2B SaaS app ships (Slack, Asana, Notion, etc.). No Apple IAP required, no 15–30% cut. Australia-first launch means the EU DMA rules don't apply to you.

A. Architecture & pricing decisions

Pricing model decisions
  • Recommended: $A19–29/user/month. Survey 2–3 prospective tradies before locking it in. Mid-market construction SaaS sits around $A25/seat.
  • Recommendation: included free. Reduces buyer friction ("1 manager + 5 foremen = pay for 5"). Easier to message.
  • e.g. monthly $A25/seat → annual $A250/seat (saves ~$50). Annual buyers churn far less, prepay smooths cash flow.
  • Lower-friction signup. If "tire-kickers" become a problem post-launch, switch to "card up front, charge after 14 days."
  • Recommendation: web-first. Manager signs up at buildprohq.com.au/signup on desktop, enters card, then downloads the app. App users (foremen) come in via invite link, never touch billing.

B. Stripe account & product setup

Account & business details
  • Account name: "Build Pro HQ Pty Ltd" once incorporated. Use a generic email until then.
  • Required to activate live mode. Stripe needs identity verification on Pty Ltd directors.
  • Settings → Tax. Auto-calculates 10% GST for Australian customers. Costs 0.5% of taxed transactions. Worth it from day one — no manual GST headaches at EOFY.
  • Mandatory above $75k. Even below, voluntary registration lets you claim GST credits on business expenses. Talk to your accountant.
Product & pricing in Stripe Dashboard
  • Description: "Per-foreman monthly subscription to Build Pro HQ, including the manager seat at no extra cost."
  • Quantity-based is simpler — pass quantity: seatCount on the subscription. Stripe multiplies. Per-seat invoicing automatic.
  • Settings → Billing → Customer Portal. Toggle features on. Pre-built hosted page; saves weeks of work building it yourself.
  • Or "Tax-inclusive" if you prefer to advertise GST-inclusive prices. Talk to your accountant — affects how prices are displayed in marketing.
  • Settings → Branding. Stripe sends professional-looking invoices automatically.
  • Settings → Billing → Subscriptions and emails → Smart Retries. ML-driven retry timing. On by default; verify settings.

C. Firestore data model & security

Org doc fields & rules
  • stripeCustomerId, stripeSubscriptionId, subscriptionStatus, seatLimit, trialEndsAt, currentPeriodEndsAt, billingInterval. See data model on Overview.
  • Manager can update name, memberUids via specific rules. Billing fields only writable by Cloud Functions (which use the Admin SDK and bypass rules).
  • Each webhook event ID gets stored after successful processing. Replays are detected and skipped.

D. Cloud Functions backend

Setup & secrets
  • firebase init functions. Use TS to match the rest of the codebase.
  • cd functions && npm i stripe. Pin to a known-good version.
  • STRIPE_SECRET_KEY (live and test variants), STRIPE_WEBHOOK_SECRET. Never put these in code or env files.
Callable functions (app → backend)
  • Called when a new manager signs up. Creates Stripe Customer (with metadata: bphqOrgId, bphqOrgName, bphqManagerEmail), creates Subscription with trial_period_days: 14 and quantity: 1, writes the new organizations/{orgId} doc with the resulting IDs.
  • Called from the app's "Manage subscription" button. Verifies the caller is the org manager, then creates a Stripe Billing Portal session and returns the URL. App opens it in a webview / external browser.
  • If the deleted user is sole manager of any org with active subscription, block. Otherwise: remove from memberUids, decrement Stripe quantity if seat is freed (or leave for manual reduction).
Webhook endpoint
  • Use onRequest. Stripe sends events as POST requests; respond 200 fast.
  • stripe.webhooks.constructEvent(rawBody, sig, STRIPE_WEBHOOK_SECRET). Without this, anyone who knows your endpoint can spoof events.
  • Stripe retries webhooks; same event can arrive twice. Store event ID after success, return 200 immediately on duplicate.
  • Look up org by stripeCustomerId (or fall back to metadata.bphqOrgId). Sync seatLimit, subscriptionStatus, currentPeriodEndsAt, trialEndsAt.
  • Set subscriptionStatus: 'canceled'. App's read-only mode kicks in.
  • Confirm or flip subscriptionStatus. Stripe handles retries automatically; your job is just to mirror state.
  • Fires 3 days before trial ends. Trigger an email to the manager: "Your trial ends in 3 days — add a payment method to continue."
  • Developers → Webhooks → Add endpoint. Stripe gives you the signing secret to store in step 23.
Reconciliation safety net
  • onSchedule('0 3 * * *'). Lists all active Stripe subscriptions, compares quantity + status to each org doc, logs drift to Sentry, optionally auto-corrects.
  • Find orgs with subscriptionStatus === 'past_due' for 7+ days. Mark them for soft-lock, email the manager.

E. App integration

Account screen — Subscription section
  • Above the Log Out button. Shown only when the user is the org manager. Hidden for foremen.
  • Example layout: "Foreman Seats × 5 · Active · Renews 14 May." Status pill colour from existing palette.
  • Calls createCustomerPortalSession Cloud Function. Opens result URL in WebBrowser.openBrowserAsync() from expo-web-browser — uses Safari View Controller / Custom Tabs, not webview (App Store prefers this).
  • "Trial ends in 2 days — add a payment method to continue" with the Manage subscription button.
  • Persistent banner. Manager-only "Update payment" button to portal.
Seat enforcement
  • Cross-reference with Phase 1 invite flow. Modal: "You're at your seat limit (5/5). Upgrade your subscription to add another foreman." → portal.
  • Disable creating action items, photos, project changes. Existing data still readable. Banner: "Your subscription is paused — update payment to resume."
  • After 30 days Stripe will have given up retries. Treat as essentially canceled; don't delete data, just freeze access.

F. Apple App Store compliance

Anti-steering & multiplatform rules
  • No "$A19/seat/month" anywhere in the app. Pricing lives only on the marketing site and Stripe Customer Portal.
  • Plain "Manage subscription" button is fine. "Upgrade — only $A29/month!" is anti-steering.
  • "You're at your seat limit. Manage your subscription." — fine. "Cheaper if you upgrade on our website" — not fine.
  • When submitting: "This is a B2B SaaS app. Subscriptions are purchased on buildprohq.com.au by the construction company manager. App users (foremen) access content their company has acquired via Multiplatform Services (3.1.3(b))."

G. Operational workflow — what Sebastian does day-to-day

Daily / weekly
  • Shows MRR, active subscriptions, churn, failed payments. Glance once a day. No external dashboard tool needed for the first 50–100 customers.
  • Stripe Dashboard → Settings → Email preferences. Tier them by importance (cancellations = immediate; new subscriptions = daily digest).
  • If the daily reconciliation Cloud Function logs drift to Sentry, you want to know.
Customer support workflows
  • Stripe Dashboard → find Customer (search by email or bphqOrgId in metadata) → click invoice → "Refund." Two clicks.
  • Customer Portal allows managers to do it. If you want to comp manually: Stripe Dashboard → subscription → "Update quantity" with proration off.
  • Subscription → "Update" → "Extend trial" by N days. Webhook fires automatically; org doc syncs.
  • When you eventually onboard a support hire, "Billing" label means "needs Stripe Dashboard access."
Tax & accounting
  • CSV export of all transactions. Hand to accountant for BAS / EOFY.
  • Stripe has native Xero integration. Auto-syncs invoices and payouts. Saves your accountant a lot of time once you have >20 customers.

H. Testing the lifecycle

Test mode rehearsal — every state transition
Production cutover
  • Use the same name/price. Note new live Price IDs and update Cloud Functions config.
Reference

Accounts & services to set up

Every external account/service needed to operate Build Pro HQ as a real product. Order matters — some block others.

0 of 0
Can do now (while waiting on Pty Ltd)
  • Hosts privacy policy, support page, terms, marketing pitch. Cloudflare Pages or Webflow.
  • Required for both stores. Hand-write or use Termly. Drafted Phase 3.
  • Especially important for B2B SaaS — defines the contract.
  • Required for store listings. Forward to your personal email until you have a help desk tool.
  • Don't share dev and production. Set up build-pro-hq-prod with the same config. Switch via env var.
After Pty Ltd is approved
  • Australian company enrolment requires DUNS number, ABN. Allow 2–6 weeks for approval.
  • Identity verification typically 1–7 days.
  • Required to receive any revenue. Multi-step. Tax form is W-8BEN-E for Australian companies selling in the US.
Nice to have, can wait
  • When you have ~10+ customers. Until then, support@ + a Trello board is fine.
  • Enterprise hygiene. Optional for v1.
  • Firebase Analytics is fine until you outgrow it. Defer.
  • Only worth it if you go App Store-billed subscriptions. Not needed for Stripe-only model.
Reference

Device test matrix

Tier 1 = must work flawlessly. Tier 2 = should work, edge cases tolerable. Use during TestFlight + Play Store internal testing.

0 of 0
Tier 1 — must work flawlessly
  • Most common phone among prospective users.
  • Often forgotten; common with budget-conscious tradies.
Tier 2 — should work, edge cases tolerable
Test scenarios per device
How to test devices you don't own
  • Cheap and effective. Aim for at least one tester per Tier 1 device.
  • One month before submission lets you cover devices nobody you know has.
  • Caveat: emulators don't replicate real network conditions, photo capture, or haptics. Real devices are still required.