System design: how the whole machine fits together

0. How to use this doc

1. The system map

Every box that exists or will exist, and what talks to what. The one architectural fact that shapes everything: Entrata only accepts calls from the VPS's static IP (5.78.139.104), and that box is outbound-only. So nothing else ever calls Entrata; everything Entrata-bound goes through an outbox the VPS pulls.

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
  

Component inventory

2. The constitution (binding rules, every build)

These came out of research, the Entrata agreement, and the EliseAI post-mortem. They are not preferences. A build that violates one is wrong even if it works.

1. Only the VPS talks to Entrata. Its static IP is what Entrata allowlists. The box stays outbound-only (no inbound ports); Workers reach it only via the pull-based outbox. One serial gate per the whole account: Entrata forbids concurrent calls.
2. READ-ONLY against any live production property until Brent lifts it for that property, in writing. No write calls before that, ever. Any occupied building with real residents, real prospects, and real staff is read-only by default, whoever owns or manages it. 📌 DECISION, Brent, 2026-08-05: this rule WILL be lifted on NPI-OWNED properties when Foothold goes live on them (Aspen, then Summerset). That is a planned change, not a present one, and it does not loosen anything today. Three things must all be true before a single write is issued anywhere: (1) NPI owns the property, (2) Foothold is live on it, and (3) Brent has signed off in writing naming that property and those methods. Until all three hold, the answer is no. Owyhee Park is NOT covered by that lift and is not expected to be. It is Liberty's building, not NPI's, and a property NPI does not own stays read-only regardless of what we are permissioned for. Everything verified so far was measured there, so do not read a probe result as a licence to write. The allowlist does not go away when the rule lifts, it becomes per-property. It stays deny-by-default and fail-safe at the single request choke point; what changes is that a named property can carry a named set of permitted write methods, rather than the list being empty everywhere forever. A missing, unparseable, or unrecognised property configuration still means read-only. Build it that way from the first line of client code, because retrofitting a per-property gate onto a global bar is exactly where the accident happens. No sendLeads, updateLeads, sendWorkOrders, updateWorkOrders, sendMitsLeads, or any other send/update/delete method. Having the permission is not authorization to use it: Liberty enabled sendLeads and updateLeads on 2026-07-31, so the vendor-side guard we assumed does not exist. The code-side guard is the only one. (sendWorkOrders and updateWorkOrders are still not on the key as of 2026-08-03, and that is now a stronger fact than it was: the maintenance group is present on the key since the 08-03 grant, and Liberty enabled exactly the two reads from it, getWorkOrders and getWorkOrderPickLists, and neither write. So their absence is a deliberate per-method state, not a side effect of a missing group. They are banned here regardless, and a permission change on Liberty's side could add them at any time without telling us.) And the two live writes are staying. Brent declined on 2026-07-31 to ask Liberty to uncheck sendLeads and updateLeads, accepting the risk deliberately, on the reasoning that the permission being enabled is not what causes a write, our code calling a write method is. So assume write capability is permanently present on this key, treat it as a standing condition rather than a gap someone will close, and understand that the code-side allowlist is the only thing that ever prevents a write, and always will be. That makes this rule and that allowlist more load-bearing, not less: nobody on the vendor side is going to catch our mistake for us. Enforce as a deny-by-default read-method allowlist at the single function that issues requests, not per call site, and fail safe (flag missing or unparseable → read-only). Verify a permission landed with getAccessibleServices or a get* call, never by issuing a real write to see if it works. A test guest card puts a leasing agent on the phone chasing a prospect who doesn't exist; a test work order sends a real tech to a real unit. Lifting this for a property needs Brent's explicit written sign-off naming the property and the methods.
3. The AI never calls the Entrata API. The access application states no AI touches Entrata; integration code is deterministic. The agent emits structured intents; the relay validates and executes them. Gate: before the agent answers prospects from Entrata-derived data (availability), do the Entrata AI-disclosure review. That crosses into their AI/ML rules.
4. Every 1:1 touch logs to Entrata (updateLeads note): recognition sends, escalation replies, agent messages, both directions. Liberty sees everything. Only bulk marketing (drips/broadcasts) doesn't log per-contact. Precedence: rule 2 wins on conflict. updateLeads is a write, so while a property is read-only this logging obligation is deferred, not active: touches log locally to the outbox and stay there, and the relay replays them into Entrata only once writes are signed off for that property. Deferred logging is not permission to skip logging; the local record has to be complete enough to replay. 📌 Refined 2026-08-13 (DECISIONS.md #1/#5/#19): the note lands as a real lead event on the lead's own record (updateLeads events array, numeric typeId resolved from getLeadPickLists), so a Liberty agent pulling up the guest card sees the history in place, and Liberty's second surface is a five-line weekly digest email, never a separate Foothold page. Resident-level touches have no appender on the key (sendLeaseActivities is not granted and the ask is tabled), so they log to Foothold's own store and surface in the weekly digest until it exists.
5. Minimum-info gate: no guest card without first name + one contact method. Until then the conversation lives in our stack only. Affirmed 2026-08-13 (DECISIONS.md #3): whether a prospect "expressed interest" is the AI's judgment call, but this gate is hard either way: (phone OR email) AND at least a first name. No guest card without a way to follow up.
6. Never state availability or price without a fresh read. Stale cache or API down → "let me confirm that and get right back to you." This is the EliseAI-proof and the reason Liberty fired the last vendor.
7. Review asks trigger on events and go to everyone at that event. Sentiment-gating is prohibited (FTC, Google, Apartments.com). Never re-ask within ~12 months of a public review.
8. Fair housing: no steering, same facts to everyone, no demographic characterizations, no promises. The move-in-timing priority rule stays written, neutral, and mechanical. HUD treats AI answers as FHA-subject.
9. All Entrata dates/times are Mountain Time. Parse as explicit MT; the VPS runs Pacific, and a lazy parse is a one-day error on dates near midnight.
10. Handoff line: ownership owns through tour-booked or application-submitted (plus one post-tour feedback text); LAG owns everything after. The agent owns the conversation channel; LAG works from the logged notes: two people never reply to the same renter.
11. Secrets live in /opt/foothold-entrata/.env (600) and Worker secrets. Never in repos, never echoed in logs or error paths, never in this binder.
12. Minimize PII at the transport boundary, and never ingest a Social Security number. Binding data rule, set by Brent 2026-08-05: NPI has no use for an SSN and does not want the liability. One is never ingested, never persisted, never logged, and never passed to an AI model. The same single function that enforces the read-method allowlist (rule 2) strips SocialSecurity, SSN and taxId out of every response on read, before anything is written to a store, written to disk, emitted to a log, or handed to a model. This is a scrub at the transport layer, not cleanup downstream, and it fails safe: a response that cannot be parsed well enough to scrub is dropped, not stored. It applies whether or not the field is populated. getMitsLeases r1 defines SocialSecurity in its response schema and it is on our key; Liberty leaves it empty today (§4.1), which is luck, not a control. (The same field appears in getMitsCollections and getVendors response schemas, neither of which is permissioned.) The rule governs document ingestion too: Aspen's 44 executed leases each carry an SSN field (§4.2), so a lease-document or DD pipeline scrubs on the way in on the same terms. Its sibling, already binding: birth dates store month and day only, year dropped at ingest (§3, §8). Entrata's Secure PII Delivery requirements sit under both: never log raw response bodies from getLeads, getMitsLeases or getGlTransactions, and keep no resident data in this repo.
13. Watch the scoreboard, not the plays. Promoted from design intent to Constitution rule by Brent, 2026-08-13 (DECISIONS.md #14). Aggregate KPIs (rating trend, review velocity, renewals, maintenance responsiveness) are measured and reported; individual plays, a single ticket, a single agent response, are never alerted on or chased with Liberty. Two clarifications are part of the decided rule, not exceptions to it: measuring an aggregate is not policing, so the maintenance-responsiveness metric (§10) is squarely inside this rule; and a per-ticket outbound message to a RESIDENT (the post-service follow-up, §9) is not policing a vendor: nothing per-ticket is sent to, demanded of, or logged against Liberty.

3. Data topology: four stores, four jobs

Each store owns one kind of truth. When two docs disagree about "where data lives," this table governs.

Contracts to pin at build time

4. The Entrata protocol (applies to every flow below)

Established by live probes (2026-07-28 auth shape, 2026-07-31 full read probe, 2026-08-03 permission re-probe, 2026-08-05 method probe of the five remaining grants) + the captured OpenAPI spec. 18 groups, 128 methods, 302 schemas. Vendored in this repo: reference/entrata-api-context.md (narrative + real data shapes), reference/entrata-method-index.md (per-method params / read vs WRITE / permissioned, plus the permissioned-service roster. Both were re-captured 2026-08-05 and carry the current 28-service roster), reference/entrata-openapi-2026-07-28.yaml (full vendor spec), reference/entrata-webhooks-2026-03-04.md (verbatim vendor webhook doc, see §4.5). Also on the VPS at /opt/foothold-entrata/entrata-openapi.yaml and in Drive.

4.1 What's actually readable (verified live 2026-07-31, getWorkOrders added 2026-08-03, the last five verified 2026-08-05)

Headline only. Per-method params, versions, and read/WRITE flags for all 128 methods are in reference/entrata-method-index.md; real response shapes, sample payloads, traps, and the PII map are in reference/entrata-api-context.md. Build against those, not against the vendor spec alone.

4.2 What's blocked

4.3 Rate limits, measured

From x-ratelimit-* headers on the 2026-07-31 probe, extended by the 2026-08-05 probes (rows marked 08-05). Per method, not per key, and the spread is enormous. Full table in reference/entrata-api-context.md §6 (re-captured 2026-08-05 and carrying these same rows), and the build-facing version in reference/entrata-touchpoints.md. ✅ The table is COMPLETE as of 2026-08-05: every method the build uses has a measured limit, the last two being getWorkOrders and getWorkOrderPickLists, though a few daily buckets never came back in the headers at all (getLeases, getUnitsAvailabilityAndPricing), and "none returned" in the table below means exactly that, not "unlimited." ⚠️ Read the two tightest buckets separately: they are different methods. Tightest hourly is getMarketingPreferencePickList at 60/hour (10/min). Tightest daily is getWorkOrderPickLists at 1,000/day (60/min, 500/hr). Both are static vocabularies, so cache both and call neither inside a loop.

4.4 Scope of the key (bigger than our authorization)

4.5 Webhooks BLOCKED (not provisioned)

Researched 2026-07-31 from Entrata's own dev-portal Webhooks page, vendored verbatim to reference/entrata-webhooks-2026-03-04.md (vendor updated_at 2026-03-04; the portal is a Gravitee SPA but its backing API at developer-api.entrata.com/portal is public and unauthenticated, so the page is fetchable without a login). Re-fetch commands are in that file's header. Narrative version and the design consequences: reference/entrata-api-context.md §6.1.

5. Flow A: availability pipeline BUILT (mock) IN PROGRESS (live)

Feeds: /rentals, the agent's check_availability, ILS freshness. KPI: apps-per-tour + vacancy days. The EliseAI failure this design exists to prevent lives here.

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
  

6. Flow B: lead capture & speed-to-lead PLANNED

KPI 1 (apps per tour). The agent answers in seconds on its own number; Entrata gets the complete mirror. Handoff at tour-booked or application-submitted.

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)
  

7. Flow C: turn engine DECIDED

KPI 2 (vacancy days → ~0). Ready date = move-in date; the only downtime is the ~3-day make-ready.

flowchart LR
  N["Notice to vacate
(Entrata: getLeases, no status filter,
statusTypeId 5 = Notice)"] --> D["Available + MakeReady dates
(getUnitsAvailabilityAndPricing):
read them, don't recompute"]
  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
  

8. Flow D: recognition engine DECIDED

KPI 3 (renewal 57% → 70%). Real cards in the mail, zero staff tasks. Touch map + tone rules locked in lead-comms §4.

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, move-ins (getLeases + getMitsLeases, verified 08-05. getCustomers blocked 1403)
  V->>S: birth MONTH + DAY only, from getLeads birthDate, joined on customerId (year dropped at ingest)
  V->>S: pets from getLeases r1, per-pet name + type + breed, joined on customerId
  Note over V,S: Ingest scrub, one choke point (rules 12 + 8).
Strip SocialSecurity / SSN / taxId before anything is stored or logged.
Drop isAssistanceAnimal records: a service animal is not a pet.
DOB reaches 65% of current residents (measured 08-05). The Welcome Profile covers the rest.
  C->>S: read trigger matrix (move-in, birthday, pre-renewal −90d, tenure, pet gift, life events)
  C->>S: consent gate: getMarketingPreferences optIn per channel (recipientTypeId 2)
  Note over C,S: Opted out on a channel = no touch on that channel.
Gate fails closed: unknown consent is treated as no.
  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 4)
  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.
  

9. Flow E: review / social-proof engine DECIDED

KPI 4 (3.9★ → 4.5★+). Event-triggered asks at goodwill peaks; reviews feed ILS rank and the site funnel.

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 · renewal (getLeases) · WO completed (getWorkOrders, unblocked 2026-08-03)
  S->>C: recognition sends (from the ledger)
  C->>C: suppression: public review in last ~12 mo? spaced enough? → skip
  C->>C: consent gate: getMarketingPreferences optIn for sms/email → skip if opted out
  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 7, not a style choice.
  

10. Flow F: escalation & edge handling DECIDED

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' → email Liberty's leasing/manager
team direct (adrienne@libertyassetgroup.com today)
+ 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
  

11. FlightDeck & reporting PLANNED

The shared cockpit from the Overview: per-property KPIs, NOI vs budget, DSCR, flags. Sources, per property:

12. Scope traceability: the Overview's promises → this design

Everything promised on / maps here. If a promise has no flow, the design is incomplete; if a flow serves no promise, cut it.

13. Build sequence & gates

14. Open questions (decide at the marked phase)

Known unknowns (unresolved, do not treat as answered)

Things the 2026-07-31 probe surfaced without settling. Recorded so nobody builds on them by accident. One row (DOB coverage) was answered on 2026-08-05 and is kept here, marked, as the record of how it got measured: everything still unmarked is still unresolved.

15. Doc registry & supersessions

Changelog