ADR-0014: In-house electronic signature
- Status: Accepted
- Date: 2026-11-14
Context and problem statement
Section titled “Context and problem statement”Several steps end with a signature: the full driver application and its authorizations, the job offer, contracts and company terms, the reply of a previous employer. Signers are candidates and drivers on a phone, third parties reached by email, and users of the company inside their session. The signed document becomes part of the driver file.
How are documents signed?
Decision drivers
Section titled “Decision drivers”- Signing is a step inside the candidate flow, in English and Spanish, on a phone.
- One proof format for every kind of document.
- A signed document cannot be changed, and tampering with the stored file is detectable.
- No external account is needed to run the product.
Considered options
Section titled “Considered options”- A signing service of the product: the signer reads the document, agrees to use electronic records and signatures, types the full name and confirms.
- A third-party electronic signature service. Common market alternative, listed for comparison.
A drawn signature and a certificate-based digital signature were left out of option 1 when the decision was made.
Decision outcome
Section titled “Decision outcome”Chosen option: 1.
SigningService, in apps/api/src/modules/platform-signing, is the only path of a signature. A module creates an envelope from structured content and its variables. The content is frozen with its SHA-256, and the worker generates the PDF (no browser runs inside the API). Signers sign in order. A person outside the company signs by a link under the careers address of the company. A user of the company signs inside the session.
For each signature the service stores the typed name, the instant, the IP address, the browser user agent, how the signer was identified (link or session), the version and language of the consent text and the hash of the document. When the last signer signs, the worker appends the proof pages and keeps the final PDF through the file service (ADR-0017). Its bytes are compared with the recorded hash every time the file is handed over. A completed, declined, canceled or expired envelope never changes: a correction is a new envelope.
Consequences
Section titled “Consequences”- Good, because signing has no cost per envelope and no external dependency.
- Good, because every module that needs a signature gets the same proof, the same public page and the same events (
signing.completed,signing.declined,signing.expired). - Bad, because there is no drawn signature and no certificate-based digital signature. The proof is the typed name with the recorded circumstances.
- Bad, because the consent text is a regulatory preview until the platform team marks it validated, see ADR-0019. Each signature records whether the text was validated at that moment.
- Bad, because a company without a careers page cannot send a document to be signed by link: the link lives under that address.
More information
Section titled “More information”apps/api/src/modules/platform-signing/index.ts: the public interface, with the life of an envelope.apps/api/src/modules/platform-signing/pdf/pdf-generator.ts: the PDF generator.packages/db/src/schema/signing.ts: envelopes, signers, signatures and events.apps/careers/src/pages/[company]/sign/: the public signing page.- Lifecycles has the state diagram of a signing envelope, and Runtime view the sequence of a signature.
- Concept pages: Files and vaults, Audit log.
- User guide: Contracts and signing.