Architecture

System Overview

Evergrn is a three-tier application:

┌──────────────────────┐   ┌───────────────────────┐   ┌─────────────────────┐
│  React Web (Vite)    │   │  Azure Static Web App  │   │  React Native (Expo)│
│  port 5173 (dev)     │   │  web.staging.evergrn.co│   │  iOS only           │
│  Vite proxy → :3000  │   │  Entra MFA required    │   │  staging.evergrn.co │
└────────┬─────────────┘   └──────────┬─────────────┘   └──────────┬──────────┘
         │ localhost                   │ VITE_API_BASE              │ JWT auth
         │                            │ fetch interceptor           │
         ▼                            ▼                             ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                    Node.js / Express API  (port 3000)                        │
│           src/app.js → src/routes/* → src/middleware/*                       │
│                                                                              │
│  Dev:     evergrn-api-dev-c7dxhkf3ctcgdqby.canadacentral-01.azurewebsites.net│
│  Staging: staging.evergrn.co (evergrn-api-stage App Service B1)              │
│  Prod:    evergrn.co (not yet provisioned)                                   │
└───────────────────┬──────────────────────────────────────────────────────────┘
                    │ Prisma ORM
                    ▼
         ┌─────────────────────┐     ┌─────────────┐
         │  PostgreSQL          │     │   Stripe    │
         │  dev:   evergrn-db   │     │   (payments)│
         │  stage: evergrn-db-  │     │             │
         │         stage        │     │             │
         └─────────────────────┘     └─────────────┘

Environments

	Dev	Staging	Production
API URL	evergrn-api-dev-*.azurewebsites.net	staging.evergrn.co	evergrn.co (TBD)
Web URL	localhost:5173 (Vite)	web.staging.evergrn.co (Azure SWA)	evergrn.co (TBD)
Web hosting	Vite dev server	Azure Static Web App Standard	TBD
Database	evergrn-db (shared dev data)	evergrn-db-stage (isolated)	evergrn-db-prod (TBD)
GodMode	✅ Enabled	❌ Disabled	❌ Disabled
Access control	Open	Entra CA policy (MFA) on web; API open	Public
Deploy trigger	.\deploy.ps1	API: ADO pipeline ID 2 (manual); Web SWA: ADO pipeline ID 4 (manual)	TBD
iOS API target	Dev App Service (via .env)	staging.evergrn.co (via eas.json env)	TBD

Tech Stack

Layer	Technology	Version / Notes
API runtime	Node.js + Express	CommonJS modules
ORM	Prisma	PostgreSQL driver
Database	PostgreSQL	Local in dev
Auth	jsonwebtoken + bcryptjs	HS256, 12 salt rounds
Payments	Stripe	PaymentIntents with manual capture
File uploads	Multer (memoryStorage) + @azure/storage-blob	Azure Blob Storage (evergrnuploads)
Input validation	zod	Schema validation middleware for all body-receiving routes
Rate limiting	express-rate-limit	Auth login + forgot-password endpoints
Web framework	React 19 + Vite	TailwindCSS v4
Mobile framework	React Native 0.81.5 + Expo SDK 54	Hermes engine; iOS primary; Android support in progress (eas.json Android profiles added 2026-06-28, Google Play Developer account pending approval)
Mobile auth storage	expo-secure-store	Encrypted on device
Push notifications	expo-notifications + expo-server-sdk	Expo push token saved on User/Provider; sent from backend
Maps (web)	Leaflet	MapPicker component
Navigation (mobile)	React Navigation v6	Stack + Bottom Tabs
Weather	Open-Meteo + zippopotam.us	Free, no API key; 1h in-memory cache per ZIP; zippopotam.us for ZIP→lat/lng geocoding
Observability	Azure Application Insights	SDK in server.js; auto-instruments Express, Prisma, Stripe
Document Intelligence	@azure-rest/ai-document-intelligence	prebuilt-idDocument (driver's license OCR) + prebuilt-read (insurance certificate OCR); src/config/docIntelligence.js

Database Schema

Models

User (customer accounts)

Field	Type	Notes
id	String (cuid)	PK
email	String	unique
password	String	bcrypt hash
name	String
address	String	home address for job ZIP inference
zip	String
lat / lng	Float?	optional map pin
stripeCustomerId	String?	set on first card save
stripePaymentMethodId	String?	saved card reference
stripeSubscriptionId	String?	set when customer starts premium subscription
isPremium	Boolean	default false; unlocks multi-address, favorites, pro notes, spend summary, seasonal alerts
premiumSince	DateTime?	set when subscription first activates
seasonalAlertsEnabled	Boolean	default false; premium-only opt-in for seasonal push alerts
pushToken	String?	Expo push token; registered on mobile login
createdAt / updatedAt	DateTime

Relations: jobs[], payments[], reviews[], addresses UserAddress[], reports JobReport[], favoriteProviders FavoriteProvider[], proNotes ProNote[]

Provider (professional accounts)

Field	Type	Notes
id	String (cuid)	PK
email	String	unique
password	String	bcrypt hash
name	String
phone	String?
companyName	String?
companyUrl	String?
insuranceInfo	String?	Auto-populated by OCR from insCheck* fields; not editable from mobile (image-upload only)
insDocUrl	String?	Azure blob URL of uploaded insurance certificate image
insCheckStatus	String?	pending / active / expired / review / error
insCheckCarrier	String?	OCR-extracted carrier name
insCheckPolicy	String?	OCR-extracted policy number
insCheckEffective	String?	OCR-extracted effective date (ISO format)
insCheckExpiry	String?	OCR-extracted expiry date (ISO format)
insCheckCoverage	String?	OCR-extracted coverage amount
insCheckFlags	String[]	e.g. ['expired', 'no_policy', 'no_carrier', 'near_expiry']
insCheckAt	DateTime?	Timestamp of last OCR run
logoUrl	String?	Azure blob URL (https://evergrnuploads.blob.core.windows.net/logos/...)
headshots	String[]	Staff headshot blob URLs; required before bidding
idDocFront	String?	Driver's license front blob URL; required before bidding
idDocBack	String?	Driver's license back blob URL; required before bidding
idCheckStatus	String?	pending / passed / review / failed / error
idCheckName	String?	OCR-extracted full name
idCheckDOB	String?	OCR-extracted date of birth (ISO format)
idCheckExpiry	String?	OCR-extracted expiry date (ISO format)
idCheckState	String?	OCR-extracted issuing state/region
idCheckFlags	String[]	e.g. ['expired', 'near_expiry', 'no_dob', 'not_a_license']
idCheckAt	DateTime?	Timestamp of last OCR run
services	String[]	e.g. ['lawncare','snowplowing']
serviceZips	String[]	ZIP codes they serve
availability	Json?	Weekly schedule: { mon: { start, end, on }, ... }
isPremium	Boolean	default false — Preferred Pro member
premiumSince	DateTime?	when Preferred Pro was activated
premiumBilledMonth	String?	last month billed ("YYYY-MM") — prevents double-charging
preferredProAppliedAt	DateTime?	set when provider applies to Preferred Pro
pushToken	String?	Expo push token; registered on mobile login
createdAt / updatedAt	DateTime

Relations: quotes[], jobs[], reviews[]

Job

Field	Type	Notes
id	String (cuid)	PK
customerId	String	FK → User
providerId	String?	FK → Provider; set on quote accept
addressId	String?	FK → UserAddress; set if customer selects a saved address at booking
service	String	lawncare / snowplowing / handyman / home_cleaning
address	String	copied from customer address at creation
zip	String	used for provider matching
description	String?	customer's free-text description
preferredAt	DateTime	customer's requested time
isAsap	Boolean	default false; urgent jobs sort to top of provider feed + trigger URGENT push notification
recurringGroupId	String?	shared ID linking jobs in the same recurring series
lat / lng	Float?	optional
details	Json?	structured service-specific details
images	String[]	general job photos (blob URLs)
beforeImages	String[]	set when provider starts job (blob URLs)
afterImages	String[]	set when provider completes job (blob URLs)
status	JobStatus	see enum below
createdAt / updatedAt	DateTime

Relations: customer, provider?, userAddress?, quotes[], messages[], payment?, review?, report JobReport?

Quote

Field	Type	Notes
id	String (cuid)	PK
jobId	String	FK → Job
providerId	String	FK → Provider
amount	Float	provider's net price
platformFeeRate	Float	0.18 (18%)
platformFee	Float	amount × 0.18
totalAmount	Float	amount + platformFee
scheduledAt	DateTime?	proposed service date/time
note	String?	optional message to customer
status	QuoteStatus	PENDING / ACCEPTED / REJECTED
createdAt	DateTime

Message

Field	Type	Notes
id	String (cuid)	PK
jobId	String	FK → Job
senderId	String	User.id or Provider.id
senderRole	String	"user" or "provider"
content	String
createdAt	DateTime

Review

Field	Type	Notes
id	String (cuid)	PK
jobId	String	unique — one review per job
customerId	String	FK → User
providerId	String	FK → Provider
rating	Int	1–5
comment	String?
createdAt	DateTime

Payment

Field	Type	Notes
id	String (cuid)	PK
jobId	String	unique — one payment per job
customerId	String	FK → User
amount	Float	quote totalAmount (platform take + provider net)
stripePaymentIntentId	String?	set on authorization at quote acceptance
tipAmount	Float?	set if customer adds a tip after job completion
stripeTipPaymentIntentId	String?	separate PaymentIntent for the tip charge
status	PaymentStatus	PENDING / PAID / FAILED
createdAt	DateTime

Current behavior (pre-production): Stripe capture fires immediately on job completion. The Payment Release Flow (HELD / DISPUTED states) is designed but not yet implemented — see the "Payment Release Flow" section below.

UserAddress (saved addresses per customer)

Field	Type	Notes
id	String (cuid)	PK
userId	String	FK → User
label	String	e.g. "Home", "Cabin" — default "Home"
address	String	street address
zip	String
isPrimary	Boolean	only one per user; used as default for booking
lat / lng	Float?	optional map pin
streetViewPhoto	String?	blob URL — uploaded by customer for provider reference
serviceAreaPhotos	String[]	blob URLs — additional property photos (driveway, lawn, etc.)
drivewayLength	Float?	in feet — used by snowplow providers
lawnAcres	Float?	lawn size — used by lawncare providers
createdAt	DateTime

JobReport (customer dispute, within 72h of completion)

Field	Type	Notes
id	String (cuid)	PK
jobId	String	unique — one report per job
customerId	String	FK → User
description	String	customer's description of the problem
createdAt	DateTime

72-hour window is enforced server-side using job.updatedAt at the time status was set to COMPLETED. One report per job (DB unique on jobId).

ProviderPayout [NOT YET IMPLEMENTED — required before go-live]

Internal ledger of what is owed to each provider per job after a successful capture. Created by the daily payout cron when a payment is released.

Field	Type	Notes
id	String (cuid)	PK
providerId	String	FK → Provider
jobId	String	FK → Job
paymentId	String	FK → Payment
amount	Float	provider's net share = quote.amount (totalAmount minus 18% platform fee)
status	ProviderPayoutStatus	PENDING / PAID
batchDate	DateTime	the 8 AM batch run that released this payout
paidAt	DateTime?	set when manual ACH/Stripe transfer is confirmed
createdAt	DateTime

Admin [GODMODE — remove before production]

Field	Type	Notes
id	String (cuid)	PK
email	String	unique
password	String	bcrypt hash
createdAt	DateTime

FavoriteProvider (customer's saved providers — premium only)

Field	Type	Notes
id	String (cuid)	PK
userId	String	FK → User
providerId	String	FK → Provider
createdAt	DateTime
Unique constraint: (userId, providerId)

ProNote (private customer note on a provider — premium only)

Field	Type	Notes
id	String (cuid)	PK
userId	String	FK → User
providerId	String	FK → Provider (not a DB relation — just stores the ID)
note	String	customer's private note text
updatedAt	DateTime	@updatedAt
Unique constraint: (userId, providerId) — one note per provider per customer

Notification (persistent in-app notification history)

Field	Type	Notes
id	String (cuid)	PK
recipientId	String	User.id or Provider.id
recipientType	String	"user" or "provider"
title	String
body	String
jobId	String?	optional link to a job
read	Boolean	default false
createdAt	DateTime
Index: (recipientId, recipientType, read)

WaitlistEmail (coming-soon page signups)

Field	Type	Notes
id	String (cuid)	PK
email	String	unique
name	String?
zip	String?
role	String?	"customer" or "provider"
createdAt	DateTime

Staff (internal support accounts)

Field	Type	Notes
id	String (cuid)	PK
email	String	unique
password	String	bcrypt hash
name	String
role	StaffRole	see enum below
createdAt	DateTime
Relations: elevationRequests[], assignedTickets[]

ElevationRequest (staff request to impersonate a user/provider account)

Field	Type	Notes
id	String (cuid)	PK
staffId	String	FK → Staff
targetId	String	User.id or Provider.id being impersonated
targetRole	String	"user" or "provider"
targetName / targetEmail	String	snapshot at request time
reason	String	required justification
status	ElevationStatus	PENDING → APPROVED → ACTIVE → DEACTIVATED; or REJECTED
requestedAt	DateTime
approvedAt / approvedBy	DateTime? / String?	set when admin clicks email approve link
activatedAt	DateTime?	set when staff triggers impersonation token
deactivatedAt / deactivatedBy	DateTime? / String?	auto-set after 15 min of ACTIVE state
notes	String?	internal admin notes

SupportTicket

Field	Type	Notes
id	String (cuid)	PK
submitterId	String	User.id or Provider.id
submitterRole	String	"user" or "provider"
submitterName	String	snapshot at submission
subject	String
body	String
status	TicketStatus	OPEN → IN_PROGRESS → RESOLVED → CLOSED
assignedToId	String?	FK → Staff
createdAt / updatedAt	DateTime
resolvedAt	DateTime?
notes	String?	internal staff notes

AuditEvent (actions taken during an active elevation/impersonation session)

Field	Type	Notes
id	String (cuid)	PK
elevationId	String	FK → ElevationRequest
method	String	HTTP method of the action
path	String	API path accessed
body	String?	request body (sanitized)
createdAt	DateTime
Index: (elevationId) — every request made during an active elevation is logged by auditLog middleware

Enums

JobStatus:    PENDING → QUOTED → ACCEPTED → ON_THE_WAY → IN_PROGRESS → COMPLETED
                                                                      → CANCELLED
QuoteStatus:  PENDING → ACCEPTED | REJECTED
PaymentStatus: PENDING → PAID | FAILED
   (HELD and DISPUTED are designed for the Payment Release Flow — not yet in schema)

StaffRole:    customer_support | professional_support | technical_support | internal_audit

ElevationStatus: PENDING → APPROVED → ACTIVE → DEACTIVATED
                         → REJECTED

TicketStatus: OPEN → IN_PROGRESS → RESOLVED → CLOSED

ProviderPayoutStatus [NOT YET IMPLEMENTED]:
              PENDING → PAID

File Structure

evergrn/
├── server.js                        Entry point — loads .env, starts Express on :3000
├── package.json                     Backend dependencies
├── .env                             Secrets (DATABASE_URL, JWT_SECRET, STRIPE_*)
├── .env.example                     Template for new environments
│
├── prisma/
│   └── schema.prisma                All Prisma models, enums, relations
│
├── src/
│   ├── app.js                       Express setup: middleware, routes, static files
│   ├── config/
│   │   ├── db.js                    PrismaClient singleton
│   │   ├── stripe.js                Stripe client singleton
│   │   ├── push.js                  Expo push notification sender (expo-server-sdk)
│   │   ├── blob.js                  Azure Blob Storage helpers (uploadBuffer, uploadFiles, makeUpload); createIfNotExists() called before every upload
│   │   ├── docIntelligence.js       Azure AI Document Intelligence: analyzeIdDocument() (prebuilt-idDocument) + analyzeInsuranceDocument() (prebuilt-read)
│   │   ├── notificationQueue.js     In-memory Map queue for admin-to-user banners (replace with Redis pre-launch)
│   │   ├── email.js                 ACS email templates + sendEmail() — quoteReceived, quoteAccepted, jobCompleted, waitlistConfirmation
│   │   └── mailer.js                ACS-backed sendPasswordReset() — used by /auth/forgot-password
│   ├── middleware/
│   │   ├── auth.js                  authenticate() — JWT verification, sets req.user
│   │   ├── validate.js              validate(schema) — Zod middleware; returns 400 on invalid body
│   │   ├── auditLog.js              auditLog — globally mounted; logs all requests during active elevation sessions to AuditEvent
│   │   └── error.js                 Global error handler
│   ├── schemas/
│   │   └── index.js                 18 Zod schemas for all body-receiving endpoints
│   └── routes/
│       ├── auth.js                  /auth/* — register + login for both roles + password reset
│       ├── jobs.js                  /jobs/* — full job lifecycle, messages, images, report, tip, recurring
│       ├── quotes.js                /quotes/* — quoting, acceptance, market rate
│       ├── providers.js             /providers/me/* — profile, headshots, ID docs (OCR), insurance doc (OCR), logo, schedule, insights, smart bundles, availability, premium-insights, notifications, preferred-pro, support
│       ├── payments.js              /payments/* — Stripe card save, setup intent, premium subscription
│       ├── reviews.js               /reviews — post review after completion
│       ├── users.js                 /users/me/* — profile, location, addresses, address photos, favorites, pro notes, spend summary, seasonal alerts, push token, notifications, support
│       ├── services.js              /services/available — service lookup by ZIP
│       ├── weather.js               /weather?zip= — 14-day forecast (Open-Meteo + zippopotam.us, 1h cache)
│       ├── waitlist.js              /waitlist — coming-soon page signups, sends ACS confirmation email
│       ├── webhooks.js              /webhooks — Stripe event handling (PaymentIntents + subscription lifecycle)
│       ├── staff.js                 /staff/* — internal support portal (login, elevation, impersonation, tickets, audit)
│       ├── driveTime.js             /drive-time — ETA + distance via OSRM (lat/lng or address string inputs)
│       └── admin.js                 /admin/* — [GODMODE] dev tooling + notify endpoint
│
├── uploads/                         Legacy local disk — no longer used for new uploads
│                                    (Azure Blob Storage: evergrnuploads.blob.core.windows.net)
│
├── client/                          React web frontend
│   ├── vite.config.js               Vite + proxy config
│   ├── package.json
│   └── src/
│       ├── main.jsx                 React 19 entry point
│       ├── App.jsx                  Router + layout + ImpersonationBanner [GODMODE]
│       ├── context/
│       │   └── AuthContext.jsx      Auth state, localStorage, JWT decode
│       ├── components/
│       │   ├── Navbar.jsx           Top nav (hidden on landing + dashboards)
│       │   ├── EvergrnLogo.jsx      SVG logo
│       │   ├── MapPicker.jsx        Leaflet map for location selection
│       │   └── MessageThread.jsx    Job messaging UI
│       └── pages/
│           ├── Landing.jsx          Marketing homepage
│           ├── Login.jsx            Customer login
│           ├── Register.jsx         Customer registration
│           ├── Dashboard.jsx        Customer main UI — jobs, quotes, details
│           ├── ProviderPortal.jsx   Provider landing page
│           ├── ProviderLogin.jsx    Provider login
│           ├── ProviderRegister.jsx Provider registration
│           ├── ProviderDashboard.jsx Provider UI — browse, quote, schedule, insights
│           └── GodMode.jsx          [GODMODE] Admin impersonation dashboard
│
├── mobile/                          React Native mobile app
│   ├── App.js                       SafeAreaProvider + AuthContext + RootNavigator
│   ├── app.json                     Expo config (bundle ID, theme color, push notification plugin)
│   ├── eas.json                     EAS Build profiles (development/simulator, device, preview, production)
│   ├── package.json
│   └── src/
│       ├── api.js                   apiFetch() wrapper + BASE_URL (hardcoded to Azure App Service URL)
│       ├── context/
│       │   └── AuthContext.js       SecureStore token storage + JWT parse + push token registration on login
│       ├── components/
│       │   ├── MessageThread.js     Messaging UI (shared with web pattern)
│       │   ├── StarRating.js        5-star rating input/display
│       │   └── NotificationBanner.js Animated slide-in banner; persistent until user taps X
│       ├── hooks/
│       │   └── useNotificationPoller.js 30s polling hook — checks server queue then job state changes
│       ├── utils/
│       │   └── pushNotifications.js Requests permission, gets Expo push token, saves to backend
│       ├── navigation/
│       │   ├── RootNavigator.js     Auth gate → role-based navigator; mounts NotificationBanner overlay
│       │   ├── AuthNavigator.js     Stack: Landing → Login/Register flows
│       │   ├── CustomerNavigator.js Bottom tabs for customer role
│       │   └── ProviderNavigator.js Bottom tabs for provider role
│       └── screens/
│           ├── auth/
│           │   ├── LandingScreen.js
│           │   ├── LoginScreen.js
│           │   ├── RegisterScreen.js
│           │   ├── ProviderLoginScreen.js
│           │   └── ProviderRegisterScreen.js
│           ├── customer/
│           │   ├── HomeScreen.js       Browse + search
│           │   ├── BookScreen.js       Post a new job
│           │   ├── JobsScreen.js       My jobs list
│           │   ├── JobDetailScreen.js  Detail view + messaging
│           │   └── ProfileScreen.js    Account settings + Report a Problem (72h window)
│           └── provider/
│               ├── AvailableScreen.js          Job board + conflict filter
│               ├── ActiveScreen.js             Assigned/active jobs
│               ├── ScheduleScreen.js           Upcoming schedule view
│               ├── ProviderJobDetailScreen.js  Quote submission + messaging
│               └── ProviderProfileScreen.js    Profile editing
│
├── scripts/                          Dev/seed utilities (not for production)
│   ├── seedAdmin.js                  Creates godmode@evergrn.com [GODMODE]
│   ├── seedAvailableJobs.js          Populates test PENDING jobs
│   ├── seedSchedule.js               Adds ACCEPTED jobs to a provider
│   ├── seedConflicts.js              Seeds conflicting jobs for UI testing
│   ├── seedMultiAddress.js           Creates multiaddress@test.com with 3 saved addresses
│   ├── seedAlexJobs.js               Creates completed jobs for Alex (dispute workflow testing)
│   └── reassignSchedule.js           Moves jobs between provider accounts
│
└── current-documentation/            This folder

Naming Conventions

Database / Prisma

• Models: PascalCase (User, Provider, Job, Quote)
• Fields: camelCase (customerId, serviceZips, stripePaymentIntentId)
• Enums: SCREAMING_SNAKE_CASE (PENDING, ON_THE_WAY, IN_PROGRESS)
• IDs: cuid() — collision-resistant unique IDs, URL-safe, sortable

Backend (Node.js)

• Route files: lowercase kebab or single word matching the resource (auth.js, jobs.js, webhooks.js)
• Route variables: camelCase (req.user, req.body.jobId)
• Middleware functions: camelCase verb+noun (authenticate, errorHandler)
• Config exports: single named export matching the tool (prisma, stripe)

Web Frontend (React)

• Component files: PascalCase (Dashboard.jsx, MapPicker.jsx, AuthContext.jsx)
• Page components: PascalCase, one page per file
• Context: named *Context.jsx, exports use* hook and *Provider
• Inline styles: JavaScript object style — no class names except on Tailwind-powered elements
• State variables: camelCase, descriptive (scheduleJobs, filterFree, deleteTarget)

Mobile (React Native)

• Screen files: PascalCase + Screen suffix (AvailableScreen.js, ProviderJobDetailScreen.js)
• Navigator files: PascalCase + Navigator suffix
• Component files: PascalCase (MessageThread.js, StarRating.js)
• StyleSheet keys: camelCase (filterBar, conflictBanner, cardConflict)

API Routes

• Pattern: /resource or /resource/:id/sub-resource
• Plural nouns for collections: /jobs, /quotes, /providers
• /me shortcut for authenticated user's own resource: /users/me, /providers/me
• Action sub-routes for state transitions: /jobs/:id/cancel, /jobs/:id/start, /jobs/:id/complete
• Versioning: not yet implemented — all routes are unversioned

File Uploads

All uploads go to Azure Blob Storage (evergrnuploads, Cool tier, Canada Central). Files are held in memory by multer and streamed directly to blob — nothing touches the container filesystem.

Container	Path pattern	Used by
jobs	{jobId}-{timestamp}-{random}.{ext}	Job photos, before/after workflow photos
logos	{providerId}.{ext}	Provider company logos (overwrites on update)
headshots	{providerId}-{timestamp}.{ext}	Provider staff headshots
id-docs	{providerId}-front/back-{timestamp}.{ext}	Provider ID verification docs; OCR runs in background after upload
insurance-docs	{providerId}-{timestamp}.{ext}	Provider insurance certificate images; OCR runs in background after upload
messages	{jobId}-{timestamp}-{random}.{ext}	Photo attachments sent in job message threads
addresses	{addressId}-street/area-{timestamp}.{ext}	Customer property photos

All returned URLs are full blob URLs: https://evergrnuploads.blob.core.windows.net/{container}/{blobName}

[GODMODE] Marker

All dev-only admin tooling is tagged with // [GODMODE] comments. To find every marked line:

grep -r "\[GODMODE\]" .

Files to delete entirely before production: src/routes/admin.js, client/src/pages/GodMode.jsx, scripts/seedAdmin.js

Platform Fee

Platform fee is 18% calculated at quote time:

platformFee   = quote.amount × 0.18
totalAmount   = quote.amount + platformFee

The platformFeeRate is stored on each Quote record so historical rates are preserved if the rate ever changes.

---

Payment Release Flow [NOT YET IMPLEMENTED — required before go-live]

This section documents the intended production payment lifecycle. The current codebase captures Stripe payments immediately on job completion, which must be changed before launch.

Design goals

• Customer's card is authorized at quote acceptance but not charged until the job is complete and the 72-hour dispute window has closed.
• Evergrn holds the funds for 72 hours after the provider marks the job COMPLETED.
• If no dispute is filed, funds are released in the next morning's daily 8 AM batch payout.
• If a dispute is filed within 72 hours, funds are captured to Evergrn but the provider payout is blocked until admin resolves the dispute manually.
• Provider payouts are tracked in an internal ledger (ProviderPayout table). Actual transfers are made manually (Stripe Dashboard or ACH) on a per-batch basis. Stripe Connect is not used for MVP.

Payment lifecycle (state machine)

Quote accepted
    │
    ▼
Stripe PaymentIntent created (capture_method: 'manual')
Payment.status = PENDING
    │
Job marked COMPLETED by provider
    │
    ▼
Payment.status = HELD
Payment.releaseAt = completedAt + 72 hours
    │
    ├─── Customer files JobReport within 72h ──────────────────────────────┐
    │                                                                       │
    │         8 AM daily cron runs                                          │
    │              │                                                        │
    │    releaseAt <= today 8 AM?                                           │
    │         NO → skip (will be picked up at tomorrow's 8 AM batch)       │
    │         YES → JobReport exists?                                       │
    │                   YES ──────────────────────────────────────────────►│
    │                   NO                                                  │
    │                    │                                                  ▼
    │           stripe.paymentIntents.capture()              Payment.status = DISPUTED
    │           Payment.status = PAID                        ProviderPayout NOT created
    │           ProviderPayout created (status=PENDING)      Flagged in GodMode for admin
    │           batchDate = today 8 AM                       Admin resolves manually:
    │                                                          - capture + create payout, OR
    ▼                                                          - refund customer
End

Batch payout timing rules

The cron runs once daily at 8:00 AM local server time.

A payment is included in a given day's batch if and only if:

Payment.releaseAt <= today at 08:00:00

If a job is completed at 10:00 AM on Monday, releaseAt = Thursday 10:00 AM. The Thursday 8 AM batch does not include it (10 AM > 8 AM). It is picked up by the Friday 8 AM batch. This means the effective hold is between 72 and ~96 hours depending on time of completion — always at least 72h, never more than 96h.

Completed at	releaseAt	Paid out at
Monday 6:00 AM	Thursday 6:00 AM	Thursday 8 AM ✓ (6 AM < 8 AM)
Monday 10:00 AM	Thursday 10:00 AM	Friday 8 AM (10 AM > 8 AM)
Monday 11:59 PM	Thursday 11:59 PM	Friday 8 AM

Provider payout split

The Stripe PaymentIntent is for totalAmount (provider net + 18% platform fee). When the cron captures it:

totalAmount   = quote.totalAmount        → charged to customer's card → Evergrn bank account
providerShare = quote.amount             → owed to provider (recorded in ProviderPayout)
platformShare = quote.platformFee        → retained by Evergrn

The ProviderPayout record is created with status = PENDING. A human reviews the daily batch in GodMode and initiates the ACH transfer or Stripe Dashboard transfer to the provider. Once confirmed, ProviderPayout.status is set to PAID and paidAt is recorded.

What needs to be built (implementation checklist)

• Prisma migration: add releaseAt DateTime? to Payment; add HELD and DISPUTED to PaymentStatus enum; add ProviderPayout model and ProviderPayoutStatus enum
• Remove immediate capture: delete stripe.paymentIntents.capture() from POST /jobs/:id/complete and PATCH /jobs/:id/status; set Payment.status = HELD and Payment.releaseAt = now + 72h instead
• Cron job (src/jobs/payoutCron.js using node-cron): schedule 0 8 * * *; query Payment WHERE status=HELD AND releaseAt <= now; for each — check JobReport; if clean → capture + create ProviderPayout; if disputed → set DISPUTED
• GodMode payout dashboard: list today's ProviderPayout records (PENDING), show provider name + amount + job; button to mark PAID after manual transfer
• GodMode disputed payments view: list Payment WHERE status=DISPUTED; admin actions: release to provider, or refund customer via stripe.refunds.create()
• Stripe PaymentIntent authorization window: Stripe holds a manual-capture PaymentIntent for 7 days before it expires. If a job is completed and no action is taken before the 7-day window, the auth expires and capture fails silently. The cron must handle this edge case — if capture fails with payment_intent_unexpected_state, mark FAILED and alert admin.

Files to create/modify

src/jobs/
└── payoutCron.js          node-cron job — runs at 8 AM daily

src/routes/
├── jobs.js                remove capture calls; set HELD + releaseAt on completion
└── admin.js               add payout dashboard endpoints [GODMODE]

prisma/
└── schema.prisma          Payment (add releaseAt, new statuses); ProviderPayout model