YPN USA App (app.ypnus.com)

Product app for mortgage loan officers (MLOs): exclusive ZIP-code territories and an always-on AI agent that captures, qualifies, routes, and nurtures every borrower.

Host	Role
ypnus.com	WordPress marketing, LO signup, Cerebro, SEO content
app.ypnus.com	This Next.js app (territory checker, intake demo, analytics)

Built with Next.js 16 (App Router, Turbopack), React 19, and Tailwind CSS v4.

Hostinger restore files for the currently-broken app homepage live in hostinger/.

What's inside

Marketing site (/) — a full conversion-focused landing page:

• Hero with a live ZIP territory availability checker (real scarcity → real reason to subscribe)
• Autonomous-agent capabilities + a 3-step "ZIP code → pipeline" explainer
• Exclusive territory reservation flow (checks availability, then captures the officer)
• Ownership / portability section — keep your leads and site if you switch brokerages
• Predictive life-event intelligence (probate / divorce / marriage signals)
• An interactive mortgage payment calculator
• Freemium pricing (Free → Pro MLO → Brokerage), FAQ, and CTAs

Working product demo:

• /embed/intake — the borrower intake assistant in an iframe-friendly surface (embed on any MLO site)
• The same assistant runs inline in the homepage "Live demo" section
• /portal/nurture — urgency-ranked MLO borrower queue with search, program/state filters, outreach, and appointment visibility
• /tools/equity — private, borrower-entered home-equity snapshot with optional consented MLO review
• /mortgage-broker/[city]-[state] and /zip/[zipcode] — curated, source-aware local SEO territories (unknown locations 404 rather than generating thin pages)
• /dashboard/local-seo — MLO NAP, Google Business Profile, review-feed, and review-link readiness

Backend (App Router route handlers):

• POST /api/intake/tick — conversational intake engine (short shared goal/amount/timeline/credit/contact flow across all loan programs, scoring, CRM mirroring, officer routing, nurture scheduling)
• GET /api/territory/check?zip=NNNNN — ZIP territory availability
• POST /api/demo-request — officer territory reservation / waitlist capture
• POST /api/property/evaluate — server-validated equity estimate and optional consented review request
• GET /api/calendar/slots, POST /api/calendar/book — consultation booking
• POST /api/automation/process — processes due nurture follow-ups
• GET /api/analytics/summary — intake telemetry (also rendered at /analytics)
• POST /api/reviews/request — accepts an authenticated closing event and hands an honest Google review request to the configured SMS/email delivery webhook
• GET /local-seo-sitemap.xml — small sitemap containing only curated local territories

Getting started

npm install
cp .env.example .env.local   # optional; sensible defaults work out of the box
npm run dev                  # http://localhost:3000

Production:

npm run build
npm run start

Configuration

All environment variables are optional — see .env.example.

Variable	Purpose
NEXT_PUBLIC_SITE_URL	Product app URL for SEO/canonical/sitemap. Defaults to https://app.ypnus.com.
NEXT_PUBLIC_MARKETING_SITE_URL	WordPress marketing host. Defaults to https://ypnus.com.
YPNUS_WP_API_BASE	Live territory/signup REST base. Defaults to https://ypnus.com/wp-json/ypnus/v1.
LOANPILOT_DATA_DIR	Directory for the JSON data snapshot. Defaults to ./data. Point at a writable path (e.g. /tmp/ypnus) on read-only hosts.
SESSION_SECRET	Signs the ypnus_session cookie. Falls back to a secret persisted at <data dir>/session-secret.key when unset — fine for local dev, but set this explicitly in production.
YPNUS_SSO_SHARED_SECRET	Shared secret for the ypnus.com → app.ypnus.com SSO handoff. Required for /api/auth/callback to accept a handoff; see docs/sso-handoff.md.
INTAKE_EXTERNAL_WEBHOOK_URL	If set, completed intakes are POSTed here (Zapier/CRM).
LOANPILOT_DEMO_MODE / LOANPILOT_DEMO_DAY_MINUTES	Compress the multi-day nurture ladder for live demos.
LOCAL_SEO_PUBLIC_ORIGIN	Public origin for local canonical URLs; defaults to https://ypnus.com.
MLO_PUBLIC_* / MLO_NMLS_ID	Co-branded public NAP and license fields. Omit a non-public office address.
GBP_PLACE_ID / GBP_PROFILE_URL	Verified Place ID for review links and public GBP listing URL.
GBP_REVIEWS_PROVIDER_URL / GBP_REVIEWS_PROVIDER_TOKEN	Authorized server-side source for dynamic verified review records.
NEXT_PUBLIC_GOOGLE_MAPS_EMBED_KEY	Optional browser-restricted key for lazy map embeds.
REVIEW_REQUEST_API_SECRET	Bearer secret required by the closing-event endpoint in production.

