DEV Community: gyani

The four-line cron that decides who falls in love (in my dating app)

gyani — Wed, 27 May 2026 06:54:31 +0000

I shipped a dating app five months ago. The matching engine is one Postgres function, a 100-line edge function, and a launchd job on my desk that hits a route every hour. No queue, no worker, no fancy ML stack. Here is the whole thing in order, and the small disaster that taught me to move the cron off Vercel.

What a "match" actually is

In most dating apps a match is a mutual swipe. In ours a match is a row in a suggested_matches table with a score above a threshold. Two profiles, one float in [0, 1], and a reason that gets shown to both sides.

The pipeline that creates that row is short.

launchd (hourly, on my Mac)
   |
   v
GET /api/cron/generate-matches  (Next.js route, bearer-guarded)
   |
   v
Supabase Edge Function  (Deno, batches users)
   |
   v
pgvector ANN  (top 100 candidates per user, cosine over embedded prompts)
   |
   v
Linear scorer  (four hand-weighted features over the candidate set)
   |
   v
INSERT into suggested_matches  (above threshold only)

Five steps. The interesting line is the rerank.

The candidate generation step (and why I let pgvector do it)

Each user writes a small set of prompt responses on onboarding. We embed those responses with a single embedding call. That vector is one row in vibe_profiles.

Generating candidates for one user is then literally:

SELECT user_id, embedding <=> $1 AS cosine_distance
FROM vibe_profiles
WHERE user_id <> $1_user_id
  AND completed_at IS NOT NULL
  AND intent_overlap($1_intents, intents) > 0
ORDER BY embedding <=> $1
LIMIT 100;

<=> is pgvector's cosine distance operator. Smaller is closer. intent_overlap is a Postgres function that returns the size of the intersection between two intent arrays (relationship, friendship, community).

I do not run ANN search myself. I do not pre-cluster. I do not maintain a separate vector store. pgvector handles the index, the operator, the query plan, the lot. The whole "candidate generation" layer that other dating apps build entire microservices for is one ORDER BY clause.

This was the first decision that surprised me about how cheap the whole thing turned out to be.

The rerank step is four weighted features

Cosine alone is a good first pass and a bad final answer. Two profiles can be vector-near because both write reflectively and recurse on the same word, even if their actual lives have no overlap. So the top-100 candidates get rescored.

The rescorer is a linear function over four features, each in [0, 1]:

function vibeScore(seed: Profile, cand: Profile): number {
  const sim    = 1 - cosineDistance(seed.vec, cand.vec);
  const intent = intentOverlap(seed.intents, cand.intents);
  const cad    = cadenceMatch(seed.cadence, cand.cadence);
  const geo    = geoFit(seed.geo, cand.geo);

  return 0.55 * sim
       + 0.20 * intent
       + 0.15 * cad
       + 0.10 * geo;
}

That is the whole matcher.

Some notes on the weights:

sim carries the most weight because the prompt embedding is doing the real semantic work. The other three are guards.
intent is binary-ish in practice: if you are here for community and I am here for a relationship, the overlap is small and the score collapses.
cad (cadence) is a derived feature from how long a user takes to write a single prompt response. It is a very weak proxy for "how this person uses written language", but it correlates surprisingly well with whether a thread between two users sustains past day three. Worth its 15%.
geo is intentionally last and intentionally small. Most users care less about distance than they tell themselves they do, and weighting it more produces matches that are geographically convenient and texturally identical.

I tuned these by hand against the first ~50 matches that produced sustained threads, not by training a model. The set was too small for anything else. I will probably keep it that way until the set is too big for me to read in an afternoon, and even then I will resist.

The insert step is two lines

const above = scored.filter(s => s.score >= 0.45);
await sb.from("suggested_matches").upsert(above);

Threshold 0.45 was empirically the floor below which users stopped reaching out. There is no clever pruning beyond that. Upsert handles the case where the same pair gets surfaced by both directions of the cron in the same window.

The cron is where I burned a day

This is the part that humbled me.

When I wrote the Vercel cron entry, I set the schedule to 0 * * * * (every hour at the top of the hour). The Vercel CLI accepted it locally. The build then rejected it with a quiet error because hourly crons are not on the Hobby plan. Worse, the rejection blocked the deploy. Every subsequent push hung in the build queue with a confusing error. I had a stack of essays sitting in PRs that I could not figure out why were not landing.

I burned half a day before I tracked it down. The fix in the end was two parts:

Revert the Vercel cron to daily (0 0 * * *) so deploys flow again. Keep the function exactly as it is.
Trigger the function from my own machine, hourly, via launchd:

   # scripts/matches_hourly.sh
   curl -X GET \
     -H "Authorization: Bearer $INTERNAL_CRON_SECRET" \
     https://byvibration.com/api/cron/generate-matches

   <!-- ~/Library/LaunchAgents/com.byvibration.matches-hourly.plist -->
   <key>StartCalendarInterval</key>
   <dict><key>Minute</key><integer>0</integer></dict>

