3.0 Architecture Overview

Building the Traffic Controller.

In a standard SaaS app, users log in to a specific workspace, so we always know which "deal" they are working on. In DealTrail, everyone emails one address: tc@dealtrail.com.

This creates a Routing Problem. If a Lender emails us saying "Here is the appraisal," how do we know if it belongs to 123 Maple Ave or 456 Oak St?

The Solution: The Central Brain Router We use n8n to act as a "Traffic Controller." Every incoming email goes through a strict logic gate before it touches the database.

Ingest: AgentMail captures the email and sends a JSON webhook.
Identify: n8n queries Supabase to find which Deal matches the Sender and Subject Line.
Route: If a match is found, the email is processed. If not, we trigger the Ambiguity Protocol.

Handling Uncertainty: The Ambiguity Protocol

What happens if the traffic controller is confused?

The Problem: A busy lender might be working on 5 different deals with us simultaneously. If they email us a generic "Here is the file," we can't be 100% sure which deal it belongs to.

The Solution: We DO NOT GUESS. Guessing creates liability.

Instead, Amy automatically replies: "Hi, I see we have a few open files together. Is this for Maple or Oak?"

When the lender replies "Maple," the system learns, links the email thread to the correct deal, and processes the original file automatically.

Moving Forward: The Success Path

What happens when the traffic controller gets it right?

The Handoff:

Once the Router identifies the deal (e.g., "This is 123 Maple"), it doesn't just dump the email into a database. It packages the email with Context.

It hands the email to the specific Worker Node (Workflow) along with a "Cheat Sheet":

Deal ID: uuid-1234
Address: 123 Maple Ave
Status: Active
Missing Items: [NHD Report, Bank Statement]

This allows the AI to immediately take intelligent action—like renaming the attachment 123_Maple_Appraisal.pdf and filing it—without asking any more questions.

Detailed Breakdown

We break this logic down into two specific technical guides:

[Article 3.2: The "Central Brain" Router]
- How we use a "Waterfall" logic flow (Thread ID $\rightarrow$ Sender $\rightarrow$ Content) to identify deals with precision.
[Article 3.3: The Ambiguity Protocol]
- The specific workflow for handling uncertainty, including the auto-reply templates and the human escalation path.