System design: how the whole machine fits together

flowchart LR
  subgraph FRONT["Front doors (renters & residents)"]
    SITE["footholdboise.com
Astro · CF Pages"]
    ILS["Apartments.com / Zillow
via Entrata ILS syndication"]
    NUM["Ownership # + per-property #
Twilio SMS · calls fwd to LAG"]
  end
  subgraph EDGE["Cloudflare edge (Workers)"]
    WAIT["/api/waitlist"]
    AGENT["AI leasing agent
Claude · v1 chat, v2 Agents SDK"]
    ENG["Recognition + review engines
cron Workers"]
    KV[("KV
availability cache")]
    OUTBOX[("Entrata outbox
Queues, pull-consumer")]
  end
  subgraph VPS["VPS 5.78.139.104 — the only IP Entrata sees"]
    POLL["Availability poller
12-min, serial gate"]
    RELAY["Entrata relay
outbox consumer, deterministic"]
  end
  subgraph SAAS["Owned SaaS"]
    GHL["GoHighLevel
lead store · tags · drips"]
    SUPA[("Supabase
agent datastore")]
    HW["Handwrytten
mailed cards + gift cards"]
    TRE["Tremendous
digital gift cards"]
  end
  ENT["ENTRATA
Liberty's system of record"]
  LAG["Liberty Asset Group
works natively in Entrata"]
  FD["FlightDeck
owner analytics"]

  SITE --> WAIT --> GHL
  SITE --> AGENT
  ILS -- "lead email (1 of 6)" --> AGENT
  ILS -- "native CoStar feed" --> ENT
  NUM --> AGENT
  AGENT --> GHL
  AGENT -- "reads" --> KV
  AGENT -- "state" --> SUPA
  AGENT -- "intents" --> OUTBOX
  ENG --> HW
  ENG --> TRE
  ENG -- "asks via Twilio" --> NUM
  ENG -- "log notes" --> OUTBOX
  POLL -- "getUnitsAvailabilityAndPricing" --> ENT
  POLL -- "publish" --> KV
  KV -- "/rentals reads" --> SITE
  OUTBOX -- "HTTPS pull" --> RELAY
  RELAY -- "sendLeads / updateLeads / sendWorkOrders" --> ENT
  ENT --- LAG
  ENT -- "financials + WOs + leases" --> FD
  GHL -- "funnel metrics" --> FD

  classDef live fill:#e2efe5,stroke:#1f6b3a,stroke-width:1.5px
  classDef built fill:#e6e9f3,stroke:#3a4a86,stroke-width:1.5px
  classDef planned fill:#fff,stroke:#7a7264,stroke-dasharray:5 4
  classDef ext fill:#f7ede4,stroke:#bb6238,stroke-width:1.5px
  class SITE,WAIT,GHL live
  class POLL,RELAY built
  class AGENT,ENG,KV,OUTBOX,SUPA,HW,TRE,FD,NUM planned
  class ENT,ILS,LAG ext
  

sequenceDiagram
  autonumber
  participant T as VPS timer (12 min)
  participant G as Serial gate
  participant E as Entrata
  participant K as CF KV
  participant W as /rentals
  participant A as AI agent
  T->>G: tick (skip inside maintenance windows)
  G->>E: POST /{org}/v1/propertyunits — getUnitsAvailabilityAndPricing (per property)
  E-->>G: units + pricing (MT dates) + rate-limit headers
  G->>K: publish avail:{propertyId} + avail:index
  W->>K: read on page view (never hits Entrata)
  A->>K: check_availability tool
  Note over A,E: Commit moment (quote / apply link):
one targeted live re-check via the relay — sparingly, it spends rate budget
  Note over G,E: Backoff ladder: rate-header low → stretch interval;
5xx/maintenance → serve last-good, alert only if stale > 2h
  

sequenceDiagram
  autonumber
  participant P as Prospect
  participant I as Apartments.com / Zillow
  participant A as AI agent
  participant H as GHL
  participant Q as Outbox
  participant V as VPS relay
  participant E as Entrata
  participant L as Liberty
  P->>I: inquiry (real name, email, phone, move-in date)
  I->>E: native CoStar feed → guest card
  I->>A: lead email (one of 6 destinations)
  A->>P: reply in seconds, own number, 24/7
  Note over A: Min-info gate: first name + one contact method
before anything touches Entrata
  A->>H: capture_lead + tags + source
  A->>Q: intent: logNote / sendLead
  Q->>V: HTTPS pull (outbound-only box)
  V->>E: getLeads by email — dedupe first
  alt card exists (ILS path)
    V->>E: updateLeads — note on existing card
  else no card (site / chat / SMS lead)
    V->>E: sendLeads — create guest card
  end
  Note over V,E: EVERY message both directions logs as a note.
Notes are record-only — no send API exists, so no duplicate risk.
  A->>P: book tour or ProspectPortal apply link
  Note over A,L: ── HANDOFF: tour booked OR application submitted ──
  L->>E: tour, leasing, move-in — natively
  A->>P: one post-tour feedback text (~1–2 hrs)
  

flowchart LR
  N["Notice to vacate
(Entrata: getLeases / getExpiringLeases)"] --> D["Compute available date
vacate + Liberty turn SLA (~3–4 days)"]
  D --> C["Liberty confirms ready date
(pre-inspection walk; nothing goes out before)"]
  C --> M["Match waitlist on optional profile
beds / budget / pet / timing"]
  M --> W1["1. Matched Insiders — 48-hr early window
texted first, ordered by stated timing"]
  W1 --> W2["2. Broader waitlist"]
  W2 --> W3["3. Public listing — ILS syndication fires"]
  W1 -.-> APP["Applications"]
  W2 -.-> APP
  W3 -.-> APP
  APP --> R["Allocation rule (written, neutral, mechanical):
among QUALIFIED applicants, completed app
closest to the ready date wins"]
  R --> S["Lease signed → move-in = ready date"]
  classDef lag fill:#f7ede4,stroke:#bb6238
  class C lag
  

sequenceDiagram
  autonumber
  participant V as VPS (daily pull)
  participant S as Supabase
  participant C as Recognition cron
  participant HW as Handwrytten
  participant TR as Tremendous
  participant T as Twilio (ownership #)
  participant Q as Outbox → Entrata
  V->>S: resident facts — leases, renewal dates, pets, move-ins (getLeases / getCustomers)
  C->>S: read trigger matrix (move-in, birthday, pre-renewal −90d, tenure, life events)
  alt mailed touch (welcome / birthday / pre-renewal / tenure / sympathy)
    C->>HW: handwritten card (+ $25 gift card where the map says)
  else digital gift
    C->>TR: gift card by text
  end
  C->>T: follow-up text the night it lands — "make sure you got your package"
  C->>Q: log note — "mailed birthday card + $25 gift card"
  Note over Q: PM sees every touch in the Entrata thread (rule 3)
  Note over C: Pre-renewal card lands ~90 days out, AHEAD of the ~60-day offer.
Gift-then-offer reads genuine; offer-then-gift reads like a bribe.
  

sequenceDiagram
  autonumber
  participant E as Entrata events
  participant S as Supabase
  participant C as Review cron
  participant T as Twilio
  participant R as Resident
  participant G as Google / Apartments.com
  E->>S: move-in +2wk · WO completed · renewal (via VPS pulls)
  S->>C: recognition sends (from the ledger)
  C->>C: suppression — public review in last ~12 mo? spaced enough? → skip
  C->>T: the ask, from the ownership number
  T->>R: text + smart link (or the service-call card, left on site)
  R->>G: public review
  G-->>C: monitor → ILS scorecard + site testimonials
  C->>E: log the ask (outbox note)
  Note over C,R: Trigger on EVENTS, ask EVERYONE at that event.
Sentiment-gating is prohibited — that's rule 6, not a style choice.
  

flowchart TD
  M["Message on the ownership channel"] --> GD{"Guardrail check
(Haiku pre-pass)"}
  GD -- "leasing, in scope" --> RE["Agent replies
logs note via outbox"]
  GD -- "service ticket" --> SR["Acknowledge instantly + redirect gently
'Liberty's responsibility, we passed it on'"]
  SR --> WO["sendWorkOrders via relay
(emergency → maintenancePriorityId from
getWorkOrderPickLists, mapped per property)"]
  WO --> LAG["Liberty resolves — natively, their SLA"]
  GD -- "out of its depth" --> ESC["'Let me get a person' + urgent note
on the guest card → Liberty takes over"]
  GD -- "agent / API down" --> FB["Fallback email to the Liberty PM
with lead + full context — nothing lost"]
  LAG -.-> AGG["Foothold watches the AGGREGATE
(rating trend, review velocity, renewals)
never per-ticket policing"]
  classDef crit fill:#f3e0dd,stroke:#9a3b2b
  class FB crit