The Vercel daily cron stays as a fallback for when the Mac is off. The hourly cadence comes from my own machine.

This feels janky in writing. It is fine in practice. A launchd entry on a Mac that is plugged in and caffeinated is more reliable than a Vercel cron on the free tier, and crucially it does not block deploys. The whole story of moving a cron off a hosted platform took thirty minutes, and the only thing it required was admitting that "real" infrastructure is not always the one with the prettier dashboard.

What I took from the build

Three things stayed with me after this pipeline landed.

The first is that the matcher is much smaller than people assume. Four features and a vector op. The intelligence is in the prompts the user writes, not in the math the engine does on top of them. If your matching layer is a regression model with 80 features, you are matching on noise.

The second is that cosine + a tiny linear rerank gets you a long way before you need to reach for anything heavier. The temptation to put a transformer-shaped thing in the rerank is real and almost always premature. Cosine over good prompt embeddings is already doing more lifting than any small model you would slot in.

The third is that you should put the cron where your deploys do not have to talk to it. The amount of incidental fragility you remove by detaching scheduled jobs from your hosting platform is genuinely surprising.

I work on byvibration, a dating and friendship app that matches by what people write, not by photos. The whole matcher described above is in the soulmate-core repo (MIT, 65 passing tests). If any of this resonates and you want to see how the four-feature rerank reads on real prompts, that is what the live site does.

How a photo-blind dating engine actually ranks people (the TypeScript)

gyani — Tue, 26 May 2026 07:08:27 +0000

Last post I argued that the matcher in our dating app cannot read photos because the TypeScript types make it impossible. A few people asked the obvious follow-up. If the matcher never sees a face, what does it see, and how does it decide who you should meet this week?

This post is that. Code samples, vector math, the one heuristic that does most of the work, and the three things we explicitly chose not to do. Repo is at github.com/donnowyu/soulmate-core, MIT.

The thing the matcher actually sees

A profile, in the eyes of the ranker, is this:

type Profile = {
  prompts: PromptAnswers;   // five short text answers
  voice: VoiceTranscript;   // ~30s recording, kept as text
  intent: Intent;           // 'friendship' | 'relationship' | 'community'
  meta: ProfileMeta;        // age band, language, city, locale
};

No photo field. No height. No income. No "tags." The strongest input by mass is the prompts plus the voice transcript, which together produce somewhere between 800 and 2,500 tokens of free-form text about how this person actually thinks.

That text is the matching substrate. Everything downstream is a function of it.

Step 1: turn text into a vector

We embed the concatenated prompts-plus-voice into a fixed-size vector using a text embedding model. The exact provider does not matter much. We use OpenAI's text-embedding-3-small (1536 dims) because it is cheap, multilingual, and good enough that the rest of the system survives provider churn.

// soulmate-core/src/embed.ts
export async function embedProfile(p: Profile): Promise<Vector> {
  const text = formatForEmbedding(p);
  const { data } = await openai.embeddings.create({
    model: "text-embedding-3-small",
    input: text,
  });
  return data[0].embedding as Vector;
}

function formatForEmbedding(p: Profile): string {
  return [
    ...Object.values(p.prompts),
    p.voice.text,
  ].filter(Boolean).join("\n\n");
}

The vector is what gets stored in Postgres, in a column typed vector(1536) thanks to pgvector. The profile row also stores the prompts and the voice transcript for display, but the matcher reads the vector and only the vector. Whatever else lives on the row is not in the function signature, so the compiler cannot accidentally let it leak in.

Step 2: find candidates with pgvector

Given a viewer with embedded vector v, the candidate query is a cosine-distance ANN lookup, filtered by intent overlap and a completed-profile gate:

SELECT id, embedding <=> $1 AS distance
FROM profiles
WHERE id != $2
  AND completed_at IS NOT NULL
  AND $3 = ANY(intents)
  AND id NOT IN (SELECT target_id FROM blocks WHERE actor_id = $2)
ORDER BY embedding <=> $1
LIMIT 100;

<=> is the pgvector cosine-distance operator. The index is an HNSW on the embedding column so that "100 nearest" runs in milliseconds even at 100k+ profiles. Smaller-distance is more similar, since cosine-distance is 1 - cosine-similarity and the operator returns the distance form.

Two things to notice. First, the SQL itself reads no photo data. There is no photo table in this join. Second, the candidate set is bounded to 100. The ranker never sees more.

Step 3: rank the 100 with a more expensive signal

Cosine distance on embeddings is the cheap pass. It is right about taste, off about intent depth. Two people can write similarly and want very different things. So we re-rank the 100 with a second function that does not call an LLM but does look at structured signals the embedding tends to flatten.

