Global Constructions & Realtors — Rebuild Architecture (Step 2)

0Decisions resolved up front reviewer fixes applied

These ten decisions are binding for the whole document; every later section conforms to them. They resolve the cross-section contradictions the reviewer caught.

1System Architecture

GCR is a lead-first portal: read-heavy, ~500 listings, no AI/video compute. Server-first (RSC) with selective client islands, Payload CMS 3 inside the same Next.js 16 process, Postgres, media on Garage S3.

Architecture / data-flow diagram

                          Cloudflare (orange-cloud)
                   HTML: uncached · static assets: cached at edge
                   + cache-purge API hit on content change (D10)
                                   │
                                   ▼
            Traefik v3.6 (coolify-proxy) · Let's Encrypt
                                   │
        ┌──────────────────────────┴───────────────────────────┐
        │   Coolify App "globalrealtor"  (Node 22-alpine)        │
        │   Next.js 16 (standalone, Turbopack) + Payload 3.84    │
        │  (frontend)  RSC pages ──┐        ┌── (payload) /admin │
        │  proxy.ts (308 redirects)│        │   REST · GraphQL    │
        │                          ▼        ▼                     │
        │            getPayload() Local API · React.cache         │
        └───────┬───────────────────────────────┬───────────────┘
                │                                 │
        Postgres (pgvector/pg16)          Garage S3  s3.csoul.cloud
        globalrealtor-db                  bucket globalrealtor-prod
        localproxy 127.0.0.1:5434         (forcePathStyle, region "garage")
                │
        prodMigrations on boot           (Redis: NOT v1 — add a DB index
        (push:true is a prod no-op)       only when notifications need a queue)

Request trace — /north-bangalore/hennur/lvs-lavender-3bhk

1. Cloudflare edge → MISS on HTML (uncached) → origin
2. proxy.ts checks the cached redirect map → miss → pass through
3. Router: not a reserved literal → [...path]/page.tsx (3 segments)
4. generateMetadata + body both call resolvePath(path)  (React.cache → ONE execution)
   length 3 → property lookup w/ locality+region constraint + publishedPropertyWhere() → kind:'property'
5. Render detail + inject RealEstateListing + BreadcrumbList JSON-LD
6. Cached with tags property:<id> ; served via ISR
7. Later admin edit → revalidateTag('property:<id>') + listings:locality:<id> + CF purge (D10)

Stack & rendering strategy

• Next.js 16.2 (App Router, output:"standalone", Turbopack), React 19. Middleware is src/proxy.ts; params/searchParams/cookies()/headers() are async; admin under src/app/(payload)/.
• Payload CMS 3.84 — db-postgres, richtext-lexical, storage-s3, sharp.
• Tailwind v4, Lucide React, Framer Motion. Brand green #00b74a / orange #ff9800; Poppins + Inter via next/font (self-hosted).
• Node 22-alpine, 3-stage Dockerfile with npm ci --include=dev (Coolify injects NODE_ENV=production which otherwise drops devDeps and breaks the build).

Hybrid SSG + ISR + tag revalidation; only /find-property and sitemaps are force-dynamic.

Infra

Co-host on the CreatiSoul Coolify VPS (62.72.56.130, Coolify v4, Traefik v3.6, Garage v2.1). New Coolify App globalrealtor + own Postgres globalrealtor-db + host socat localproxy on 127.0.0.1:5434 + dedicated Garage bucket globalrealtor-prod. No Redis for v1. Schema via prodMigrations (on boot; push:true is a prod no-op). Healthcheck GET http://127.0.0.1:3000/admin (IPv4). Marginal cost ≈ $0/mo.

2Payload CMS Structure

Cross-cutting conventions

• Slug fields: text, required, index + a shared formatSlug hook. Property.slug is not unique — uniqueness is the composite (region, locality, slug) (D6). Other slugs stay single-column unique.
• Status (D1): every public collection uses a plain status select + publishedAt-backfill hook. No versions/_status/trash anywhere.

// src/access/index.ts
export const isOwner: Access = ({ req }) => roleOf(req.user) === 'owner'
export const isStaff: Access = ({ req }) => ['owner','manager'].includes(roleOf(req.user) ?? '')
export const readPublishedOrStaff: Access = ({ req }) =>
  req.user ? true : publishedPropertyWhere() // anon → published-only