Local SEO deployment

The Next.js service is hosted at app.ypnus.com, while the requested local pages are intended for ypnus.com. Before indexing, configure WordPress/Hostinger to reverse-proxy these paths to this app:

• /mortgage-broker/*
• /zip/*
• /local-seo-sitemap.xml

Then add https://ypnus.com/local-seo-sitemap.xml to the marketing site's sitemap index or Google Search Console. Do not submit the app-hosted sitemap as a substitute for that marketing-host route.

Location pages are intentionally registry-backed. Add a distinct profile with original copy, neighborhoods, municipal sources, and dated metric sources before a city or ZIP is generated. Reviews are omitted from both the page and JSON-LD until a configured provider returns valid records; no sample testimonials or ratings ship in production. FinancialService / MortgageBroker JSON-LD is emitted only when both MLO_PUBLIC_NAME and MLO_NMLS_ID are configured; otherwise the page uses neutral WebPage structured data.

Data & persistence

State (sessions, leads, CRM notes, territory reservations, analytics) is held in an in-memory store that is hydrated from and written through to a JSON snapshot on a best-effort basis. On a persistent Node host (next start, a VPS, Docker, Hostinger Cloud, Render) the JSON snapshot survives restarts. For durable multi-instance production data, swap the storage layer in src/lib/db.ts for a database (Supabase, Postgres, etc.); a starter schema is in supabase-leads-schema.sql.

Deploy

Hostinger Cloud (recommended)

Production shape: WordPress marketing on ypnus.com, this Next.js product app on app.ypnus.com as a Hostinger Cloud Node.js web app. Full checklist: hostinger/README.md.

Deploys go through GitHub: merge to main, .github/workflows/release-build.yml publishes release app-build-<sha7>, then run scripts/hostinger-install-release.sh on the server. It verifies the checksum, keeps the previous release, and rolls back automatically if /api/health doesn't report the new commit. Never deploy through hPanel's Node.js Deploy/Rebuild or Hostinger's Node.js Builds API.

Render

A render.yaml blueprint is included for a persistent Node host:

1. At dashboard.render.com: New + → Blueprint.
2. Connect the dave4079111/ypnusa repo and click Apply.
3. Set NEXT_PUBLIC_SITE_URL in the service's Environment tab.

Any Node host (VPS / Docker)

npm ci
npm run build
NEXT_PUBLIC_SITE_URL=https://your-domain npm run start   # honors $PORT

Put it behind a reverse proxy (nginx/Caddy) and process manager (PM2/systemd). The default ./data directory is writable here, so lead data persists across restarts.

Project layout

src/
  app/                     App Router pages, API routes, sitemap.ts, robots.ts
    page.tsx               Marketing homepage
    analytics/             Intake telemetry dashboard
    embed/intake/          Iframe-friendly borrower assistant
    api/                   Route handlers (intake, territory, demo-request, calendar, …)
  components/              Marketing sections, territory checker, calculator, chat assistant
  lib/                     Intake engine, qualification, CRM, automation, territory, storage