// soulmate-core/src/rank.ts
export function rank(viewer: Profile, candidate: Profile): number {
  const text = textSim(viewer, candidate);              // 0..1
  const intent = intentOverlap(viewer, candidate);      // 0..1
  const energy = energyMatch(viewer, candidate);        // 0..1
  const cadence = cadenceMatch(viewer, candidate);      // 0..1

  return (
    text * 0.55 +
    intent * 0.25 +
    energy * 0.12 +
    cadence * 0.08
  );
}

textSim is the cosine similarity reconstructed from the distance returned by Postgres. intentOverlap weighs whether both sides want the same kind of connection (friendship, relationship, community), and how strongly. energyMatch and cadenceMatch are small heuristics derived from how much text the person wrote and how fast they answer messages historically. They mostly catch the case where two people are similar on substance but operate on incompatible rhythms.

The weights are not fitted. They are intuitions we did not have data to fit yet, and we kept them in code so any future change is a real diff and not a parameter twiddle that nobody notices. When we have enough signal to fit them, we will, and that PR will be reviewable in one page.

The function returns one float. We pick the top 5 above a 0.45 threshold for the weekly batch. If fewer than 5 cross the threshold, we send fewer. We do not pad.

What we explicitly did not do

Three things kept coming up in design review and we kept choosing not to.

We did not build a feed. There is no infinite-scroll candidate stream in this product. The weekly batch is the whole surface. The argument for a feed is engagement; we are intentionally trading engagement for a different shape of behavior, the one where the user opens the app rarely and deliberately.

We did not let the matcher see photos, not even as a tiebreaker. We considered the version where photos enter at rank time with a small weight, and rejected it for the obvious type-system reason and the less obvious behavioral one: as soon as the matcher can see faces, the production data collection of "what humans clicked on" starts encoding face preference into the ranker even if no explicit feature does. The cleanest defense is to make the photo bytes literally unreachable from the function. The compiler is the policy.

We did not put an LLM in the ranker. The temptation is real, especially since we are already embedding text. We resisted because an LLM in the loop makes the function opaque in a way that the four-feature linear combination is not. If a match is wrong, we can read the four numbers. We cannot read an LLM the same way.

Why this matters outside dating

The pattern, embedding-plus-pgvector-plus-small-linear-rerank, is good for any product where the primary signal is "how this user thinks" rather than "what this user clicked on." Documentation search, similar-issue triage, mentor matching, study-group formation. The dating context is just the one where the cost of being wrong is most visible to the user.

If you want to read the full implementation, it is at github.com/donnowyu/soulmate-core, all of it under MIT. The vector math is in src/rank.ts and src/embed.ts; the SQL is in db/migrations/. Tests cover the rank function and the edge cases of empty profiles, missing voices, and intent mismatch.

The product that wraps this engine is byvibration.com. It is the same idea taken all the way to a working app: you write, the engine reads how you think, you meet by mind not by face.

I work on byvibration. The framework above stands on its own; the product is one way to live inside it.---
title: "The four-line cron that decides who falls in love (in my dating app)"
published: true
canonical_url: https://byvibration.com/essays/why-matching-layer-is-physically-blind

tags: typescript, postgres, webdev, supabase

What a "match" actually is

The pipeline that creates that row is short.

launchd (hourly, on my Mac)
   |
   v
GET /api/cron/generate-matches  (Next.js route, bearer-guarded)
   |
   v
Supabase Edge Function  (Deno, batches users)
   |
   v
pgvector ANN  (top 100 candidates per user, cosine over embedded prompts)
   |
   v
Linear scorer  (four hand-weighted features over the candidate set)
   |
   v
INSERT into suggested_matches  (above threshold only)

Five steps. The interesting line is the rerank.

The candidate generation step (and why I let pgvector do it)

Each user writes a small set of prompt responses on onboarding. We embed those responses with a single embedding call. That vector is one row in vibe_profiles.

Generating candidates for one user is then literally:

SELECT user_id, embedding <=> $1 AS cosine_distance
FROM vibe_profiles
WHERE user_id <> $1_user_id
  AND completed_at IS NOT NULL
  AND intent_overlap($1_intents, intents) > 0
ORDER BY embedding <=> $1
LIMIT 100;

This was the first decision that surprised me about how cheap the whole thing turned out to be.

The rerank step is four weighted features

The rescorer is a linear function over four features, each in [0, 1]:

function vibeScore(seed: Profile, cand: Profile): number {
  const sim    = 1 - cosineDistance(seed.vec, cand.vec);
  const intent = intentOverlap(seed.intents, cand.intents);
  const cad    = cadenceMatch(seed.cadence, cand.cadence);
  const geo    = geoFit(seed.geo, cand.geo);

  return 0.55 * sim
       + 0.20 * intent
       + 0.15 * cad
       + 0.10 * geo;
}

That is the whole matcher.

Some notes on the weights:

