Inside TheAgent AI — how every function works, and why.

01Executive summary

One AI system doing what agencies buy from four vendors — with one brain and one database.

Agencies today stitch together a chatbot, a call service, a CRM and an ad tool that don't talk to each other. TheAgent AI collapses those into a single system: it advertises, chats, calls, records everything as structured CRM data, and hands off to a human — all sharing one grounded brain and one tenant-isolated store. Because the layers share state, the AI that answers a call already knows the WhatsApp history and the ad the buyer clicked, and the broker sees one timeline.

The rest of this document is organized as: the architecture (§3–5), the AI brain and the property-database methodology that make it grounded (§6–7), a deep dive on every app function (§8–13), the go-to-market machine — personas, marketing, the advertising engine, the closer report and the AI-vs-operator matrix (§14–18), the Setup Center and Master Admin (§19–20), the data, security, billing and operations that make it a real product (§21–26), and the full vision and roadmap (§27–31).

02Product & personas

Who we serve, and how we measure winning.

The KPIs the system is built to move

First-response time (<60s chat), voice turn latency (<~1s), lead→qualified→booked→closed per source, invented-fact rate (target zero), cost-per-qualified-lead, and cost-to-serve & margin per agency — all instrumented, because what you can't measure you can't price or improve.

03System architecture

Four layers, one data spine — nothing bypasses the engine.

Buyers arrive through channels (ads → WhatsApp, phone). Those hit the engine — a stateless API that verifies every request, runs the grounded AI turn, and persists results. All state lives in one database where each agency is isolated at the row level. Operators work in the console. Because every request funnels through the engine, every rule — grounding, tenancy, consent, routing — is enforced in exactly one place.

The codebase is one TypeScript monorepo — a Next.js console, a Node.js engine, and shared typed packages for domain logic, the database layer and retrieval — so one set of types is enforced front-to-back. The seam pattern: every external dependency (AI model, telephony, speech, sending) sits behind a narrow interface, wired to the real service in production and a deterministic fake in tests — so the whole system verifies offline in seconds and any vendor is swappable in one line.

04Multi-tenant & white-label

One codebase, many isolated agencies.

A single shared database serves every agency, with a mandatory tenant_id on every row and PostgreSQL Row-Level Security (RLS) as the enforced boundary, plus app-level scoping as the first line of defence. Defence in depth: the app resolves a tenant per request; the database applies an RLS policy on every table (tenant_id = current agency) that even a buggy query cannot cross; the DB role cannot bypass RLS; and vector-search rows are tenant-tagged so knowledge never leaks across agencies.

05The journey of a message

From an ad click to a booked viewing — the critical path.

1. Capture. The buyer clicks an ad (or messages directly) and lands in WhatsApp with the project context pre-loaded.
2. Verify. Meta delivers a signed webhook; the engine verifies the HMAC signature before trusting a byte — forged requests are rejected.
3. Resolve the tenant. The destination number maps to one agency/project; from here every read/write is RLS-scoped.
4. Understand. Voice notes are transcribed; the buyer's language is detected; history is loaded.
5. Ground. The engine pulls the relevant structured facts (units, prices, plans) and, by vector search, the most relevant brochure passages — the only source of truth for this turn.
6. Generate. Claude writes the reply from that context only, in the buyer's language, following the agency's playbook.
7. Act. A viewing is booked; a CRM lead is created/updated (score, budget, intent) automatically.
8. Deliver & record. The reply is sent; the delivery outcome is stamped on the message — a failure is visible, never silent.
9. Escalate. A hot lead routes to the right agent (language, availability, load); the broker gets a summary + likelihood score and can take over live.

06The AI grounding engine

How the AI knows what it's allowed to say — and never invents a number.

The brain is a large language model (Claude) that never trains on or memorizes an agency's data. Instead, the right facts are fetched fresh on every turn and injected as context — keeping answers current (change a price, the next reply uses it) and auditable (we know exactly what the model was shown).

The agent turn — planner, tools, guardrails

