ADU Directory V2
— filter-first comparison engine

The single most important diagram for V2. Build Leads consistently assume V2 is a separate product on its own infrastructure. It isn't. V2 is an additional frontend on top of the same Mac mini, the same agent fleet, the same builder catalog, the same Stripe Connect account.

Three primary filters drive all V2 traffic. Each is geographic-aware, real-time, and deep-linkable. "All Home Types" is mutually exclusive with the others — selecting it clears the rest.

Every filter change triggers this pipeline. Meilisearch is the index; Postgres is the source of truth. Never query Postgres directly for filter results — too slow at scale.

Every cell below becomes a unique SEO landing page at /builders/[home-type]/[state]. Each page is auto-generated by the Marketer Agent — pre-loaded filter set, ranked builders, state-specific regulations (e.g. SB 543 for the California column), permit timelines, financing notes. Page regenerates whenever new builders are added.

V2 adds five fields to the existing Builder + Model records. Builders with incomplete V2 data show in V1 catalog browsing only — they're invisible to the filter engine until they complete states_delivered and home_types_offered.

Operationally identical to V1's architecture except Meilisearch is added as a search index layer on the Mac mini. WordPress remains the CMS for content (state guides, articles); Meilisearch is the index for builder filter queries. Postgres remains source of truth.

Same 5 agents as V1. New skills called out below in monospace. Engineer Agent does the heaviest V2 lift (filter logic + landing page generation); Marketer Agent benefits from zero-result analytics as a builder-acquisition signal.

Same as V1. V2-specific change: Saved Searches use a magic-link account-lite pattern (email-only, no password) — leverages the existing Email channel for the magic links and digest cadence.

V2 is built in parallel with V1. Phase 1 prioritizes schema migration + Meilisearch + the filter MVP. Phase 4 is the decision point: retire V1, retire V2, or run both for different segments.

Eight V2-specific risks. R7 (mobile filter UX) and R4 (zero-result frustration) are the highest-likelihood — both UX failure modes that erode trust fast. R1 (filter latency) and R5 (duplicate-content SEO penalty) are the existential ones. All V1 risks still apply on top.

V1 schema extended with new fields on Builder + Model (see §06) and three brand-new entities: SavedSearch, FilterAnalyticsEvent, and LandingPage.

erDiagram
    BUILDER ||--o{ MODEL : "lists"
    BUILDER ||--o{ LEAD_ROUTING : "receives"
    INQUIRY ||--o{ LEAD_ROUTING : "fans out to"
    SAVED_SEARCH }o..o| BUILDER : "matches"
    FILTER_ANALYTICS_EVENT }o..o{ BUILDER : "surfaced"
    LANDING_PAGE }o..o{ BUILDER : "showcases"

    BUILDER {
        uuid id PK
        string business_name
        text_array states_delivered
        text_array states_operating_from
        enum_array home_types_offered
        int delivery_radius_miles
        jsonb exclusivity_zones
        enum payment_tier
        bool verified
    }
    MODEL {
        uuid id PK
        uuid builder_id FK
        enum home_type
        text_array deliverable_states
        int sqft
        int price_starting
        int lead_time_weeks
    }
    INQUIRY {
        uuid id PK
        jsonb homeowner_contact
        string state
        enum_array selected_home_types
        int quality_score
        enum status
    }
    LEAD_ROUTING {
        uuid id PK
        uuid inquiry_id FK
        uuid builder_id FK
        int charged_amount_cents
        enum outcome
    }
    SAVED_SEARCH {
        uuid id PK
        string user_email
        jsonb filter_state
        enum notification_cadence "weekly|monthly|off"
        timestamp last_notified_at
    }
    FILTER_ANALYTICS_EVENT {
        uuid id PK
        uuid session_id
        jsonb filter_state
        int result_count
        int inquiries_sent
        text user_agent
        text utm_source
    }
    LANDING_PAGE {
        uuid id PK
        string url_slug
        enum home_type
        string state
        text generated_content
        timestamp last_regenerated_at
        int serp_rank_current
        int traffic_30d
        int inquiries_30d
    }

The V1 Build Lead onboarding (7-day) applies fully — V2 layers on top. These six weeks describe the V2-specific build sequence Engineer Agent runs after the standard Hatchstacks Pro stack is up.

V2 inherits V1's relationships (same builders, same SEO content engine). Adds one notable share: Meilisearch infrastructure is reusable for Vacation Rental host search and Network for Creators creator search.

V2-specific terms. All V1 terms (Builder, Model, Inquiry, LeadRouting, Verified badge, PPL, Featured, Exclusivity, FacetWP) still apply.

V1 catalog-first

The original version. SEO content drives discovery; the catalog is the destination. Built on Postgres + FacetWP.

V2 filter-first

This version. Three-filter configurator drives instant shortlisting. Built on Meilisearch.

Filter combo

A specific selection of scope × destination × home type. Drives a unique URL pattern and a unique ranked result list.

Zero-result combo

A filter combo returning no builders. = builder acquisition opportunity. Marketer Agent uses these as outbound targets.

Exclusivity zone

A premium-tier home_type × state combo exclusively assigned to one builder. Highest-margin tier.

Faceted search

Multi-dimensional real-time filtering. Powered by Meilisearch in V2.

Meilisearch

Open-source search index, self-hosted on the Mac mini. Real-time, faceted, geo-aware. The performance layer that makes V2 viable.

Account-lite

Magic-link email-only account for saved searches. No password. Sent via Resend.

Saved search

A user-bookmarked filter combo. Triggers digest emails when new matching builders are added.

300 landing pages

50 states × 6 home types matrix. Auto-generated by Marketer Agent. Each has unique content (state regulations, permit timelines, financing notes).

A/B routing

Infrastructure (PostHog feature flag or Cloudflare worker) that splits paid traffic between V1 and V2 by buyer segment.

Builder dashboard "Coverage & Types"

Builder self-service panel where they update states_delivered + home_types_offered via a US map UI.