sim carries the most weight because the prompt embedding is doing the real semantic work. The other three are guards.
intent is binary-ish in practice: if you are here for community and I am here for a relationship, the overlap is small and the score collapses.
cad (cadence) is a derived feature from how long a user takes to write a single prompt response. It is a very weak proxy for "how this person uses written language", but it correlates surprisingly well with whether a thread between two users sustains past day three. Worth its 15%.
geo is intentionally last and intentionally small. Most users care less about distance than they tell themselves they do, and weighting it more produces matches that are geographically convenient and texturally identical.

The insert step is two lines

const above = scored.filter(s => s.score >= 0.45);
await sb.from("suggested_matches").upsert(above);

The cron is where I burned a day

This is the part that humbled me.

I burned half a day before I tracked it down. The fix in the end was two parts:

Revert the Vercel cron to daily (0 0 * * *) so deploys flow again. Keep the function exactly as it is.
Trigger the function from my own machine, hourly, via launchd:

   # scripts/matches_hourly.sh
   curl -X GET \
     -H "Authorization: Bearer $INTERNAL_CRON_SECRET" \
     https://byvibration.com/api/cron/generate-matches

   <!-- ~/Library/LaunchAgents/com.byvibration.matches-hourly.plist -->
   <key>StartCalendarInterval</key>
   <dict><key>Minute</key><integer>0</integer></dict>

The Vercel daily cron stays as a fallback for when the Mac is off. The hourly cadence comes from my own machine.

What I took from the build

Three things stayed with me after this pipeline landed.

65 deterministic tests for a matching engine, no database, no fixtures

gyani — Tue, 19 May 2026 07:00:55 +0000

I write the matching engine for a small dating and friendship app. The engine is open-source (github.com/donnowyu/soulmate-core, MIT). The hardest thing about working on it was not the math. It was that for the first three weeks I could not refactor anything because I had no way to know whether my changes had broken the ranking.

This post is the testing pattern I landed on. 65 deterministic tests. No database. No fixtures loaded from disk. No live embeddings. The whole suite runs in 1.8 seconds and tells me, in plain language, whether any of fifteen ranking invariants just regressed.

If you maintain anything that takes a query and returns a sorted list (search, recsys, matching, ranking, RAG retrieval), the shape of this should transfer.

The problem with the obvious test setup

The first version of the test suite was the obvious one. Seed a fake Postgres, insert 200 fake profiles, compute embeddings with the real model, ask the engine to rank them, snapshot the top 20.

Three problems showed up within a week.

It was slow. Real embedding calls plus database round trips meant ~40 seconds for the full suite. I stopped running tests before commits.

It was non-deterministic. The embedding model was probabilistic enough that the same input produced subtly different vectors across runs, which meant the snapshot diff was always noisy. I learned to ignore the diff. Predictably, the day a real regression slipped in I ignored that diff too.

And the failures, when they came, did not tell me anything. A snapshot would change. I would stare at a list of 20 user IDs and try to remember what each one was supposed to represent. The test had nothing to say about why the new order was wrong, only that it was different.

What deterministic tests look like for a matching engine

The flip was to stop testing the system end-to-end and start testing each invariant the ranker is supposed to satisfy, one at a time, with the smallest possible synthetic input.

Here is one of the tests, verbatim.

test("intent overlap dominates lexical similarity", () => {
  const candidates = [
    profile({ intent: "relationship", text: "I like long walks" }),
    profile({ intent: "friendship",   text: "I like long walks and hiking" }),
  ];
  const viewer = profile({ intent: "relationship", text: "I like hiking" });

  const ranked = rank(viewer, candidates);

  expect(ranked[0].intent).toBe("relationship");
});

There is no database. profile is a one-line helper that builds a Profile object with sensible defaults. rank is the real function from the engine. The vectors are synthetic, produced by a tiny deterministic embedder (a stable hash of token bigrams projected into 128 dimensions), not the live model.

The test reads, in English, as a sentence: "When two candidates have similar text but different intents, the one with matching intent should win." When that test fails, the diagnostic is not "snapshot differs." It is "rank()[0].intent was 'friendship', expected 'relationship'." That tells you exactly which invariant broke.

There are 65 of these. Each one is roughly four to ten lines. Together they cover the fifteen ranking invariants the matcher is supposed to hold, with several tests per invariant for edge cases (empty fields, very short text, language mismatch, intent set to community, etc.).

How to keep them deterministic without faking the math

The trick is the deterministic embedder. It is about thirty lines. It tokenizes the input the same way the real pipeline does, then projects each token into a fixed 128-dimensional vector using a stable hash. Two inputs with identical tokens produce identical vectors. Two inputs that share most tokens produce vectors with a high cosine similarity, just like a real embedder would.

function tinyEmbed(text: string): Float32Array {
  const v = new Float32Array(128);
  for (const tok of tokenize(text)) {
    const h = stableHash(tok);
    for (let i = 0; i < 128; i++) {
      v[i] += ((h >> i) & 1) ? 1 : -1;
    }
  }
  return normalize(v);
}

