build.allanninal.dev

Part 1 of 7 · Onboarding guide series ~5 min read

An onboarding guide on AWS for a few dollars a month

A small business signs up more customers than anyone can hand-hold one at a time. The new user who tried the product once and never came back. The customer who got stuck on the very first setup step and quietly gave up. The trial that ran out before anyone ever showed them the feature they actually needed. Walking each new person through their first steps is the work that pays off most and slips first when the week gets busy. This post walks through the design of a small guide that greets every new customer, walks them through the right first steps, nudges gently when someone stalls, and tells the owner who is stuck — and never spams anyone.

Key takeaways

  • Three sources for new customers: a signup webhook, a Drive sheet, and an inbox forwarding lane.
  • Every customer ends in one of four moves on each tick: on track, next step due, gentle nudge, or flag to owner.
  • Per-plan step plans: a starter plan gets welcome at day 0, setup at day 2, a check-in at day 6.
  • Messages adapt to pace, respect quiet hours and weekends, and carry a one-click done link.
  • Designed on AWS for about $2.10/month at typical small-business volume.

The whole system on one page

Before any code, here’s the shape of what we’re designing.

System architecture: three sources, three pieces inside AWS At the top, three external boxes in a row. Far left, "New customers" — a signup webhook from your app, a Google Drive sheet you can fill in by hand, and an inbox forwarding lane that all add newly signed-up customers to the onboarding list, each row holding the customer name, email, plan, signup date, the current step, and which steps are done. Centre, "Rules and voice" — a Drive folder with a rules doc covering the per-plan step plans, the timing windows, the owner who gets flags, and the quiet hours, plus a voice doc with the message templates for each step. Far right, "Customers and owner" — the new customer who receives the friendly step messages and nudges, and the internal owner who gets a flag when someone is stuck. Each connects via an arrow to the AWS account container below. New customers have an outgoing arrow into AWS. Rules and voice feed in to ground every message. Customers receive step messages that carry the next step, a short how-to, and a one-click done link; the owner receives the flag with full context. Inside the AWS account are three components in a row, mirroring the layout above. On the left, the Signup intake — receives customers from each source, normalizes the row, and writes the cleaned customer into the list. In the middle, the Guide — runs daily; reads the onboarding list; computes days-since-signup and which steps are done per customer; picks one of four moves: on track, next step due, gentle nudge, or flag to owner. On the right, the Sender — sends the message via email, respects quiet hours and weekends, and tracks which steps each customer has finished. Internal arrows flow left to right. A note at the bottom reads: the pace adapts to each customer — the guide never drips an endless sequence and never spams. New customers webhook, sheet, inbox Rules and voice step plans, owners, templates Customers + owner where messages land customers in grounds step message + done link AWS account Signup intake normalize, enroll, add to the list Guide picks one of four: on track, due, nudge, flag Sender friendly email, respects quiet hours customer move The pace adapts to each customer — the guide never drips an endless sequence and never spams.
Fig 1. Three sources outside, three pieces inside AWS. Customers flow in from a signup webhook, a Drive sheet, and an inbox forwarding lane. The Guide runs daily and picks one of four moves. The Sender emails the right step to the right person at the right time.

What you set up once (the outside)

  • New customers. A Google Sheet in a Drive folder, one row per customer: name, email, plan (starter, pro, team), signup date, the current step, which steps are done, and a paused flag. New customers usually flow in straight from your app via two of the lanes covered in Part 2 — a signup webhook (your app calls a small endpoint the moment someone signs up) and an inbox-forwarding lane (forward the welcome email to a dedicated address and the guide proposes a row for one-tap approval). The sheet itself is the third lane, for the customers you add by hand.
  • A rules folder. Two short Google Docs in a Drive folder. The rules doc covers the step plan for each plan — which steps there are and how many days after signup each one should land. A starter plan typically gets welcome at day 0, setup at day 2, a check-in at day 6; a pro plan gets a longer plan with an extra feature tour. The doc also lists the owner who gets flagged when a customer is stuck, the quiet hours, and any holiday days to skip. The voice doc holds one message template per step — what the welcome, the setup help, the check-in, and the gentle nudge actually say.
  • Customers and owner. The new customer receives the step messages and nudges. The internal owner receives a flag when a customer gets stuck. Messages land with the next step, a short how-to, a link into the product, and a one-click “I’ve done this” link so the customer can mark a step done without logging a ticket.