2.1 The canonical visibility function (D2)

// src/lib/property-query.ts — the ONE source of truth
export const VISIBLE_STATUSES = ['available','booked','sold','ongoing'] as const
export function publishedPropertyWhere(extra?: Where): Where {
  const base = { and: [
    { status: { in: [...VISIBLE_STATUSES] } },           // draft → 404
    { publishedAt: { less_than_equal: new Date().toISOString() } },
  ] }
  return extra ? { and: [base, extra] } : base
}

Product rule: sold/booked stay at HTTP 200 with a status badge (preserves backlinks), may carry noindex via the per-listing toggle. Every front-end and collection-builder where-clause calls this function; the old inline _status: published and status in ['available','booked'] variants are deleted.

2.2 Property — tabs & conditional logic

Tabs: Listing · Pricing · Specs · Amenities · Location · Media · SEO & Migration. admin.condition(data) keyed on type/purpose mirrors the mockup's data-show-for / data-show-for-purpose.

Pricing (conditional on purpose)

// SALE
{ name: 'price', type: 'number', admin: { condition: (d) => d?.purpose === 'sale' } }
{ name: 'priceOnRequest', type: 'checkbox' }   // migration sets for "Negotiable"/"Call"
{ name: 'pricePerSqft', type: 'number', admin: { readOnly: true } }  // display/filter only — NOT a sort (D8)
// RENT / LEASE / PG
{ name: 'monthlyRent', admin: { condition: (d) => ['rent','lease','pg'].includes(d?.purpose) } }
{ name: 'deposit' }, { name: 'maintenance' }
// PG-only
{ name: 'sharingType' }, { name: 'preferredTenants', hasMany: true }

Specs — reviewer completeness fixes applied

// BUILT-UNIT GROUP (apartment|serviced|house|villa)
unit: { bedrooms, bathrooms, furnishing, facing, propertyAge, availability,
        transaction, ownership, areaSqft /*built-up*/, carpetAreaSqft /*ADDED, mockup*/ }
floor / totalFloors      // apartment|serviced only

// POSSESSION — select group, NOT a free date (D-fix, mockup is a SELECT)
possession: { state: 'immediate'|'3m'|'6m'|'dated', possessionDate? (when dated) }

// PLOT GROUP (plot|bda) — reviewer fixes:
plot: { plotType: 'residential'|'commercial'|'agricultural',  // ADDED
        plotDimensions, plotAreaSqft, roadWidth, cornerPlot,
        facing: 8-dirs + 'corner',                       // 'corner' ADDED
        khata: 'A'|'B'|'E',                          // E-Khata ADDED
        brand: 'none'|'BDA' }
bdaSanctionNo  // bda only
bdaVerified: checkbox (default false)  // ADDED — gates the "BDA Approved" badge truthfully

Full type×purpose matrix re-walked: PG fields show for any built type incl. independent-house PG; monthlyRent shows for plot+rent/lease (rare but legal); plots have no BHK/floor/amenities; serviced+pg and villa+pg valid.

Location (nested group — D4)

location: { region (rel 'locations', kind=region), locality (rel 'locations', kind=locality, parent=region),
            street, city (default Bangalore), pincode,
            geo: 'point'  // [lng,lat] — single source for JSON-LD + map pin,
            nearby[]: { kind, name, distanceKm } }

Amenities = fixed select hasMany of the 12 (built-units only); PropertyType = the type enum + a static config/propertyTypes.ts. Both are closed lists — collections rejected (editable labels would desync from admin.condition strings and break URL preservation).

SEO & Migration tab: metaTitle, metaDescription, ogImage, noindex, legacyNodeId (unique), legacyAliases[] (each → 308 Redirect).

2.3 Locations — ONE self-referencing collection (D3)

slug: 'locations'; access: { read: allowPublic, create/update: isStaff, delete: isOwner }
fields: kind (region|locality), name, slug (unique),
        parent (rel 'locations', kind=region, shown when kind=locality),
        intro, connectivity[], geo (point), heroImage, legacyTermId (unique), legacyAliases[]

Integrity guard: a region has no parent; a locality must have a region parent. Seed 6 regions + 70+ localities. Compound index (parent, slug).

2.4 CollectionPage builder (replaces D7 Views)