This is not the right embedder for production. It cannot tell that "happy" and "joyful" are similar. But for testing the ranker, it is exactly right. The ranker should care about intent overlap, language match, profile-completeness, and recency before it cares about the small nuance the real embedder adds. The tests assert those four things hold even with the dumb embedder. If a refactor accidentally makes the engine depend on the embedder's semantic nuance for a basic invariant, the test catches it.

Why no database

Every test runs against in-memory objects. The engine accepts a viewer profile and a list of candidate profiles, both as plain TypeScript values, and returns a ranked list. The Postgres + pgvector layer that production uses is a separate module that calls into this pure function. The tests do not touch it.

This is the most expensive design decision in the whole repo. It means the ranker cannot do anything fancy with the database (no clever joins, no SQL-side scoring). Every signal it uses must travel through the function signature. In exchange the tests run in 1.8 seconds and have no flakiness. I have come back to this tradeoff many times. I keep choosing the tests.

What this gets you

Refactor confidence. I rewrote the rerank step three times in two months. Each rewrite, I ran the suite. If the tests passed, the rerank was at least as good as the previous version on every invariant we care about. If a test failed, the message told me exactly which invariant I had broken.

Honest documentation. The test file is the most useful documentation of how the matcher behaves. New contributors read the tests first. The invariants are not in a wiki that will go stale, they are executable.

A floor under quality. I cannot make a change that ships a worse ranker by accident. The bar is "all 65 invariants still hold." Below that bar, CI is red.

The three things this does not test

Snapshot tests are still useful for catching subtle changes in ranking order on real data. I have a separate test file with two of those, gated on a RUN_INTEGRATION=1 env var, that uses real embeddings and a small fixture set. They are slow and they are noisy. They are not the suite I run on every commit.

Performance. The 65 tests do not check that ranking is fast. There is a separate benchmark file that runs nightly.

Calibration. The tests check that the ranker orders correctly. They do not check that the score thresholds match what should be a "good match" for users. That is a product question and the answer comes from user data, not from invariant tests.

The pattern, generalized

If you maintain a system that takes a query plus a candidate set and returns a sorted list, the pattern is:

List the invariants the ranker should satisfy, in English. "When the user explicitly excludes a language, no candidate of that language should appear in the top N." Write that down.
For each invariant, build a minimal synthetic input that exercises only it.
Use a deterministic stand-in for any probabilistic component (embeddings, model calls). Make sure the stand-in is dumb enough that the invariant still has to be satisfied by the ranker, not by accident.
Skip the persistence layer entirely. Treat the ranker as a pure function.
Write the assertion in terms of the invariant, not in terms of which specific items came back in which order. "The top result should have intent X" not "the top result should be ID 47."

The reward is a test suite that tells you, in English, what you just broke. After enough refactors that survived it, the suite starts to feel like a colleague who has read every line of the engine and will let you know the moment you do something stupid.

The full engine, all 65 tests, and the tiny deterministic embedder are at github.com/donnowyu/soulmate-core. If you ever want to see one specific test, tests/rank.invariants.test.ts is the file. The engine ships on byvibration.com, which is a small relationship and friendship app that genuinely cannot read your photos.---
title: 65 deterministic tests for a matching engine, no database, no fixtures
published: true
canonical_url: https://byvibration.com/essays/why-matching-layer-is-physically-blind

tags: typescript, testing, opensource, webdev

If you maintain anything that takes a query and returns a sorted list (search, recsys, matching, ranking, RAG retrieval), the shape of this should transfer.

The problem with the obvious test setup

The first version of the test suite was the obvious one. Seed a fake Postgres, insert 200 fake profiles, compute embeddings with the real model, ask the engine to rank them, snapshot the top 20.

Three problems showed up within a week.

It was slow. Real embedding calls plus database round trips meant ~40 seconds for the full suite. I stopped running tests before commits.

What deterministic tests look like for a matching engine

The flip was to stop testing the system end-to-end and start testing each invariant the ranker is supposed to satisfy, one at a time, with the smallest possible synthetic input.

Here is one of the tests, verbatim.

test("intent overlap dominates lexical similarity", () => {
  const candidates = [
    profile({ intent: "relationship", text: "I like long walks" }),
    profile({ intent: "friendship",   text: "I like long walks and hiking" }),
  ];
  const viewer = profile({ intent: "relationship", text: "I like hiking" });

  const ranked = rank(viewer, candidates);

  expect(ranked[0].intent).toBe("relationship");
});

How to keep them deterministic without faking the math

function tinyEmbed(text: string): Float32Array {
  const v = new Float32Array(128);
  for (const tok of tokenize(text)) {
    const h = stableHash(tok);
    for (let i = 0; i < 128; i++) {
      v[i] += ((h >> i) & 1) ? 1 : -1;
    }
  }
  return normalize(v);
}

Why no database

What this gets you

A floor under quality. I cannot make a change that ships a worse ranker by accident. The bar is "all 65 invariants still hold." Below that bar, CI is red.

