Orchestrate: journeys

A journey moves the people using your app through a sequence of touches over days or weeks: it enrolls someone when something happens (an event, a page visit, joining an audience, a trait, a date), then shows them in-app guides, sends them emails, waits, waits for something they do, and branches on what they did, while measuring a goal such as "created a deal within 14 days".

Journeys live under Journeys in the sidebar. The page has three tabs: Journeys, Emails (the email templates journeys send, see email.md) and Suppressions (addresses that are never emailed).

Concepts

Triggers

Only activity in the journey's environment counts, and only activity after the journey starts (or resumes), except for the two "enroll existing" options above.

Steps

The first step is the entry point; every step names the step that follows it (next), and a journey without a following step ends there. The builder draws the graph top to bottom, with a + between steps to insert one, branches as Yes / No columns that rejoin where both sides meet, and "Continues at …" links when a path jumps to a step drawn elsewhere.

A journey has at most 40 steps. Before it starts, Guidely checks that step ids are unique, every step it points at exists, there are no loops, every step can be reached from the first, every step has its settings, and the guides, audiences and email templates it uses exist in the project (and aren't archived). Problems are shown on the steps in the builder, and starting is refused until they're fixed.

How guide steps reach people

The SDK isn't involved: each guide step has a static audience the journey manages, named Journey · <journey> · <step>. While someone is at the step, the journey adds them to it (removing them when the step ends, or when they leave the journey for steps that don't wait); identify() already returns the audiences a person is in, so a guide that targets that audience shows to exactly the people at the step.

The step panel shows whether the guide's live version (and its draft) targets the step's audience and whether it's live in the journey's environment. Target the guide at this step adds an Audience member rule for the step's audience to the guide's draft targeting (keeping its other rules, needs Edit guides); publish the guide to make it live. Completion is read from the guide history Guidely already keeps (guide_completed / guide_dismissed); a guide the person completed before reaching the step counts as completed.

Email steps

Email steps use the project's customer email channel (Settings → Email): it must be on, with a verified sender and a postal address, or the journey won't start. Each person gets an email step's email at most once per enrollment (the send is keyed <enrollmentId>:<stepId>, so retries never send twice); people without an email trait, who unsubscribed (from everything or the template's category), bounced or were suppressed are skipped and recorded as skipped. Delivery, opens, clicks, bounces and unsubscribes come from SendGrid's event webhook. See email.md.

Enrollment rules

• Once per person (default): someone who entered never enters again.
• Again after they leave: someone can enter again once their previous run ended and the cool-down (reentryAfterHours, default 24) has passed; only activity after that counts.

Someone already in the journey is never enrolled twice. Enroll someone now on the Analytics tab enrolls one person by user id or end-user id whatever the trigger, for testing. In development and staging it needs Edit journeys; in production Start journeys (and a confirmation). Remove from journey takes someone out (same permissions).

Goal

A goal is an event, a page visit or a completed guide within N days of entering (default 14). Reaching it sets the enrollment's goalReachedAt (the time of the activity) whether the person is still in the journey or already finished it. With Leave the journey on reaching it, people who convert stop getting guides and emails (checked at least hourly). The conversion rate is people who reached the goal / people enrolled.

Analytics

The Analytics tab shows enrolled / in progress / completed / left early / failed, the goal conversion rate and median time to goal, a step funnel (reached vs completed), enrollments and conversions per day, email performance per email step (sent, delivered, opened, clicked, bounced, unsubscribed, skipped), why people left early, and the people in the journey with their current step. While a journey runs, the builder shows live counts on each step (here now, reached, done).

The worker

runJourneys() in src/server/services/journey-engine.ts runs on every outbox pass (about every 10 seconds). Each pass:

1. Enrolls: for each active journey (least recently scanned first, up to 100 a pass), it locks the journey row (FOR UPDATE SKIP LOCKED, so one worker scans a journey at a time), reads up to 500 trigger rows after the journey's scanCursor (events through the (projectId, name|customName, occurredAt) indexes, audience memberships, environment activity for traits, a text range on the trait for dates), and creates enrollments for the people the enrollment rules let in. The cursor moves to the last row read when the batch was full, otherwise to now minus a 5-minute overlap, so events that arrive a little late are still seen; re-reading the overlap is harmless because enrollments are unique per (journey, person, cycle).
2. Advances: it claims up to 200 due enrollments (nextRunAt <= now, FOR UPDATE SKIP LOCKED; a claim older than 5 minutes belongs to a dead worker and is taken over), runs each one's current step and every step that can run straight after it, and saves where it stopped and when to look again (a wait's end, a timeout, or a re-check every 10 minutes for steps that listen).

Every side effect is idempotent, so a crash between a side effect and saving the state just replays the step: audience membership is an upsert, the email is keyed per enrollment and step, and step events are unique per (enrollment, step, kind). Every save checks the claim is still the worker's, so a worker that lost its claim never overwrites newer progress. A step that throws is retried after 1 minute, 5 minutes, 30 minutes and 2 hours; after 5 failed attempts the enrollment is marked failed. Someone whose step was removed while the journey was paused leaves with the reason step_removed.

Pausing freezes everyone where they are (no one new enters; waits that end meanwhile continue on resume). Archiving takes everyone out, empties the guide-step audiences and stops the journey for good; analytics are kept.

Permissions

Every change of state (create, edit, start, pause, resume, archive, delete, targeting a guide, test enrollment, removing someone) is in the audit log.

API

All under /api/v1, with the dashboard session (see api.md):

The trigger, step and goal JSON shapes are the zod schemas in src/lib/journeys.ts (TriggerSchema, StepSchema, GoalSchema). AI assistants can read journeys over MCP with list_journeys and get_journey_status.