Tabs: Page · Query · SEO · Legacy URLs. All relationTo are 'locations' (D5). purposes/types/bhk are select hasMany closed enums.

Query tab: locationScope (all-bangalore|region|area|areas) → region | areas[] (conditional),
           purposes[], types[], priceMin/Max, bhk[], featuredOnly,
           defaultSort: featured|newest|price-asc|price-desc|area   // psf DROPPED (D8),
           featuredOrder[] (pin to top)
SEO tab:   isIndexable (master), indexable (cached boolean §4), metaTitle/desc, canonicalUrl, ogImage

One resolution engine — whereFromCollectionPage() — is called by both the renderer and the admin live preview, so the count preview equals what visitors see. It intersects with publishedPropertyWhere() (D2) and uses dotted-path location clauses (D4).

Price purpose-aware (sale→price, rent-like→monthlyRent, mixed→suppressed + warning). BHK 5 = "4+". Live preview endpoint /api/collection-pages/preview runs the same builder (count + 5-row sample + indexability chip + warnings).

2.5–2.10 Requirement · Service · Media · Redirect · Users · SiteSettings

• Requirement (requirements): create: denyAll (D9). kind (requirement|enquiry|alert) + intent; conditional lookingFor/haveProperty groups; triage (status, assignedTo, internalNotes, priority); provenance (sourcePage, utm, ipHash salted, consent/consentAt); notify audit. afterChange → dispatchNotification.
• Service (services): title, slug, summary, icon, hero/vaseem images, body, features[], processSteps[], faqs[], order, status select + publishedAt, SEO. delete: isOwner.
• Media (media): S3/Garage via storage-s3 (bucket globalrealtor-prod, forcePathStyle, region "garage"); sizes thumbnail/card/feature/og; alt required, legacyFid (unique), sha256 (dedup). No local volume.
• Redirect (redirects): owner-only; from (unique), to, type default 308 (D7), gone (spam → 410). afterChange → revalidateTag('redirects') busts the proxy map.
• Users (auth): owner|manager, field-level role access (no self-escalation), 8h tokens, lockout. Admin hardening: Cloudflare Access + 2FA for owner, Redis-rate-limited login, configured forgot-password provider, rotate all D7-era creds.
• SiteSettings (global): read: allowPublic, update: isOwner. Tabs Contact / Social / Homepage / Channel Partners / Navigation / Leads&Notifications / SEO Defaults (incl. minIndexableResults default 3).

2.11 Roles & access — the no-delete guarantee (D1-corrected)