The three things this does not test

Performance. The 65 tests do not check that ranking is fast. There is a separate benchmark file that runs nightly.

The pattern, generalized

If you maintain a system that takes a query plus a candidate set and returns a sorted list, the pattern is:

List the invariants the ranker should satisfy, in English. "When the user explicitly excludes a language, no candidate of that language should appear in the top N." Write that down.
For each invariant, build a minimal synthetic input that exercises only it.
Use a deterministic stand-in for any probabilistic component (embeddings, model calls). Make sure the stand-in is dumb enough that the invariant still has to be satisfied by the ranker, not by accident.
Skip the persistence layer entirely. Treat the ranker as a pure function.
Write the assertion in terms of the invariant, not in terms of which specific items came back in which order. "The top result should have intent X" not "the top result should be ID 47."

The full engine, all 65 tests, and the tiny deterministic embedder are at github.com/donnowyu/soulmate-core. If you ever want to see one specific test, tests/rank.invariants.test.ts is the file. The engine ships on byvibration.com, which is a small relationship and friendship app that genuinely cannot read your photos.---
title: How a photo-blind dating engine actually ranks people (the TypeScript)
published: true
canonical_url: https://byvibration.com/essays/why-matching-layer-is-physically-blind

tags: typescript, webdev, postgres, ai

This post is that. Code samples, vector math, the one heuristic that does most of the work, and the three things we explicitly chose not to do. Repo is at github.com/donnowyu/soulmate-core, MIT.

The thing the matcher actually sees

A profile, in the eyes of the ranker, is this:

type Profile = {
  prompts: PromptAnswers;   // five short text answers
  voice: VoiceTranscript;   // ~30s recording, kept as text
  intent: Intent;           // 'friendship' | 'relationship' | 'community'
  meta: ProfileMeta;        // age band, language, city, locale
};

That text is the matching substrate. Everything downstream is a function of it.

Step 1: turn text into a vector

// soulmate-core/src/embed.ts
export async function embedProfile(p: Profile): Promise<Vector> {
  const text = formatForEmbedding(p);
  const { data } = await openai.embeddings.create({
    model: "text-embedding-3-small",
    input: text,
  });
  return data[0].embedding as Vector;
}

function formatForEmbedding(p: Profile): string {
  return [
    ...Object.values(p.prompts),
    p.voice.text,
  ].filter(Boolean).join("\n\n");
}

Step 2: find candidates with pgvector

Given a viewer with embedded vector v, the candidate query is a cosine-distance ANN lookup, filtered by intent overlap and a completed-profile gate:

SELECT id, embedding <=> $1 AS distance
FROM profiles
WHERE id != $2
  AND completed_at IS NOT NULL
  AND $3 = ANY(intents)
  AND id NOT IN (SELECT target_id FROM blocks WHERE actor_id = $2)
ORDER BY embedding <=> $1
LIMIT 100;

Two things to notice. First, the SQL itself reads no photo data. There is no photo table in this join. Second, the candidate set is bounded to 100. The ranker never sees more.

Step 3: rank the 100 with a more expensive signal

// soulmate-core/src/rank.ts
export function rank(viewer: Profile, candidate: Profile): number {
  const text = textSim(viewer, candidate);              // 0..1
  const intent = intentOverlap(viewer, candidate);      // 0..1
  const energy = energyMatch(viewer, candidate);        // 0..1
  const cadence = cadenceMatch(viewer, candidate);      // 0..1

  return (
    text * 0.55 +
    intent * 0.25 +
    energy * 0.12 +
    cadence * 0.08
  );
}

The function returns one float. We pick the top 5 above a 0.45 threshold for the weekly batch. If fewer than 5 cross the threshold, we send fewer. We do not pad.

What we explicitly did not do

Three things kept coming up in design review and we kept choosing not to.

Why this matters outside dating

The product that wraps this engine is byvibration.com. It is the same idea taken all the way to a working app: you write, the engine reads how you think, you meet by mind not by face.

I work on byvibration. The framework above stands on its own; the product is one way to live inside it.

I shipped 19 SEO essays in 12 days from a single Next.js page file

gyani — Sat, 16 May 2026 07:22:48 +0000

I have been quietly running an experiment for the last twelve days. I wanted to know how minimal the publishing pipeline for a real SEO essay corpus can be if I gave up every CMS, every markdown loader, and every static-site generator that pretended to be lightweight but turned out to require its own ecosystem.

The answer ended up being one Next.js page file, one slug allowlist, one sitemap function, and a postscript script that probes the live URL after deploy. Nineteen essays are live as I write this, all ranked individually in sitemap.xml, all internally linked, all with stable URLs and zero rebuild surprises. The whole pipeline is small enough that a human in a hurry can read it in five minutes.

This post is the file. Not a tutorial about the file. The actual structure.

The shape

The route lives at apps/web/app/essays/[slug]/page.tsx. Everything an essay needs is in two arrays in that file plus one small allowlist file next to it.

