Associado

The problem and constraints

Associado exists to formalize something small business associations already do informally and inconsistently: a member asks around for a plumber, a bookkeeper, a photographer, someone in the group vouches for a specific other member, the two connect, a deal happens, and, in theory, the association was owed a small commission for having made the introduction in the first place. In practice, that last part almost never happens, because nobody is tracking who referred whom, whether it led anywhere, or what it was worth.

The first constraint is that the one fact the entire business model depends on (did the deal actually close, and for how much) happens entirely outside the software, in a conversation and a handshake between two people. The platform can ask about it, but it cannot observe it directly, and it’s asking two people who don’t have symmetric incentives to answer honestly: the person who’d have to pay a commission has every reason to say less than the truth, while the person who wouldn’t pay anything has no particular reason to correct them.

The second constraint is the shape of the request itself. Members don’t type category names. They type “who fixes a leak,” and a system that only understands an exact catalog term like “plumber” will silently fail the moment someone’s vocabulary doesn’t match what got typed into the category list. But a system that answers purely on vague semantic similarity produces a result nobody can audit, and the single most predictable complaint this platform will ever receive is a provider asking why they, specifically, weren’t the one referred. Whatever resolves a request has to be both flexible enough to understand real language and precise enough to explain itself in one sentence.

The third constraint is money handling in a system whose core mechanism is an AI agent reading unstructured WhatsApp messages. Text from a member is exactly the kind of input a language model can be maneuvered by, deliberately or not, and the one part of this system that absolutely cannot be maneuvered is what gets charged to whom. Whatever architecture got built had to make it structurally impossible for anything the model touches to directly decide a commission, a guarantee no policy alone could give.

The fourth constraint was avoiding a specific, already-lived mistake. A sibling platform (a WhatsApp CRM already in production) solves a similarly-shaped problem with a visual workflow tool orchestrating dozens of integration steps, and that tool has a real, ongoing cost: credentials that don’t transfer between environments, execution order that depends on where a box sits on a canvas rather than anything committed to version control, and a saved workflow file that drifts from what’s actually running. This project’s expected volume is a few hundred requests a month for one association, well short of the multi-tenant SaaS scale that justified that other system’s complexity. Carrying the same architecture over here would mean paying operational costs this project’s actual size doesn’t call for.

The last constraint was time itself. A referral that never expires turns into a commission owed on a business relationship the association stopped actually being part of the moment introductions turned into an ongoing arrangement between two people. A plumber introduced once who ends up doing a customer’s monthly maintenance for years is a real outcome this platform needs to not misread as thirty-six separate commission-worthy events.

Architecture

A member sends a WhatsApp message describing what they need. An AI agent (Claude, using tool use rather than free-form generation) reads it and tries to resolve it to a category in the service catalog, first by exact and trigram matching against known terms and synonyms, then, only if that doesn’t land with confidence, by semantic vector search over category embeddings. If neither path resolves cleanly, the agent asks a clarifying question instead of guessing: an unresolved request is logged as a gap in the catalog instead of silently dropped, which is what eventually tells the association where a synonym or a whole category is missing.

Once a category resolves, the same agent queries for providers offering that service (filtered, structurally, to only those who’ve turned on referral consent) and returns a short list to the member, notifying each matched provider that they were referred. Everything up to this point is the agent’s job: understanding language, matching intent to a catalog entry, formatting a helpful answer. None of it touches money.

Money lives entirely in a separate, deterministic path the agent has no access to. Days after a referral goes out, a scheduling worker (running as part of the same process, on a plain database table rather than a task queue) sends a follow-up to both the requester and the provider, independently, asking whether the deal closed and for how much. Only when both answers describe the same deal, within a small tolerance for rounding, does the backend generate a commission automatically. A disagreement in value, one-sided silence, or any ambiguity doesn’t get resolved by more automation: it becomes a queued item in the admin panel for a person to look at, on the theory that a wrongfully generated charge costs the association more trust than a missed one costs it money.

That commission, once generated, is bounded in time on both ends. A request that goes 30 days without a confirmed close simply expires. There’s no such thing as a referral sitting open forever. And if the same requester and provider close another deal in the same category within 90 days of the last one, the system still logs the new referral and still notifies everyone, but records the resulting deal as exempt rather than commission-generating, visibly, as a zero-value, explicitly-exempt record rather than an entry that quietly doesn’t exist. Both windows are configuration values rather than constants baked into logic, and both are explicitly first-guess numbers the design expects to revisit once real conversion data exists to revisit them with.