Skip to content
allanninal.dev/build
Collaborate

Part 5 of 7 · Offer letter generator series ~5 min read

How a sent offer is recorded

An offer letter is a document that gets read back years later, usually at an inconvenient moment. What gets stored at the point of sending determines whether that reading is a two-minute lookup or an afternoon in an email archive.

Key takeaways

  • The exact PDF is kept, not the ability to re-render it.
  • The clause versions used are recorded, so the letter can be explained as well as produced.
  • Acceptance is recorded as an event with a date, however it arrived.
  • The start date and role hand straight to onboarding, with nobody retyping anything.
  • One report matters: how often the library needed a new clause.

Keep the document, not the recipe

The tempting economy is to store the terms and the template versions and re-render the letter when needed. It saves a small amount of storage and it is wrong, because rendering is code and code changes: a formatting fix eighteen months from now would silently produce a document that differs from the one somebody signed.

So the PDF as sent is stored, unmodified, and it is the record. The terms and clause versions are stored alongside it to explain it, not to reproduce it.

KeptWhy
The PDF as sentIt is the document. Nothing regenerates it.
The nine terms, versionedWhat was agreed, and what changed if it was renegotiated
Clause ids and versionsLets somebody explain any sentence in the letter
Who drafted and who sentTwo different people, both recorded
The covering emailOffers are frequently qualified in the email body
Acceptance, with a dateHowever it arrived: a reply, a signature, a phone call logged

The covering email is the one most systems forget, and it matters because a substantial proportion of offers are qualified in the body of the message rather than in the attachment — “as discussed, we can review the rate at six months”. That sentence is part of what was communicated and it belongs with the letter.

Acceptance

How an accepted offer is recorded and handed to onboardingA vertical chain of four steps entered by a box labelled Offer sent, by a person. Step one covers the three ways a response arrives: a reply, a signature, or a logged phone call; a decline exits to Declined, recorded with a reason if one was given. Step two records the acceptance with its date and route as an immutable event in a DynamoDB offers table. Step three hands the name, role and start date to onboarding, specifically to the background check chaser from Day 86. Step four notes that nothing is retyped and the same terms carry all the way through. A note says the handover is the point, because retyping a start date is where onboarding starts going wrong.AWS ACCOUNTOffer sentby a personReply, signature, or callthree ways inDeclinedrecorded, with a reason if givennoRecord the acceptancedate and routeDynamoDB offersimmutable eventHand to onboardingname, role, start dateCheck chaserfrom Day 86Nothing retypedthe same terms all the wayThe handover is the point. Retyping a start date is where onboarding starts going wrong.
Fig 1. What happens when an offer is accepted. The handover to onboarding carries the same terms that were in the letter, which removes the most common source of a wrong start date.
  • Database
  • App integration
  • Machine learning
  • Networking
  • Security & identity
  • Management
  • People

That handover is worth more than it looks. The most common onboarding error in small businesses is a start date that differs between the offer letter, the HR record and the payroll setup, because it was typed three times. Passing it once removes the possibility.

Declines

Recorded, with a reason if the candidate volunteered one, and never chased. A declined offer is a complete outcome, and the only useful thing to do with it is count it: three declines on salary in a quarter is a market signal, and it is only visible if declines are recorded rather than deleted.

The report

One quarter of offer letters summarised in five numbersA horizontal row of five boxes. Offers: fourteen this quarter. Median time: three hours from agreement to letter sent. Accepted: eleven. New clauses: three were requested. Library age: the oldest clause is three years old. A note says the fourth number tells you whether the library still describes how you hire.ONE QUARTER OF OFFERSOffers14 this quarterMedian timeagreed to sent: 3hAccepted11New clauses3 requestedLibrary ageoldest clause: 3 yearsThe fourth number says whether the library still describes how you hire.
Fig 2. A quarter of offers in five numbers. The clause-request count is the one that tells you something you did not already know.

Three new clauses in fourteen offers means roughly one offer in five is doing something the library does not cover, which is high and usually means the business has started hiring differently — more part-time, more fixed-term, more flexible arrangements — without the paperwork catching up. That is a genuinely useful thing to learn from a document generator.

Next: what all of this costs to run.

All posts