Skip to content
All work

01Case study

Outreach Pro

An internal research and outreach system for Studio Sajtova: evidence first, then a question

At a glance

Problem
Writing to a local business well means knowing what was actually seen on its site, what is only assumed, and what the owner has said.
Role
Product & engineering
Key decisions
  • Evidence and assumptions are separate tables, so an observation can't be edited into a guess and a hypothesis can't exist without evidence.
  • Rules exist twice: TypeScript policies explain before anything is written, and Postgres enforces them for every writer.
  • Cancellation lives in the database, so every path that stops a contact cancels pending email the same way.
Status
Internal toolIn production as a private, sign-in-only application; delivery of a scheduled email hasn't yet been verified end to end.
Stack
TanStack Start, React, TypeScript, Supabase, Resend, Google Places API
Timeline
2026

One business, from search result to a confirmed problem

The panes on the right are the system's records and rules.The figure in each step draws the system's records and rules. One business is followed from a search result, through research, to the moment its problem is confirmed. What was observed, what is assumed and what the client said stay apart the whole way.

Skip the walkthrough
  1. 0108

    Discover

    A search runs against Google Places and returns businesses as results: name, address, website, phone and rating. Each one is reviewed, then kept or skipped.

    Repeating a search shows only businesses not seen before: remembered results first, then the next page, with at most two Google requests per search. A place already in the list is never shown again.

    • result: new → reviewed | skipped
    • seen place ID → not shown again
    One row per result. Reviewed rows stay; skipped rows step back. A repeated search shows only rows not seen before.
  2. 0208

    One business, one record

    A kept result becomes a prospect: one record per business in the workspace, shared by every project that researches it. It needs no email address yet.

    The database enforces the identity on the Google place ID and on the website's normalized domain. The same business found again resolves to the record that exists, and only what the source reported is copied onto it.

    • result → prospect
    • same place ID or domain → the existing record
    • stage in the project: discovered
    A kept result becomes the business's one record; another result for the same place resolves to that record.
  3. 0308

    Evidence

    The business's website is read from the server: the homepage, then at most three same-site pages likely to hold contact details. Every request and every redirect passes a guard: public addresses only, the connection pinned to the address that was checked, time and size capped.

    Real-estate sites get a second pass over the sitemap and a few offer pages, at most ten requests per analysis.

    What the pages show comes back as observations with their source URL, and nothing is saved until a person keeps it. Evidence can be removed but never edited, and an entry worded as a guess (“probably”, “maybe”) is refused.

    An email address printed on the site is kept on the record together with the page, the method and the time it was seen.

    • observed: sourced, append-only
    • internal address → stopped at the guard
    • worded as a guess → refused
    Requests pass the guard; one to an internal address stops there. Observations come back with their source, a person keeps some as evidence, and the email found on the site joins the record.
  4. 0408

    Hypothesis

    A hypothesis is its own record: an assumed problem, saved by a person and linked to at least one piece of evidence about the same business. The database checks the link when the transaction commits, so a hypothesis without evidence can't exist.

    Its status can't be edited. Two database functions move it to confirmed or rejected, and only from assumed. Evidence a hypothesis rests on can't be deleted.

    Nothing changes one state into another on its own: evidence never confirms a hypothesis, and no stage change confirms anything.

    • hypothesis: assumed
    • ≥ 1 evidence link, checked at commit
    • linked evidence → can't be deleted
    Dashed: an assumption, linked to the evidence it rests on. That evidence can't be deleted while the link exists.
  5. 0508

    Opportunity and stage gates

    An opportunity is the offer built on one hypothesis. That hypothesis needs evidence and can't be rejected, but it doesn't have to be confirmed yet.

    Each project keeps one stage per business, from discovered to won. Opportunity needs a supported hypothesis and an opportunity; Pain confirmed needs a hypothesis the client confirmed.

    Users can't write the stage column. A server function applies the rule, then writes with elevated rights only if the stage is still the one it checked.

    • discovered → researching → opportunity
    • pain_confirmed: closed until confirmed
    • stage changed meanwhile → refused
    The opportunity is built on the supported hypothesis, which opens the gate to Opportunity. Pain confirmed stays closed until the client confirms.
  6. 0608

    Asking, not claiming

    While the problem is only assumed, the next step the workflow suggests is a question that checks it. Offering the solution is suggested only after the client has confirmed the problem.

    Writing needs a contact with a valid address, typed or found on the site. A draft waits for review before it's sent, and the database ties the email to this project and this business; its follow-ups inherit that.

    Every send, manual or scheduled, passes one send policy in a fixed order: the recipient, the sender, then the weekday send window in Belgrade time. The daily slot is claimed in one locked database step, so concurrent sends can't exceed the limit.

    • assumed → validation question
    • confirmed → offer
    • recipient fails → cancelled
    • outside the window → waits
    While the problem is assumed, the next step is a question that checks it. The reviewed email passes the same send checks as every other.
  7. 0708

    Signed feedback and stopping

    Delivery events come back from Resend through a signed webhook. The signature is checked against the raw request, events more than five minutes off are rejected, and each event ID is recorded once, so a replay does nothing.

    A reply is marked by hand. It cancels the timed emails to that contact in every project and keeps unscheduled drafts; the other projects show their outreach as paused by a reply elsewhere, so a person looks before anything new goes out.

    A hard stop cancels everything pending for the contact: an unsubscribe, a bounce or complaint, a suppressed address, a “not interested” or “do not contact” status. It happens in the database, on the status change itself.

    Every email carries one-click unsubscribe headers; the link opens a confirmation page, and only the confirming request changes anything.

    • valid signature → recorded once
    • reply → timed emails cancelled, every project
    • unsubscribe | bounce | suppressed → all pending cancelled

    The cancellation paths are covered by the database integration and SQL tests.

    Signed events are recorded once; a replay is ignored. Left: a reply cancels the timed emails in every project and the draft stays. Right: a hard stop cancels everything pending.
  8. 0808

    Confirmation

    Only the client can confirm a problem. A confirmation names its source (an email reply, a call, a meeting or a note) and records what the client said. There is no system source.

    Recording a reply doesn't change a stage or confirm anything. A person reads it and confirms or rejects the hypothesis; only then can the project move to Pain confirmed.

    A rejected hypothesis stays on record, crossed out, and can never be the basis of an opportunity.

    • assumed → confirmed (client source + note)
    • assumed → rejected
    • pain_confirmed: open
    The reply, marked by a person, is recorded with its source and what the client said. It confirms the hypothesis (solid) and opens Pain confirmed. A rejected one stays on record, crossed out.

