# Zettlein × Proassistly × Brokher.com
## Master Brief — What we're building, why, and how we merge the three systems

**Version:** 1.0 (English)
**Audience:** (1) The developer who built Proassistly, (2) The founder, (3) Future Zettlein team
**Market:** Cambodia first → regional → global
**Core thesis:** *The Operating System for Real Estate Transactions.*

---

## 0. TL;DR — read this first

We are building **one** transaction system in three layers:

| Layer | Product | Role | Status |
|---|---|---|---|
| **Distribution** | **Brokher.com** | Public marketplace, SEO, top-of-funnel | ✅ Exists (Lovable) |
| **Intelligence** | **Zettlein** | Portable AI desk: broker, lawyer, banker, notary etc. that guides the user through the entire deal | 🔨 To be built |
| **Operating system** | **Proassistly** | Backend, state, CRM, documents, escrow, source of truth | ✅ Exists (developer's system) |

**The rule that governs everything:**
> Brokher shows. Zettlein talks and acts. Proassistly owns the truth.
> Zettlein never touches the database directly — everything goes via Proassistly RPC.
> No binding action is executed without a licensed human's approval (T2).

---

## 1. Product architecture

### 1.1 Brokher.com — Distribution
- Public SSR-rendered marketplace (listings, search, SEO, local content).
- **Never writes business state itself.** Renders a *read-model* from Proassistly.
- Embeds the **Zettlein widget** (script embed) on PDPs, search results, seller onboarding.
- Inherits visitor locale + auth state into Zettlein.

### 1.2 Zettlein — AI desk (portable broker/lawyer/transaction app)
Nine specialist agents, same spec template, three-tier approvals:

| Agent | Responsibility |
|---|---|
| Broker | Matching, viewings, negotiation |
| Lawyer | Contracts, due diligence, jurisdiction |
| Banker | Financing, escrow, FX |
| Developer Liaison | New builds, inventory |
| Service Coordinator | Inspection, photo, moving, insurance |
| Notary | Signing, stamping, registration |
| Landlord | Rent, deposit, tenants |
| Investor | Yield model, portfolio, exits |
| Compliance | KYC/AML, sanctions, PEP, audit trail |

**Approval tiers (no agent operates outside these):**
- **T0 Autonomous** — inform, book, draft. No effect on money/legal.
- **T1 Reviewed** — a human (license holder) must approve before the action is sent.
- **T2 Signed** — requires e-signature + notary/bank confirm. Logged irrevocably.

### 1.3 Proassistly — OS
- Owns: users, listings, deals, documents, payments, events, audit.
- Exposes **one** versioned surface: `POST /rpc/v1/{tool}`.
- Emits domain events (`listing.published`, `offer.submitted`, `deal.signed`…).
- Read-model projected to Brokher; RAG index projected to Zettlein.

---

## 2. Integration Spine — how the three systems talk

```
 ┌───────────────┐  read-model   ┌────────────────┐
 │  Brokher.com  │◀──────────────│                │
 │ (SSR, SEO)    │  events       │                │
 │  Zettlein     │──────────────▶│  Proassistly   │
 │  widget ──────┼──RPC /rpc/v1─▶│  (source of    │
 └──────┬────────┘               │   truth)       │
        │ handoff (Context       │                │
        │  Envelope, signed JWT) │                │
        ▼                        └───────┬────────┘
 ┌───────────────┐                       │ events
 │   Zettlein    │◀──────────────────────┘
 │  agents +     │  RAG index, state sync
 │  tool runtime │
 └───────────────┘
```

### 2.1 Identity
- **One** user identity: Proassistly `user_id`.
- Brokher creates a **Context Envelope** (signed JWT) when the user clicks "Ask Zettlein":
  ```json
  {
    "user_id": "…", "listing_id": "…", "role": "buyer|seller|…",
    "locale": "km-KH", "intent": "…", "iat": …, "exp": …, "sig": "…"
  }
  ```
- Zettlein verifies it and starts a session without re-login.

### 2.2 Data planes (two planes, one truth)
| Plane | Who reads? | Who writes? |
|---|---|---|
| **Read plane** | Brokher, Zettlein UI | Only projectors from Proassistly events |
| **Write plane** | Zettlein tool runtime | Only via `POST /rpc/v1/{tool}` to Proassistly |

### 2.3 Tool catalog (v1) — RPCs Proassistly must expose
Minimum set for Phase 1:

1. `create_lead`
2. `qualify_lead` (KYC stub)
3. `book_viewing`
4. `submit_offer`
5. `counter_offer`
6. `accept_offer`
7. `create_reservation_agreement` (T2)
8. `create_spa` (T2)
9. `open_escrow`
10. `record_deposit`
11. `request_document` (id, income, title deed)
12. `notify_party` (SMS/email/Telegram)

Each RPC: `idempotency_key`, `actor` (agent + human reviewer), `tier` (T0/T1/T2), returns event id.

### 2.4 Continuity guarantees (handoff Brokher → Zettlein → Proassistly)
1. **Context preserved** — envelope travels with every step.
2. **State is server-side** — Zettlein always reads from Proassistly, never from the Brokher DOM.
3. **Idempotency** — every write has an `idempotency_key`.
4. **Audit** — every T1/T2 action is logged with reviewer + signature.

---

## 3. What the developer (Proassistly team) needs to do

**This is the list to hand to your developer.**

### 3.1 Open a stable RPC surface
- [ ] Publish `POST /rpc/v1/{tool}` for the 12 tools above.
- [ ] OpenAPI/JSON schema per tool (input, output, error codes).
- [ ] Idempotency via `Idempotency-Key` header.
- [ ] Auth: verify Zettlein service JWT **and** Context Envelope.

### 3.2 Emit domain events
- [ ] Outbox table + publisher (Kafka/SNS/Redis Streams — whatever you already have).
- [ ] Events: `lead.*`, `listing.*`, `offer.*`, `deal.*`, `document.*`, `payment.*`.
- [ ] Payload versioned (`v` field).

### 3.3 Read-model for Brokher
- [ ] Projector that consumes events → denormalized table/CDN cache Brokher.com renders.
- [ ] No direct DB link from Brokher into the Proassistly core.

### 3.4 Identity federation
- [ ] Endpoint `POST /auth/envelope` that Brokher calls to sign a Context Envelope (HS256/RS256, short TTL).
- [ ] Endpoint `GET /auth/verify` for Zettlein.

### 3.5 Approval hooks
- [ ] Every T1/T2 RPC must be settable to `pending_review` and picked up by a license holder in the Proassistly UI.
- [ ] Webhooks/events when the reviewer approves/rejects → Zettlein continues automatically.

### 3.6 Documents & signing
- [ ] Contract template engine per jurisdiction (Cambodia first).
- [ ] Integration with e-sign (DocuSign/HelloSign/local) + notary flow.

### 3.7 Banking adapters
- [ ] Adapter interface (same port, different providers): ABA, Acleda, Wing, Wise.
- [ ] Escrow ledger as internal double-entry bookkeeping, provider-agnostic.

### 3.8 Observability
- [ ] Trace id through Brokher → Zettlein → Proassistly.
- [ ] Audit log that is irrevocable (append-only + hash chain).

**Handoff to the developer:** upload the Proassistly code to Claude together with this document and have him map every existing endpoint to the RPC catalog in §2.3. Gap analysis = first deliverable.

---

## 4. What YOU (the founder) need to do

### 4.1 This week
1. **Send this document** to the Proassistly developer + Brokher developer.
2. **Book an architecture meeting** (60 min) to walk through §2 and §3 together.
3. **Assign ownership:** who owns the RPC contract? (Recommendation: the Proassistly developer.)

### 4.2 This month
4. **Recruit the Zettlein team:** 1 senior AI engineer (agent runtime + LLM ops), 1 fullstack (widget + UI), 1 prompt/policy engineer (agent specs + guardrails). Can start as freelance.
5. **Legal:** get an opinion from a Cambodian lawyer on what T2 requires (notary, stamping, registration).
6. **Licensing:** identify which license holders (broker, lawyer, banker) will sit as human reviewers in T1/T2.
7. **Data partnerships:** listings feeds, cadastre, developer inventory. No data, no Zettlein.

### 4.3 This quarter
8. **Pilot market:** pick **one** city and **one** segment (e.g. Phnom Penh, condo resale) for Phase 1.
9. **10 pilot deals** end-to-end with Zettlein in the loop. Measure: time-to-close, error rate, NPS.
10. **Fundraising:** this document + pilot data = pre-seed deck.

---

## 5. How we best build Zettlein

### 5.1 Architecture principles
1. **Zettlein is stateless with respect to Proassistly.** All persistent state lives there.
2. **Agents = policy + tools**, not hardcoded code. Change policy → change behavior without a release.
3. **Human-in-the-loop is a feature, not a brake.** Build the reviewer UI first.
4. **One model isn't enough.** Routing: fast reasoning (Gemini 2 Flash / GPT-4o mini) for dialog, heavier (Claude Sonnet / GPT-4o) for contracts & compliance, embeddings for RAG.
5. **Portable:** the same agent runtime runs as (a) Brokher widget, (b) standalone web app, (c) mobile later.

### 5.2 Technical stack (recommendation)
- **Runtime:** TypeScript, edge-first (Cloudflare Workers or similar), streaming.
- **Orchestration:** thin custom agent loop (tool-calling → RPC → observation). Skip heavy frameworks until volume demands it.
- **LLM layer:** one gateway (Lovable AI Gateway / OpenRouter) so models can be swapped per agent.
- **RAG:** Postgres + pgvector for listings, jurisdiction packs, prices. Updated via Proassistly events.
- **Widget:** a `<script>` that injects an iframe with postMessage to Brokher (locale, auth, listing_id).
- **Reviewer UI:** simple inbox in Proassistly where license holders see pending T1/T2 actions.

### 5.3 Build order (critical path)
```
Week 1–2    Contracts: RPC v1 + Context Envelope + event schema
Week 3–4    Agent runtime skeleton + 3 agents (Broker, Lawyer, Compliance)
Week 5–6    Widget on Brokher.com + handoff flow
Week 7–8    Reviewer inbox in Proassistly (T1/T2)
Week 9–10   Escrow + banking adapter (one provider, e.g. ABA)
Week 11–12  Pilot with 3 real deals, closed-loop measurement
```

### 5.4 What we do NOT build in Phase 1
- All nine agents at once (only Broker + Lawyer + Compliance + Banker).
- Multi-jurisdiction (Cambodia only).
- Mobile app (web/widget only).
- Custom model training (prompting + RAG only).
- Marketplace features on Brokher beyond what already exists.

### 5.5 Risk register
| Risk | Mitigation |
|---|---|
| LLM hallucinates and sends a bad contract | T2 always requires human signing; templates are fixed |
| Proassistly schema changes and breaks Zettlein | RPC v1 is a contract, decoupled from the internal schema; versioning |
| Regulatory backlash in KH | Compliance agent + lawyer in the loop from day 1 |
| Banks won't integrate | Manual escrow as fallback + an official partner bank early |
| We build a generic assistant instead of a desk | Stick to the nine-agent model; "chatbot" is a banned word internally |

---

## 6. Effort estimate — MVP with the developer + Claude

Assumes: **Phase 1 scope only** (Cambodia, condo resale, 4 agents, 12 RPCs, one bank), the current Proassistly developer + Claude Code / Claude in the loop as pair-programmer, and this document as spec.

### 6.1 Headline number
**~12 focused weeks (3 months) of calendar time, ~380–520 engineering hours total** to a working MVP piloting 3–10 real deals.

### 6.2 Breakdown by workstream

| # | Workstream | Owner | Hours | Calendar | Confidence |
|---|---|---|---|---|---|
| 1 | RPC v1 surface (12 tools, OpenAPI, idempotency, auth) | Proassistly dev + Claude | 60–80 | Wk 1–2 | High |
| 2 | Domain events + outbox + versioned payloads | Proassistly dev | 30–40 | Wk 2 | High |
| 3 | Read-model projector for Brokher | Proassistly dev | 20–30 | Wk 2–3 | High |
| 4 | Identity federation (Context Envelope sign/verify) | Proassistly dev | 15–25 | Wk 2 | High |
| 5 | Reviewer inbox UI in Proassistly (T1/T2 queue) | Proassistly dev + Claude | 40–60 | Wk 7–8 | Medium |
| 6 | Contract template engine (KH pack, 2 templates) | Proassistly dev + lawyer | 40–60 | Wk 6–8 | Medium |
| 7 | E-sign + notary flow (one provider) | Proassistly dev | 25–35 | Wk 8 | Medium |
| 8 | Banking adapter (ABA only) + escrow ledger | Proassistly dev | 40–60 | Wk 9–10 | Medium |
| 9 | Observability (trace id, audit log, hash chain) | Proassistly dev | 15–25 | Wk 10 | High |
| 10 | Zettlein agent runtime skeleton (TS, tool loop, LLM gateway) | Zettlein AI eng + Claude | 50–70 | Wk 3–4 | Medium |
| 11 | 4 agent policies (Broker, Lawyer, Compliance, Banker) + RAG | Prompt eng + Claude | 40–60 | Wk 4–6 | Medium |
| 12 | Zettlein widget (script + iframe + postMessage) on Brokher | Fullstack + Claude | 25–35 | Wk 5–6 | High |
| 13 | Pilot ops: 3–10 deals, telemetry, feedback loop | Founder + team | 40–60 | Wk 11–12 | Medium |

**Total:** ~440 hours (mid-point). Two engineers full-time hit this in ~12 weeks; one engineer + heavy Claude assistance in ~16–20 weeks.

### 6.3 What Claude actually accelerates (realistic)
- **Big wins (~30–50% faster):** RPC scaffolding + OpenAPI, event schema, projector code, adapter boilerplate, agent policies, prompts, test cases, migration scripts, docs.
- **Modest wins (~10–20%):** reviewer UI, template engine (needs legal review either way), observability wiring.
- **No meaningful help:** legal opinions, bank integrations that require paperwork/KYB, notary onboarding, pilot deal ops. These are gated by external parties, not code speed.

### 6.4 Team assumptions
- **Minimum viable team:** 1 Proassistly developer (existing) + 1 Zettlein engineer (new hire or contractor) + Claude as pair programmer. Founder does ops, legal, bank, pilots.
- **Comfortable team:** +1 fullstack for widget/UI, +1 part-time prompt/policy engineer. Cuts calendar by ~30%.
- **Solo mode (only the current developer + Claude):** doable but stretch to ~5–6 months and Zettlein agent quality will suffer without a dedicated AI engineer.

### 6.5 Cost order-of-magnitude
- Engineering (contractors, KH/regional rates): **$25k–$60k** for the 3-month MVP.
- LLM + infra during pilot: **$500–$2,000/month**.
- Legal (Cambodian counsel, templates, opinion): **$3k–$8k** one-off.
- E-sign + notary + bank onboarding fees: **$1k–$5k**.
- **Total MVP cash out-of-pocket:** roughly **$30k–$75k**, dominated by engineering.

### 6.6 What "done" for the MVP looks like
1. Brokher user clicks "Ask Zettlein" on a Phnom Penh condo PDP.
2. Zettlein widget opens with context preserved (no re-login).
3. Broker agent qualifies the lead, books a viewing (T0), drafts an offer (T1 → reviewer approves).
4. Banker agent opens escrow via ABA adapter; Lawyer agent drafts reservation agreement (T2 → licensed lawyer signs).
5. Compliance agent runs KYC checks; Proassistly logs every action with trace id + hash-chained audit.
6. Deal closes; time-to-close, error rate, NPS captured. Repeat 10x.

### 6.7 Biggest risks to the timeline
1. **Bank integration slippage** — ABA API access can take 4–8 weeks of paperwork. Start week 1.
2. **Legal template review** — needs a real Cambodian lawyer, not just Claude. Book early.
3. **License-holder recruitment** — no T2 flow without them. Line up before week 8.
4. **Scope creep to all 9 agents** — hold the line: only 4 in MVP.

---

## 7. Roadmap (condensed)

**Phase 1 — Cambodia MVP (M0–M6)**
Brokher live • Zettlein widget • 4 agents • RPC v1 • 1 bank • 10 pilot deals

**Phase 2 — Regional (M7–M18)**
All 9 agents • VN/TH/LA jurisdiction packs • Mobile • Developer portal • Series A

**Phase 3 — Global (M19+)**
Multi-currency escrow • Cross-border deals • White-label for brokerage chains • Market data as a product

---

## 8. Appendices (in our Lovable site)

- `/vision` — the thesis
- `/products` — product details
- `/journeys` — user journeys
- `/architecture/system|data|ai|crm|marketplace|banking|legal` — deep dives
- `/architecture/integration` — integration spine
- `/zettlein/flow` — flow
- `/zettlein/orchestration` — Brokher → Zettlein → Proassistly handoff
- `/zettlein/agents` — the nine-agent desk
- `/roadmap` — full roadmap

---

**Contact / ownership**
- Product & strategy: *(you)*
- Proassistly: *(the developer)*
- Brokher.com: *(the Lovable project)*
- Zettlein: *(new lead, to be recruited)*

*This is a living document. Version 1.0 — update at every architectural decision.*