// apps/web/app/essays/[slug]/page.tsx

import { notFound } from 'next/navigation';
import { ESSAY_SLUGS } from '@/lib/essay-slugs';

export const dynamic = 'force-static';
export const dynamicParams = false;

type Essay = {
  slug: (typeof ESSAY_SLUGS)[number];
  title: string;
  publishedAt: string;
  body: string;
};

const ESSAYS: Essay[] = [
  {
    slug: 'why-matching-layer-is-physically-blind',
    title: 'Why the matching layer is physically blind, on purpose',
    publishedAt: '2026-05-08',
    body: `
      ... essay prose here, plain markdown-ish strings ...
    `,
  },
  // ... 18 more
];

export function generateStaticParams() {
  return ESSAY_SLUGS.map((slug) => ({ slug }));
}

export default function EssayPage({ params }: { params: { slug: string } }) {
  const essay = ESSAYS.find((e) => e.slug === params.slug);
  if (!essay) notFound();
  return <Article essay={essay} />;
}

ESSAY_SLUGS is a const tuple in its own file so the type system catches typos at compile time. Slugs in the renderer that are not in the allowlist will not type-check; slugs in the allowlist with no renderer entry will hit notFound() and return a real 404.

// apps/web/lib/essay-slugs.ts
export const ESSAY_SLUGS = [
  'why-matching-layer-is-physically-blind',
  'letters-mode-is-mercy',
  'why-dating-apps-feel-exhausting',
  // ... 16 more
] as const;

That is the single source of truth for the corpus. Sitemap reads it. Index page reads it. Renderer reads it. Three callers, one list. When a new essay ships, one line in this file and one entry in the renderer is the whole diff.

Sitemap, index, internal linking

Because ESSAY_SLUGS is a typed tuple, the sitemap generator is six lines.

// apps/web/app/sitemap.ts
import type { MetadataRoute } from 'next';
import { ESSAY_SLUGS } from '@/lib/essay-slugs';

export default function sitemap(): MetadataRoute.Sitemap {
  return ESSAY_SLUGS.map((slug) => ({
    url: `https://byvibration.com/essays/${slug}`,
    lastModified: new Date(),
  }));
}

The /essays index page does the same lookup and renders a card per essay, ordered by publishedAt descending. Adding a new essay automatically promotes it to the top of the index and into the sitemap on the next deploy. There is nothing else to remember.

Internal linking is a function call inside the prose. Each essay body has a small Related block at the bottom that pulls related slugs by cluster tag (introvert cluster, friendship cluster, etc.). The cluster mapping is another tiny const next to the slug list. Total moving parts so far: three files.

The "is it actually live" probe

Vercel deploys are usually fast, but there is one failure mode that bit me hard. A page can return HTTP 200 while serving the home shell when something upstream of the renderer crashes silently. The status code lies.

To catch this, the post-deploy probe asserts three things: the page returns 200, the rendered <title> contains a stem of the slug, and the slug is present in the live sitemap.xml. If any of those fail, the deploy is treated as not-live, even on 200.

# superbot/util/essay_liveness.py
def is_live(slug: str) -> bool:
    page = httpx.get(f"https://byvibration.com/essays/{slug}", timeout=10)
    if page.status_code != 200:
        return False
    title = re.search(r"<title>([^<]+)</title>", page.text)
    if not title or not any(
        stem in title.group(1).lower() for stem in slug.split("-") if len(stem) > 3
    ):
        return False
    sitemap = httpx.get("https://byvibration.com/sitemap.xml", timeout=10).text
    return f"/essays/{slug}" in sitemap

This is the single most-useful seven-minute piece of code in the pipeline. It caught a soft-404 for me on essay number five before I noticed the slug was being silently rewritten by middleware. The fix took ten minutes; without the probe it would have taken a week of confusion about why search was not seeing the page.

What I did not build

A markdown loader. A frontmatter parser. An MDX pipeline. A CMS adapter. A headless preview environment. A content directory. A draft state machine. A separate build pipeline for content vs. application code.

Every one of those was suggested by some part of my brain along the way. None of them earned their place. The reason is honest: the corpus is small, the cost of typing prose inline is trivial, and the type checker is the only quality gate that actually catches the bugs that ship in production. The simplest model that works is the model.

The day I have one hundred essays I will probably move to a markdown directory. Until then, the file fits on one screen of any normal editor, the array is sorted by date, and I can grep my own corpus instantly.

What this looks like in practice

The cadence has been roughly one essay every fifteen hours, written in plain prose, ported into the array, slug added to the allowlist, pushed. Vercel deploys. The probe runs. The sitemap updates. Google indexes it within forty-eight hours. The internal links to the rest of the corpus stay correct because they are computed, not hand-maintained.

The unit of friction per new essay is "write the essay." Everything downstream of that is one diff against one file.

