Current Architecture

PropertyGenome runs as a score-led product stack across Next.js, FastAPI, PostgreSQL, and provider-backed enrichment.

The current codebase is organized so the web app handles product experience and workflow orchestration, while the Python backend handles property intelligence workloads. Together they support scoring, discovery, Deal Tracker, billing, admin operations, and PGASK guidance.

System Layers

Four layers working together

Next.js Application

The customer-facing layer handles marketing pages, authenticated product pages, and application APIs for auth, billing, reports, Deal Tracker, admin, and concierge workflows.

  • App Router pages
  • Route handlers
  • Billing, auth, Deal Tracker, admin settings
  • Provider-compliance enforcement

FastAPI Intelligence Backend

The Python backend owns score generation, valuation orchestration, address validation, county enrichment, forecast hooks, and citywide opportunity pipelines.

  • Realtime score engine
  • Valuation and county enrichment
  • Undervalued homes pipeline
  • Forecast and AI/ML hooks

PostgreSQL Data Layer

PostgreSQL stores the operational system of record for users, reports, alerts, deals, and parts of the nationwide score persistence layer.

  • users
  • reports
  • alerts
  • deal_tracker_items
  • subject_properties and genome_score_runs

External Providers

PropertyGenome connects to provider services for address validation, valuation, parcel enrichment, maps, billing, AI assistance, and OAuth login where configured.

  • USPS, RentCast, Regrid
  • County / NC OneMap / Mecklenburg
  • Mapbox
  • Stripe, OpenAI, Google OAuth
Operating Loop

How the product moves from visitor to workflow

1. Attract and Route

Visitors enter through the homepage, product pages, pricing, or PGASK. The public site pushes them toward scoring, discovery, or plan evaluation.

2. Score and Explain

Analyzer requests go through Next.js into FastAPI, which returns score, valuation, property profile, market context, and provider-aware confidence messaging.

3. Save and Track

Users can persist reports to dashboard history and move promising properties into Deal Tracker for notes, reminders, outreach, and offer tracking.

4. Convert and Govern

Billing upgrades users into higher plans, while admin controls manage pricing, provider policy, and concierge-lead follow-up behind the scenes.

Current Architecture Principles

What the current code optimizes for

  • Graceful fallback when scoring, billing, or concierge dependencies are unavailable
  • Plan-aware feature access from both page and API layers
  • Operational persistence in PostgreSQL for users, reports, alerts, and Deal Tracker
  • Provider-aware data handling with compliance controls for persistence, cache, and exports
  • A product model that connects scoring, discovery, workflow, and monetization instead of treating them as separate apps