Problem

Writing to a local business well means knowing what was actually seen on its site, what is only assumed, and what the owner has said. Outreach Pro keeps those three apart from the first search to the reply.

Around that sits the work of an internal outreach tool: projects, a research queue, a pipeline, and sending that stops when it has to.

The Outreach Pro overview: navigation grouped into work, outreach and system, today's work counted by what it waits for, and a list of next steps.
The overview: today's work and the next steps, nothing done automatically.

Product & design thinking

Four knowledge states, each with its own treatment, icon and label, never colour alone: observed (solid), assumed (dashed outline), confirmed (solid, locked), rejected (crossed out).

Communication state is derived, never stored as a stage: contacted, replied, paused and stopped are computed from the email and activity records. The research queue, the pipeline and the dashboard read the same derivation, so they can't disagree.

The research queue isn't stored either. It groups businesses by what they lack (evidence, a hypothesis, a validation) and offers one next step for each.

The research graph draws only stored relationships: business → channels and evidence, evidence → hypothesis through its links, hypothesis → opportunity. Nothing is inferred from text or similarity.

The research queue: businesses grouped under no evidence, waiting for a hypothesis and problem not confirmed, each with its counts, a priority and one next step.
The research queue, grouped by what each business lacks, with one next step each.
The pipeline's first four stages as columns, from discovered to pain confirmed; cards carry knowledge and communication labels such as assumed, scheduled, replied and stopped.
The pipeline: the column is the stage, the labels are derived communication state.