SiteSettings / Users / Redirects = owner-only (resolves the brief's open question — bar Manager from site-config: yes). System nav items use admin.hidden for managers (UX); access is the real enforcement. Reports = owner-only /admin/reports.

3Drupal-7 Migration Plan

Two-stage pipeline with a stable JSON intermediate, idempotent and re-runnable.

[D7 MySQL] --(1 extract)--> [normalized JSON snapshot + media blobs] --(2 import)--> [Payload Local API → Postgres + Garage S3]
 read-only copy             /migration/snapshot/*.json                                idempotent upsert by legacy* keys

• Stage 1 (extract): Node mysql2 against a read-only mysqldump restore (never production — zero PHP execution on a hacked site). Self-discovering via field_config/field_config_instance — captures everything; unmapped → _raw. Measure file_managed.filesize here to size the Garage bump.
• Stage 1.5 (transform): clean + spam-filter + taxonomy-map + URL-map → import-ready.json.
• Stage 2 (import): Payload Local API, upsert by legacyNodeId/legacyTermId/legacyFid.

D7 field machine names are inferred from the brief + mockups. The extractor prints the discovered field_config list — treat any mismatch as an open question, not a guess.

Field mapping (Property, abridged)

Taxonomy: category→type, location→locations (parent=0 → region; child → locality+parent), brand→plot.brand, amenities→12-key synonym map. Spam exclusion = WHITELIST: content-type gate + required-valid-fields + heuristic score (pharma/casino regex, outbound-link count) + explicit known-bad list (/node/4204); every exclusion → excluded.jsonl.

URL preservation — 308 permanent (D7)

Every live non-spam alias keeps working: served natively at the identical path, or a 308 (Google == 301). Property paths byte-identical (composite-unique slug makes this possible even when tail slugs collide).

• Property: composed /region/locality/slug; equals legacy → native, else 308. Diff assertion flags mismatches (must be zero non-redirected before cutover).
• Collection aliases (D7 Views) → seed one CollectionPage per legacy URL (slug = exact path, managedSource:'migrated'). Migrated + hand-built share one renderer/sitemap.
• Static verbatim; /contact-us → 308 /contact. /node/NNNN → mapped path; hacked nodes gone:true → 410.

Importer: npm scripts d7:extract / transform / import / import:dry / validate; dependency order Locations → Media → Properties → Services → CollectionPages → Redirects → SiteSettings; { context:{ skipRevalidate:true } } during bulk load; batch-50 + checkpoint resumability; schema (incl. composite index) via migrate:create → prodMigrations.

Validation gate (report.md): aliases not covered by a native route or redirect = MUST be zero; URL-parity mismatches = zero non-redirected; plus counts (imported / excluded / quarantined / media / redirects) and integrity checks.

Cutover & rollback

Staging at gr.csoul.cloud (indexing blocked): extract → transform (review with Vaseem) → import:dry → import → validate (zero uncovered aliases) → manual QA → Screaming Frog crawl. Cutover (D7 stays live on legacy.): freeze → fresh dump → re-run (idempotent) → add prod domains → activate proxy map → smoke-test top redirects (accept 308-or-301 → 200) → submit new + legacy sitemaps.

Post-cutover SEO (weeks 1–8): GSC Coverage / URL Inspection; daily redirect test asserting 301-or-308 → 200 (no chains/loops); 404 logging → add redirects; baseline + weekly clicks/impressions on top 50 URLs; Rich Results Test on JSON-LD.

4Thin / duplicate-content control (cached & stable)

Index a CollectionPage when isIndexable AND result count ≥ minIndexableResults (default 3). Reviewer fix: do NOT count live in the force-dynamic sitemap (an N-query fan-out that can 500). Instead:

• Store denormalized liveResultCount + indexable boolean per CollectionPage, recomputed by a tag-revalidated job whenever a matching Property changes (we already bump listings* tags) and in the page's own afterChange.
• The sitemap filters on the stored indexable boolean — one indexed query, cheap and stable.
• Render-time noindex stays as a safety net but reads the cached count.
• Hysteresis: only flip to noindex after the count is below the minimum for a sustained period (avoids index thrash).

Canonical self by default; canonicalUrl folds near-duplicates; ?sort=/?page= never in the canonical; pages 2+ noindex,follow. Authoring guards: slug-collision hard-block (incl. reserved + locality shapes) + soft duplicate-criteria warning. Unique intro rich text is the positive lever against thinness.

5Front-end routing & search

Two route groups: (payload) (admin + REST/GraphQL) and (frontend). Reserved literal folders (matched before the catch-all): find-property, compare, post-requirement, company-profile, contact, services/[serviceSlug]. Everything else → [...path]/page.tsx catch-all resolver.

Segment resolution (resolvePath, React.cache-wrapped, ≤3 DB queries)

Redirect status (D7): hot/known aliases handled in proxy.ts via NextResponse.redirect(to, 308), loading the map through a revalidateTag('redirects')-cached server function (not module-eval TTL — reflects slug changes immediately). Static legacy set can also compile into next.config redirects. RSC permanentRedirect (308) is the safety net. proxy.ts + segmented sitemaps are NEW build items — de-risked by an early spike (Phase 0).

Search (/find-property, force-dynamic)

URL = state; typed parseSearchParams whitelists every param. buildPropertyQuery → Payload where ∩ publishedPropertyWhere() (D2), dotted-path location (D4), purpose-aware price. Sort exactly matches the mockup (D8): Relevance · Price↑ · Price↓ · Newest · Area — no psf. limit=12; facet counts via a single Drizzle GROUP BY cached with tag listings. Map = lazy MapLibre island (view=map only). Compare = localStorage store (max 4) mounted as a layout island; /compare?ids= server-resolves opaque ids, SSR'd, noindex.

6SEO infrastructure

• Sitemaps: generateSitemaps() index → properties / localities / collections (cached indexable filter) / services / static, all force-dynamic + try/catch. /find-property + /compare excluded.
• robots.txt: Disallow /admin, /api, /compare, /find-property?*.
• Canonical/noindex: entity pages self-canonical; /find-property noindex,follow on any filter param; high-value combos become real indexable CollectionPages.
• JSON-LD: layout = RealEstateAgent (GCR, Vaseem Khan, founded 1995) + WebSite SearchAction; Property = RealEstateListing (price/floorSize from unit.areaSqft, rooms from unit.bedrooms, geo from location.geo); Locality/Region = Place; CollectionPage = CollectionPage + ItemList; Service = Service; FAQ pages = FAQPage; non-home = BreadcrumbList.
• CWV: next/image remotePatterns for s3.csoul.cloud; fixed aspect-ratios (no CLS); next/font Poppins/Inter (kills render-blocking Google Fonts link); ~5 client islands.

The mockup's "898 of 898" count is illustrative placeholder — the brief says ~500 properties. Do not use 898 as a seed/QA acceptance target.

7Leads, notifications & reports

Three surfaces, one Server Action (submitRequirement, 'use server'): (a) /post-requirement (intent-conditional); (b) property-detail enquiry card + tel:/wa.me primary conversions; (c) "Alert me" save-search (v1 store + manual match; automated matcher deferred).

Submission path (D9): requirements.create = denyAll; the action is the sole ingress, writing via Local API overrideAccess after honeypot → time-trap → ipHash → Redis rate-limit (falls open if Redis down) → Turnstile (config-gated) → zod → create → afterChange dispatch. ('use server' files export only async — keep zod/types in a sibling constants.ts.)

Notifications: Resend for v1 email (fallback Google Workspace SMTP, swappable behind config); recipients from SiteSettings; dispatchNotification() indirection so a BullMQ queue swap is one line. WhatsApp v1 = wa.me click-to-chat deep links; later = BullMQ notify_whatsapp via WhatsApp Cloud API (deferred). Idempotent (key on requirementId + channel); try/catch'd (never rejects the lead write).

Inbox: Payload list view + native filters; status workflow new→contacted→qualified→site-visit→closed-won/lost + spam; assignedTo; internalNotes timeline. Reports: owner-only /admin/reports — leads over time, by intent (buy/rent/sell/rentout), by source/UTM, by status (conversion), popular localities, listing counts, "available with zero enquiries".

PII/DPDP: explicit consent + consentAt; ipHash never raw IP; leads staff-read-only; 404 (not 403) for unauthorized; retention sweep designed-for but deferred; owner-delete = right-to-erasure.

8Phased build roadmap migration-first

9Open questions to confirm with the owner

1. Sold/booked visibility & indexing: confirm they stay live (200) with a badge for SEO equity; should sold be noindex? (Recommended: stay live; noindex optional.)
2. ₹/sq.ft sort: mockup has none (D8 dropped it). Add a psf sort as a new product decision, or leave out? (Derived pricePerSqft kept regardless.)
3. Shared vs dedicated host: confirm co-hosting on the CreatiSoul VPS (shares kernel/Traefik/Coolify — a host incident affects all three sites).
4. Email provider: Resend (recommended) vs the client's Google Workspace SMTP? From-address + notification recipients (Vaseem + office)?
5. BDA verification source: start imported BDA listings bdaVerified=false (badge hidden), or map a D7 verification field? (Badge must never show unverified — liability.)
6. Canonical host: apex or www (match D7)? /contact-us → 308 /contact acceptable?
7. Cloudflare control: do we have CF access for the DNS flip, ACME/grey-cloud step, and the cache-purge token (D10)?
8. D7 access: read-only mysqldump + sites/default/files/ + the full live URL list (sitemap + GA/GSC) for migration + the parity gate?
9. D7 field names: confirm the inferred mapping against the extractor's discovered field_config. Does D7 track per-listing featured/agent/BDA-verified data to preserve?
10. Lead routing & auto-reply: route enquiries vs sell-leads differently? Enable the confirmation email to the lead (consent implication)?
11. Manager scope: confirm Manager is barred from SiteSettings/Users/Redirects and has no delete anywhere. Future agent/broker roles?
12. Privacy / DPDP: privacy-policy content (linked from consent) + retention window (N months for closed-lost/spam)?
13. Compare & alerts v1: is automated "new matching listing → notify lead" needed at launch, or is the deferred manual-match alert acceptable?