A turn is a structured assembly, not "prompt in, text out": the system prompt (role, disclosure, anti-hallucination rule, the agency's playbook) + retrieved context + conversation history + a small set of tools the model may call (book a viewing, look up a unit, escalate to a human). Tool results feed back in. Guardrails wrap it all: no figure without grounding, no advice as a guarantee, disclosure on voice.

07Property database & knowledge — the full methodology

How the platform stores what it sells, and turns documents into grounded answers.

This is the heart of the product: the AI is only as trustworthy as the property data behind it. The database separates two kinds of knowledge, handled by two pipelines, because they have different truth requirements.

The structured layer — project → unit → payment plan

An agency models what it sells as a small hierarchy: a project (the development, its developer, location, status) holds units (type, size, price, handover), and each unit carries a payment plan (an ordered list of milestones — "on booking 10%", "on handover 40%"…). These are exact, typed values. When a buyer asks "what's the 2-bedroom price and payment plan?", the engine reads these rows and hands the exact figures to the model — the model paraphrases the language, never the numbers.

The knowledge ingestion pipeline — document → grounded answer

Unstructured material (a developer's PDF brochure, a community write-up) becomes retrievable through a five-stage pipeline that runs once per document, then serves every future conversation and call:

1. Parse. The document's text is extracted (a PDF becomes clean text).
2. Chunk. The text is split into overlapping, paragraph/sentence-aware passages — small enough to be precise, overlapped so a fact spanning a boundary isn't lost.
3. Embed. Each chunk is converted, once, into a meaning-vector (Voyage AI, multilingual).
4. Store. The chunk + vector are saved in pgvector, tagged with tenant_id + project_id, so retrieval is always scoped to the right agency and project.
5. Retrieve & ground. A buyer's question is embedded the same way; the database returns the closest-in-meaning passages; only those go to the model as context.

Freshness & provenance

Two properties make the data trustworthy over time. Freshness: update a price or a document once, and every future chat and call uses the new value — no retraining, no lag; the platform can flag when a project's knowledge is getting stale. Provenance: every fact and chunk carries where it came from, so the answer is traceable to a source the agency approved — the audit trail behind "the AI said it because your brochure says it."

The shared canonical catalog — an idea that becomes a moat roadmap

Off-plan projects are largely the same facts for everyone (a tower's floor plans, the developer's official payment plan). The methodology: maintain a shared canonical catalog of verified project facts, with provenance, that any agency can activate — layered with a per-tenant overlay holding that agency's private data (its price, its commission, its allocation), isolated by RLS so one agency's overlay is never visible to another. The AI grounds on canonical facts + the agency's own overlay only.

08Inbox & conversations

Every buyer conversation in one place — with the AI's thinking visible.

The Inbox is the operator's home. How it works, feature by feature:

09Voice command center

The same brain, on a live phone call — under one second per turn.

Voice is realtime: call audio is streamed — not recorded-then-processed — through a four-stage pipeline (speech→text → grounded reply → text→voice) that overlaps work to keep responses fast and natural, including barge-in (the buyer can interrupt).

How the center works: the AI discloses it's an AI by default in the agency's brand + buyer's language; the agency picks the voice from a library and tunes a playbook (how it sells); it buys and releases real numbers in a click; and every call is logged with recording, transcript, AI summary and outcome, day-grouped in the call history. Outbound calling is live; inbound answering (the AI picks up) is the next step.

10Messaging & WhatsApp operations

The official channel, made observable and self-healing.

• Official Cloud API (Meta). Inbound arrives as signed webhooks (verified before trust); outbound goes through the Graph API.
• The 24-hour window. WhatsApp only allows free-form replies within 24h of the buyer's last message; outside it, pre-approved templates are required — the platform models this rule and surfaces it template sending: building.
• Delivery is first-class state. Every outbound records its outcome; a rejection (expired token, closed window) shows in the thread with an actionable reason — never a silent "sent."
• Self-healing connection. The webhook subscription is health-checked and re-attached automatically; a channel-health panel names the exact fault (token, subscription, last inbound) with a one-click reconnect.

11Pipeline & CRM

An operator-grade CRM, purpose-built for this vertical.

12Team & AI routing

The AI hands each lead to the right human, automatically.

Agencies define their team — each agent's languages, availability and specialty. When a new lead arrives, a pure routing engine assigns it to the best agent by language match, availability and current load (least-loaded or round-robin), isolated so a routing error never blocks intake. Admins manage the roster, see each agent's live open-lead load, and configure alert routing. Agents get a personal "My area" for their profile and availability.

13Dashboard & analytics

The whole operation on one screen.

The dashboard reads live from the same data spine: a KPI strip (new leads, meetings, conversations, average response time) with vs-yesterday deltas; a pipeline funnel; an AI health card (real capability flags, knowledge freshness, average response time); today's AI activity; recent conversations; top-performing agents by open pipeline value; and upcoming meetings. Everything is tenant-scoped, so each agency sees only its own numbers. Call scoring & deeper analytics: building

14Customer personas & classification signals live auto-labeling roadmap

The system doesn't sell to "leads." It reads five different buyers.

Every buyer who clicks an ad wants something different from the same apartment: monthly income, a price curve, a home near a school, an exit from rent, or a safe purchase from 5,000 km away. The persona taxonomy below drives all three stages of the machine — which ad finds them (audiences and creative per persona), how the AI talks to them (what it probes for, which objections it expects), and what the closer opens with. One taxonomy, end to end, instead of a marketing deck that dies before the CRM.

The five buyer personas

How the platform classifies them — signals that exist today live

Classification starts from deterministic signals the system already extracts on every AI turn — WhatsApp text, transcribed voice notes, live calls — and never regresses: a "thanks" can't erase a stated budget. Every score carries its reasons, so an operator sees why a lead is hot, never a black-box number.

The signal layer is production code: purpose, budget and timeline extraction with weights (+35/+30/+25…), bands hot ≥ 70 · warm ≥ 35, explainable reasons[], operator corrections on the same 0–100 scale, and profile fields (country, nationality, language, tags) an operator curates today.

Figures shown are industry benchmark ranges or public statistics, illustrative only — not TheAgent AI performance data.

15Marketing strategy — how the machine finds buyers pipes live automation roadmap

Be first, be instant, never leak a lead.

Acquisition strategy here is not "run some ads." It is a machine with three moving parts: markets chosen for structural demand, channels chosen by funnel economics, and an operating discipline that treats every dirham of spend as an experiment with a kill rule. The platform's edge is at the seam: the industry loses roughly half of its ad-generated leads to slow or absent follow-up — the AI answers in seconds, in the buyer's language, forever.

The KPIs this machine is built to move are the blueprint's own (§Product & personas): cost per qualified lead — not per click — first-response time (<60s chat), lead→qualified→booked→closed per source, and cost-to-serve per agency. Everything below exists to bend those four numbers.

The market moment — why now, in two markets

Dubai. 2024 closed at ~226,000 transactions worth AED 761bn (+36% / +20% YoY) (src #75); 2025 set a new record above 270,000 transactions and AED 917bn (src #80). Off-plan — this platform's home turf — went from ~63% of sales in 2024 to roughly 69–70% of transactions in 2025 reporting (src #77, #78), and the city crossed 4 million residents in 2025 (src #86). The buyer base is global (src #81).

Saudi Arabia. The Law of Real Estate Ownership by Non-Saudis (Royal Decree M/14, July 2025) entered into force on 22 January 2026 (src #2, #4 — adversarially confirmed), and in June 2026 the Cabinet approved the actual zones: Qiddiya, New Murabba, Diriyah Gate, KAFD and King Salman Park in Riyadh; Jeddah's centre; plus NEOM, AMAALA, Red Sea and AlUla areas (src #6). In Makkah and Madinah, ownership is a special regime — Muslim individuals worldwide and Saudi companies only (src #7). The sellable pipeline behind those zones is giga-scale: Masar in Makkah (~SAR 100bn program, ~13,000 residential units planned) (src #57, #59), Diriyah (~$63bn, >$4bn residences already reported sold) (src #63, #64), Qiddiya, New Murabba, Jeddah Central, ROSHN's 400,000-home program (src #67, #69, #72, #73). A once-per-generation ownership opening, months old, with inventory measured in the hundreds of billions — and buyers worldwide who have never been marketed to for these products. The machine is market-agnostic by design: Dubai first, Saudi next, same pipes.

Channels — status today, honestly

Why Meta first — the funnel economics

Real estate is structurally cheap on Meta and structurally expensive on Google: in the 2025 LocaliQ benchmarks, real-estate CPL on Facebook was $16.61 — among the lowest of any industry — against $100.48 on Google search ads (illustrative; industry benchmark — src #13, #43). Dubai agency benchmarks put Meta off-plan CPL at roughly AED 25–150 (src #19); GCC panels report Saudi real-estate CPL below UAE levels (src #20), with KSA CPMs around SAR 8–15 (src #22). Meta finds latent demand at volume; Google harvests declared demand at a premium — that ordering, not preference, sets the roadmap.

The Meta playbook — operating discipline, not vibes

1. One anchor metric: TCPL — target cost per qualified lead. Not cost per form-fill. "Qualified" is the platform's own explainable score (warm ≥ 35, hot ≥ 70), which means the quality layer Meta can't see is computed automatically on every conversation — the CRM check that most advertisers do by hand, done by the product. Every kill/keep/scale rule below is arithmetic on TCPL.
2. Two-campaign structure per market. A Scaling campaign (~80% of budget) holds only proven ads; a Testing campaign (~20%) protects new concepts from being starved. Ad-count ceiling sized to budget so every ad gets a fair read; image-first validation before video spend.
3. Audiences mapped to personas. Lookalikes (1–3%) seeded from won deals and hot leads — not raw form-fills; interest layers per persona (yield investor: investing + landlord interests; relocator: family + schools + moving signals); geo splits: UAE + GCC + top diaspora markets for Dubai (src #81); KSA domestic plus worldwide Muslim-majority markets for Makkah/Madinah products, respecting the ownership regime (src #7). Always exclude existing customers and recent converters.
4. Creative from grounded data, three angles per persona. Yield: rental demand + service-charge honesty. Appreciation: launch access + masterplan. End-user: community + handover certainty. Ads never promise what the project data can't back — the same grounding rule that governs the AI's answers. Seasonality is planned, not suffered: GCC peak-season CPMs run +40–80% (src #27).
5. Lead form design: short form, smart conversation. Industry data says instant forms produce 2.5–4× more raw leads at lower CPL but worse downstream quality; longer forms trade volume for intent (src #23, #24). This platform breaks the trade-off deliberately: the form stays minimal (name + phone) because qualification is the AI's job — the conversation is the qualifying form, with a 0–100 score instead of a checkbox. Higher-Intent form type when volume outruns quality.
6. Speed-to-lead — where benchmarks become an edge. Classic and modern studies agree: contacting a lead within 5 minutes multiplies qualification odds ~21× vs 30 minutes (src #32); 78% of buyers go with the first responder (src #38); yet mystery-shopping keeps finding that roughly half of real-estate leads never get a human response at all (48% in 2014; 47% in 2024) (src #34, #35). The platform's first reply is designed to land in under a minute, in the buyer's language, at 2am — the funnel's biggest known leak, welded shut by architecture.
7. Kill, keep, scale — by rule. No spend judgment before 3× TCPL of data; zero qualified leads at 3× TCPL kills the concept; qualified-rate < 40% swaps the angle; graduation to the scaling campaign only after ≥ 5 qualified leads at ≤ TCPL over ≥ 14 days; budget scales +20% per 5 days, never more; frequency and CPM drift trigger staged creative refresh. Today this discipline is the operator's manual, run on the platform's scores live; the Advertising engine automates it with Spend-Guard as the circuit breaker roadmap.

An illustrative month — how the math compounds

Illustrative scenario, not a projection: a Dubai off-plan agency spends AED 30,000/month on Meta. At benchmark off-plan CPL of AED 25–150 (src #19) that is roughly 200–1,200 raw leads. Industry lead-to-appointment averages 10–15% (src #30) — but that average embeds the ~47% who never get contacted (src #35). A system that answers every lead in seconds competes on the contacted half of the curve, where top producers reach 25–30% (src #30). The same budget, the same benchmark CPL — the variable this platform moves is what happens in the first five minutes, every time, at zero marginal headcount.

Attribution today, optimization tomorrow

live Every lead carries its origin: ad id, headline, form id, and the CTWA click id (ctwa_clid) captured on the first message — the closer knows which promise the buyer clicked. roadmap The Advertising engine closes the loop: server-side Conversions API reporting qualified / booked / closed back to Meta so optimization targets real outcomes, per-persona cost-per-qualified-lead dashboards, automated budget shifts under Spend-Guard — the full design lives in the Advertising engine section.

Google & organic — the planned second wave roadmap

Google harvests declared intent at a premium: UAE real-estate CPCs run ~AED 18–65 with premium keywords higher (src #50), in what is frequently cited as the world's most expensive CPC market (src #52), and US benchmarks put real-estate search CPL around $100 (src #43). It earns its place once the Conversions API loop exists: Performance Max for lead gen only pays off when fed offline conversion data — qualified leads, not form-fills (src #53, #54) — which is exactly the data this platform already produces. Organic and portal presence then feed the same WhatsApp entry points, so every channel lands in one front door, one score, one closer report.

Figures shown are industry benchmark ranges or public statistics, illustrative only — not TheAgent AI performance data.

16The Advertising engine — how the ADS work roadmap

The AI doesn't just answer leads — it goes and gets them.

The advertising engine closes the loop at the top of the funnel: it builds and runs campaigns, ingests the leads they produce straight into the same AI, and attributes every dirham of spend to a real outcome. It is designed around one principle — every lead source flows into one AI front door — so a new channel is just another pipe into the same qualification engine.

How it works, step by step

1. Creative from the property data. The AI generates campaign structure, ad copy and creative angles per project directly from the grounded project data (real units, prices, USPs) — so ads never promise what the data can't back, and there's no manual ad-ops.
2. Campaigns via the official APIs. Campaigns, ad sets and ads are created through the Meta Marketing API and Google Ads API — the platform manages budgets, audiences and schedules programmatically.
3. Lead ingestion, zero leakage. Meta Lead Ads and click-to-WhatsApp land the buyer directly in the AI conversation; there's no CSV, no delay — the lead is qualified within seconds of clicking.
4. Audiences & A/B. Lookalike and interest audiences, plus continuous A/B testing of creative and copy, with a lift measurement so budget flows to what actually produces qualified buyers.
5. Attribution (the closing of the loop). A pixel + server-side Conversions API reports real outcomes (qualified, booked, closed) back to the ad platforms, so their optimization targets real results, not just clicks — and the agency sees cost-per-qualified-lead and ad → conversation → viewing → sale end to end.
6. Budget optimization & the managed model. A flat managed marketing add-on runs Meta + Google across all of an agency's projects; the engine shifts budget toward the best cost-per-qualified-lead automatically.

Ad-account resilience — designed against bans

Ad accounts get restricted; a single point of failure would take an agency dark. The design is ban-resilient: multiple business managers, redundant Conversions-API paths, and automatic failover + appeal handling, so a restriction on one account degrades gracefully instead of stopping lead flow.

17The closer report — AI qualifies, humans close live

The AI never signs the deal. It manufactures the conversation in which a human can.

Everything upstream — the ad click, the WhatsApp thread at 2am, the qualifying questions in the buyer's language, the voice call, the booked viewing — exists to produce one artifact: a ready-to-close conversation, handed to a human closer with a complete dossier. The AI extracts, scores, summarizes, books and routes. The human persuades, negotiates and signs. That boundary is architectural, not aspirational: takeover controls, AI disclosure on calls, and escalation paths exist precisely so the machine prepares and the person closes.

The dossier — what the closer receives today live

Every component below is generated by the live system and visible in the operator console the moment a lead is worth a human's time. The relationship summary is framed in the code itself as "what a human agent needs before picking up the phone."

A closer report, end to end

Illustrative example — fictional buyer. Every field below is a real field the live system produces.

Sara picks up the phone knowing the ad that brought him, what he wants in his own words, his one real objection, and exactly what to open with. None of it was typed by a human — the capture, the score, the summary and the booking were produced by the system.

Handoff mechanics — how the baton passes live

1. Auto-assignment on arrival. Every new lead routes to the best available human by language match and current load, and the assignment is audited. No pool, no cherry-picking, no lead sitting unowned.
2. Takeover — human control is absolute. One action flips a conversation from AI to human. Under human control the AI is silent: it does not reply, interject or improvise.
3. 30-minute auto-handback. If the operator goes idle past 30 minutes, the conversation hands back to the AI — audited — so a buyer never messages into a void because a human stepped away.
4. "I want a human." An explicit request creates exactly one urgent callback task for the owner — idempotent, so repeat requests don't spam the task list. Honest boundary: there is no live call transfer in v1; escalation is an urgent callback, not a warm transfer.

One packaging note, honestly tagged: all of the dossier data above is live and visible across the lead panel, summary and pipeline views. A single exportable one-page closer brief — the same dossier as one shareable artifact — is building. It is an assembly of fields that already exist, not new intelligence.

18AI vs. operator — who decides what

The AI executes and proposes; humans set policy and own the irreversible.

"Human in the loop" is usually a vibe. Here it is a governance model you can audit: for every decision in the acquisition funnel — which campaign runs, where budget goes, which lead gets called and when, what the AI is allowed to say, which offer is on the table, when a human takes over — one table states who decides, under which guardrail, and whether that is shipped code or roadmap. The operating principle is fixed: the AI owns high-frequency, reversible execution; humans set policy and own every irreversible commitment — money, price, and the final word on a deal. And the default posture is conservative: the most invasive capability in the system, calling people, ships off per agency until a human explicitly turns it on.

The decision matrix — the full funnel

Read the "Today" column honestly and a clean pattern appears. Everything upstream of the lead — campaign, budget, creative, audiences — is operated by humans outside the platform today; the Advertising engine that automates it is roadmap, and the target models above activate only as it ships. Everything from first contact to handoff — scoring, routing, cadence, grounded answers, booking, escalation — is already decided by the system in production, each with its guardrail in code, not in a policy PDF. And everything that commits money or ends a deal is human in both columns — by design, not by temporary limitation.

Escalation triggers — what flips a conversation to a human today

1. The buyer asks. An explicit "I want a human" creates one urgent callback task — idempotent, so ten requests still make one task. There is no live mid-call transfer in v1; a human calls back rather than relying on a fragile patch-through.
2. The operator takes over. One action in the inbox flips the conversation to human control at any moment, unconditionally — no AI veto, no threshold to satisfy.
3. The system raises its hand. The urgent task lands with the routed agent — matched by language and current load — and surfaces in their agenda until handled.

The design intent is that all three converge on one motion: a hot lead reaches a human with the dossier, not just a phone number — score and its reasons, objectives, objections, sentiment, next action — the package described in the closer report. Escalation is a promotion with context, not an exception thrown over a wall.

The three governance zones

19The Setup Center — how an agency onboards itself building

From signup to a live AI answering a real lead — the same day, with no help from us.

The Setup Center is what turns TheAgent AI from "a product we operate for a client" into "a product any agency runs itself" — the difference between a service and a scalable business. Its job: let an agency connect its own third-party accounts and data through a guided wizard, store those credentials safely and per-tenant, verify each connection, and go live — without an engineer in the loop.

The onboarding wizard, step by step

1. Company & branding. Name, logo, colours, languages, timezone, quiet hours — written to the tenant's theme + config, which immediately restyle the console and set the agent's behaviour.
2. Connect WhatsApp. The agency links its own WhatsApp Business number (its phone-number id + token, or an embedded-signup flow). The platform verifies the token against Meta, checks the webhook subscription, and shows a live health status — the same self-healing connection layer described in §10.
3. Connect phone / voice. The agency connects telephony (its own Twilio subaccount, or buys a number in-app), picks the AI voice from a library, and tunes the playbook and disclosure name.
4. Load the property knowledge. The agency selects projects from the shared canonical catalog (or registers its own), enters units/prices/plans, and drops in brochures/PDFs — which flow through the ingestion pipeline (§7) so the AI can ground on them.
5. Connect ads & calendar. Link Meta/Google ad accounts and a calendar for viewings (roadmap), so the ad engine and booking work end to end.
6. Test in a sandbox. A test chat and test call run against the agency's own data before anything is public — proof it works, not a leap of faith.
7. Go live. One switch turns the number on and ads on; leads start flowing into the CRM.

Per-tenant credential vault — the architecture underneath

Every agency brings its own WhatsApp, telephony, voice and ad credentials. Those are stored in an encrypted, per-tenant credential store, isolated by the same RLS boundary as all tenant data, and read only server-side at the moment a call to that provider is made — never exposed to the browser or to another tenant. Each capability is gated by the tenant's plan entitlements, so connecting (say) voice is only offered on a tier that includes it.

20Master Admin building

One control room over every agency.

The platform operator needs oversight without breaking isolation. Master Admin provides: a directory of all agencies with health scores; usage & cost-to-serve per agency (voice minutes, messages, AI tokens) against a live margin view; plan & entitlement management; feature flags; and incident tools. Crucially, it reads raw tenant data only through an audited request-access flow — support can help without a standing backdoor, and every access is logged. This is how we run thousands of tenants safely and profitably from one place.

21Data model & ERD

Every row is owned, typed, and auditable.

The spine is tenant → project → unit (what's sold) and lead → conversation → message / call / appointment (who's buying and what happened). Every table carries tenant_id (RLS), timestamps and soft-delete where needed; admin changes are written to an append-only audit log.

22API design

A stateless HTTP surface with a strict trust boundary.

• Two kinds of endpoint. Public webhooks (WhatsApp, telephony) — each cryptographically verified before trust; and authenticated operator APIs behind sign-in + role checks.
• Auth & tenancy. Operator requests carry a signed session resolving to an agency + role; the engine sets the tenant per transaction so RLS applies to every query.
• RBAC. Every mutating route checks a capability (e.g. conversation.write, channel.write).
• Observable side-effects. Network calls happen after the DB transaction commits; their outcome is recorded, never silently dropped.
• Backend-for-frontend. The web app holds no provider secrets; it proxies through server routes.

23Security & compliance

Isolation and consent are core, never bolted on.

24Billing & economics roadmap

Recurring subscription plus metered, legible cost-to-serve.

We bill the agencies — a monthly subscription per agency, with usage-based costs (AI, voice minutes, messages, a share of ad spend) that are per-interaction and meterable. The platform never touches a buyer's money — no deal-flow risk. A live margin dashboard per agency and a per-agency spend guard keep unit economics legible and safe as volume grows.

25DevOps & infrastructure

Ship fast without breaking what's live.

26Testing & quality

A mandatory gate nothing broken can pass.

A comprehensive suite (hundreds of tests) runs on every change; nothing ships unless all tests pass, plus type-checking and a full build. Because every dependency is behind a seam wired to a deterministic fake, the whole system verifies offline, for free, in seconds. Standouts: a cross-tenant test (A can never read B), a grounding eval harness (flags invented facts / guarantees), and pure-logic unit tests for scoring, routing and pipeline math. The database layer runs against an in-process Postgres, so RLS behaviour is exercised for real.

27The big ideas — where this goes

The vision the architecture is deliberately built to reach.

The foundation was designed so these are extensions, not rewrites — each one sits on the same grounded brain, the same data spine, and the same multi-tenant isolation.

28Roadmap

Foundation shipped; the next phases are designed, not speculative.

Each release ships in small, tested increments — R1 landed as ten consecutive milestones without breaking production — so the roadmap is a sequence of low-risk steps, not a big-bang launch.

29Engineering risks & how they're handled

The honest list — and the mitigation for each.

30Why it's defensible

The technical reasons this is hard to copy.

31Appendix & glossary

The stack, and the terms, in one place.

Glossary

This document describes the engineering of TheAgent AI as built and planned. Items marked building or roadmap are designed but not yet fully shipped; figures are indicative and evolve as the platform ships. Technical questions welcome.