Architecture

  1. 01

    App

    TanStack Start, React

    • research queue
    • pipeline
    • prospect workspace
  2. 02

    Server functions

    signed-in user only

    • research and stage rules
    • guarded website reader
    • shared send policy
  3. 03

    Postgres

    Supabase, RLS on every table

    • workspace isolation
    • evidence and hypothesis rules
    • cancellation triggers
  4. 04

    External

    Google Places · websites · Resend

    • search
    • read through the guard
    • sending and delivery events
  5. 05

    Public endpoints

    webhook · unsubscribe · processing

    • signed, replay-safe webhook
    • secret-guarded processing

Research records belong to a workspace. Row-level security checks membership on every table, and composite foreign keys keep each channel, piece of evidence, hypothesis and opportunity inside its business's workspace.

The sending tables stay scoped per user. Where they meet the research model, a trigger checks that the contact's owner is a member of the business's workspace.

External services are called from the server only: Google Places for search, business websites through the request guard, Resend for sending and delivery events.

Key decisions & trade-offs

Evidence and assumptions are different tables, not a flag on one: an observation can't be edited into a guess, and a hypothesis can't exist without one.

Rules exist twice: as pure TypeScript policies that give a clear reason before anything is written, and in Postgres (constraints, triggers and functions) as the backstop for every writer.

One record per business, shared by projects. Evidence belongs to the business, so research done once serves every project; hypotheses and stages belong to one project.

Cancellation lives in the database as triggers on the status change, so every path that stops a contact (the app, the webhook, the unsubscribe page) cancels pending email the same way.

A business's hypotheses: a rejected one, crossed out with its rejection note, and an assumed one with confirm and reject actions, each listing the evidence it rests on.
Hypotheses rest on listed evidence; a rejected one stays on record, crossed out.
A business's outreach panel: the contact has replied, and the activity shows the sent email, the reply recorded and the follow-up cancelled because of it.
A recorded reply, and the follow-up it cancelled.

Hardest problem

Keeping an assumption from turning into a fact. It could happen on screen, in the database or in what gets sent, so the separation exists in all three: distinct treatments in the interface, separate tables and client-only confirmation in Postgres, and a workflow that suggests asking before offering.

A business's research map: three observed pieces of evidence linked to one confirmed hypothesis and the opportunity built on it, above the evidence list with source pages.
The research map and evidence: observed, assumed and confirmed, each drawn differently.

Reliability engineering

The website reader is the system's only open-ended outbound request, so it's guarded hop by hop: private, loopback, link-local and metadata ranges are blocked for IPv4 and IPv6, every resolved address must be public, and responses must be HTML.

Background processing isolates each email: a failure marks that one email failed and the batch continues. An email stuck in sending is failed for review, never re-sent.

Migrations are additive and safe to run more than once; the database test harness applies every research-model migration twice to prove it.

Testing & migration

393 unit tests, 143 database integration tests and 13 SQL test files pass against a local database rebuilt from the migrations.

The SQL tests try to break the research rules directly: a hypothesis without evidence, evidence from another business or workspace, a confirmation from a system source or without a note, a status written around the functions.

The backend moved to a new Supabase project with accounts, IDs and data kept one-to-one, and policies, triggers and functions compared.

Current state / Next iteration

Current state

Deployed at app.studiosajtova.net as a private, sign-in-only application: the production build carries the research model, projects, the research queue, the pipeline and the prospect workspace.

Production runs on its own infrastructure with signed delivery events and an active scheduled processing job.

In progressDelivery of a scheduled email hasn't been verified end to end in production.

In progressWorkspaces are personal: the schema leaves room for teams, but there are no team or invitation features.