If you have an essay practice and you are intimidated by the pipeline question, this is a version of "just ship it" that has an answer. One file. One allowlist. One probe. Nineteen essays in twelve days from that pattern, with the type checker as your friend.

I would skip every CMS until you actually need one.

I work on Byvibration, where the corpus this file feeds lives. The essays index is at byvibration.com/essays.

A dating algorithm that physically cannot read photos (and why I wrote it that way)

gyani — Sat, 16 May 2026 00:44:18 +0000

A dating algorithm that physically cannot read photos (and why I wrote it that way)

gyani — Fri, 15 May 2026 15:13:14 +0000

I have been writing a connection app for a year. Last week I open-sourced the matching engine, and the only design choice I want to walk through is the one that took the longest to talk myself into: the matcher does not have access to photos. Not "it ignores them." Not "it deprioritizes them." It cannot see them. The TypeScript build fails if you try.

If you only want the punchline, here it is.

// soulmate-core/src/rank.ts
export function rank(viewer: Profile, candidate: Profile): number;

type Profile = {
  prompts: PromptAnswers;       // five short text answers
  voice: VoiceTranscript;       // ~30 sec, kept as text
  intent: Intent;               // friendship | relationship | community
  meta: ProfileMeta;            // age band, city, language, etc.
};
// no photo field. anywhere on this type.

The image bytes live in a different table, behind a different read path, behind a mutualVibe boolean. The function above has no reference to that table and no way to obtain one through normal app wiring. The constraint is enforced by the compiler.

The repo is at github.com/donnowyu/soulmate-core if you want to read along.

Why type-level, not flag-level

The natural shape of this is a feature flag. if (allow_photo_in_ranking) { ... }. Several products built on this shape. I think it is the wrong shape. Three reasons.

Flags get flipped by people who weren't in the room when the principle was set. A future engineer, looking at the engagement dashboard on a tired evening, will propose a "secondary signal" A/B test. They will be right that the metric will move. They will be wrong that what is being measured is what we said we cared about. A flag does not survive that conversation. A type signature does.
The constraint should live in the artifact, not the documentation. A README that says "do not use photos in ranking" is a memo. A type that has no photo field is a build error. Banks do not enforce referential integrity with memos.
It is honest in a way I can verify in public. The repo is open. You can look at the entry-point type and convince yourself in 60 seconds. You do not have to take my word for anything.

The cost of doing it this way

I will not pretend this was free.

The most expensive part was the data model. I had to design the schema so that the photo entity has its own service, its own access control, its own read path. The image upload pipeline never returns to the matching service. The "show me a face" step is a separate request, gated server-side on the existence of a mutualVibe row keyed by both user IDs. That is not a refactor you do in an afternoon.

The second cost was deciding what Profile should contain so that ranking still works. I tried a lot of things. The current shape (five prompts plus a transcribed voice clip plus intent metadata) is the smallest set I found that produces matches I can defend on inspection. Most of a year was spent reducing it to that.

The third cost is a soft one. There is a class of user who, on the existing apps, sorts mostly by face. They will look at this product and bounce. That is fine. They were not the users I was trying to find.

The trick of the embedding

The text answers and the voice transcript get concatenated into a single document per user. That document is embedded into a 1536-dim vector. Ranking is cosine similarity over those vectors, with two soft rerankers (ideology distance, shared-passion overlap) breaking ties.

This is not exotic. The trick is not in the math. The trick is in the input. By construction, the model has never seen a pixel. By construction, the model has no learned latent dimension that correlates with attractiveness, because nothing in the training distribution ever encoded one. The rerank loop is small enough to read.

// rerank pseudocode
const baseline = cosine(viewerEmb, candidateEmb);
const ideologyPenalty = distance(viewer.ideology, candidate.ideology);
const passionBoost   = jaccard(viewer.passions, candidate.passions);
return baseline - 0.15 * ideologyPenalty + 0.10 * passionBoost;

You can argue with the coefficients. I have. The coefficients are not the point of the post.

Why I am writing this on Dev.to

Because the type-system argument is the part of the project that is interesting to people who write code for a living, and because most of the press around "no photo dating apps" handles the question at the marketing layer, where it is much less interesting. The interesting question is whether the constraint is structural, and structural constraints are something a dev audience can read in source. I wanted that audience to be able to verify the claim without me in the room.

If you want the long-form essay version of this argument, it is on the product site at byvibration.com/essays/why-matching-layer-is-physically-blind. If you want the code, the repo link is at the top. If you want to push back on any of the choices, the comments are open and I will be in them.

I work on byvibration. The matching engine is open source. I am writing about it here because I think the type-signature framing is a transferable idea: constraints you want to honor across a long time should be expressed in the artifact, not the team's memory.---
title: A dating algorithm that physically cannot read photos (and why I wrote it that way)
published: false
canonical_url: https://byvibration.com/essays/why-matching-layer-is-physically-blind

tags: typescript, webdev, discuss, architecture