What runs on every tick (the inside)

  • The signup intake. Three sources feed the list. The signup webhook is the main one — your app posts a new customer to a small endpoint the moment they sign up, and the row is enrolled at once. The Drive sheet is the canonical store you can also edit by hand. And the inbox forwarding lane lets anyone forward a welcome email to welcome@your-company.com; the guide uses Bedrock Haiku 4.5 to read the name, email, and plan, then drops a one-tap approval card in Slack before the row is added.
  • The guide. Runs once a day at 9am local. Reads the onboarding list. For each customer, computes days-since-signup and looks at which steps are already done. Compares against the per-plan step plan in the rules doc. Picks one of four moves. On track: nothing is due, or the customer is moving fast — do nothing. Next step due: a step’s day has arrived and it isn’t done — send the step message. Gentle nudge: a step passed its window with no progress — send one friendly reminder. Flag to owner: the final window passed and the step is still undone — tell the owner named in the rules doc so a human can reach out. The guide itself doesn’t call a model on the daily tick — the move logic is plain Python.
  • The sender. Reads the voice doc, formats the message for the chosen step, and sends it. Email goes through SES outbound. It honors quiet hours (no sends between 6pm and 8am local by default) and skips weekends and holidays. Every send writes a row in DynamoDB so the next day’s tick can tell which steps already went out. A weekly digest summarizes who finished and who’s stuck. A monthly summary writes a one-paragraph activation narrative: how many finished, where people drop off, the longest-stuck customers.

In plain words

Priya signs up for the starter plan on Monday. The same day, the guide emails her a warm welcome with the one first step: connect your data source. Here’s how, and here’s a button that says “I’ve done this.” She connects it that afternoon and clicks done. On Wednesday (day 2) the guide sends the setup step: invite a teammate. She’s busy and skips it. On Thursday the window passes, so the guide sends one gentle nudge that mentions the welcome. Still nothing by the weekend. On the following Monday the final window passes, so the guide flags Priya to the owner, Sam, with the full picture: starter plan, stuck on “invite a teammate,” five days in. Sam emails her himself, learns she’s a team of one, and pauses her sequence. Priya never gets nagged again about a step that doesn’t apply to her.

The cost of running this is about $2.10 a month at SMB volume. The cost of not running it is the new customer who signs up, gets stuck on step one, and is gone before anyone notices — the most expensive kind of churn, because you already paid to win them.

Design rules that shaped every decision

  • Every message ships with full context — the next step, a short how-to, a link in, and a one-click done link. The customer never has to dig.
  • Four moves, always. On track, next step due, gentle nudge, flag to owner. There is no fifth.
  • The pace adapts. A customer moving fast skips ahead and gets fewer messages; a stuck one gets one nudge, then a human.
  • Quiet hours, weekends, and holidays are respected. A message is a finite resource; bad timing burns it.
  • A finished or paused customer stops getting messages. The guide never drips an endless sequence.
  • Every send and every owner action is logged. Review an onboarding next quarter and you can see every message that went out.

Why this shape

Most teams onboard new customers in one of three ways: a person who reaches out when they have time, a generic drip sequence that emails everyone the same five things on the same five days, or nothing at all. The person works until they’re busy — and the weeks they’re busiest are exactly the weeks the most new customers are arriving. The generic drip is the worst kind of false comfort: it keeps emailing the customer who already finished, and keeps emailing the customer who’s stuck the exact thing that didn’t help the first time. And “nothing at all” is how a business quietly loses the customers it worked hardest to win.

The setup above keeps the customer list in a sheet the team already has, but adds a small system that looks at that list every day and acts only when a customer actually needs the next step or has stalled. Messages go out when they’re useful, not on a fixed drip. The pace bends to the person: fast movers get out of the way, stuck movers get a hand. It escalates to a human cleanly when a nudge isn’t enough. And it stops the moment someone finishes or the owner pauses them. The guide is invisible on the days a customer is moving along fine; it only shows up when there’s a next step to take or someone is stuck.

The next four posts walk through each piece in turn: how a new customer gets enrolled, how an onboarding step comes due, how a nudge reaches a customer, and how an onboarding finishes. One diagram per post. A cost breakdown and a final engineering reference at the end.

All posts