# Project pack: Documenso @ 8707e33

Facts about **Documenso** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Documenso is an open-source e-signature platform, a DocuSign alternative. You upload a document, place signature and form fields, send it to signers by email, and everyone receives a signed, sealed PDF with an audit trail. You can host it yourself and use your own signing certificate.

## Version and source
- Repository: https://github.com/documenso/documenso
- Pinned commit: `8707e33c124e4b1a68dde92d5e05178c9aabd0be`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/documenso/documenso/archive/8707e33c124e4b1a68dde92d5e05178c9aabd0be.zip
- Official docs: https://docs.documenso.com
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them your source code under the same licence. Using it privately for yourself or your household has no extra obligations. The packages/ee folder has a separate licence for enterprise features.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/documenso/documenso bespoke-documenso
  cd bespoke-documenso
  git checkout --detach 8707e33c124e4b1a68dde92d5e05178c9aabd0be
  # Prepare development requirements and local configuration first.
  npm install
  cp .env.example .env
  npm run dx
  npm run dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  Follow the Docker guide at https://docs.documenso.com/developers/self-hosting to run the documenso/documenso image with a Postgres database and a signing certificate.
  ```

- Needs: Docker with Postgres; Node 22 for development
- Develop: `npm run dev`
- Check/lint: `npm run lint`
- Build: `npm run build`
- Stack: typescript (React Router (Remix), Prisma, Hono, tRPC, Turborepo). Difficulty for a non-developer with an AI: **advanced**. A TypeScript monorepo with a web app, signing and PDF logic, and email templates. Branding and templates are settings; workflow changes touch signing code that must stay correct.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`, `.cursorrules`.

## Customisation points (settings → extend → code)
- **templates** [settings]: Reusable documents with fields already placed. → `Templates in the web app`
- **branding-and-email** [settings]: Your logo, colours and email wording. → `Team settings → Branding and Email`
- **api-and-webhooks** [extend]: Create documents from other tools and get notified on completion. → `docs.documenso.com/developers/public-api, Webhooks`
- **embedded-signing** [extend]: Show signing inside your own website. → `Embedded authoring and signing packages`
- **signing-flow** [code]: Changes to the signing steps. → `packages/lib/server-only/document and apps/remix/app`

## Must keep working
- Signature validity and the audit trail. Never alter a document after it is sealed.
- Prisma migrations. Add new ones; never edit old ones.
- Authentication for signers and access to documents.

## Staying updatable
Prefer templates, branding, webhooks and the API. Keep code in new files and away from the signing core and ee folder.

## Data, costs and safety
- Personal data: **yes**. Stored in: A Postgres database, plus documents in the database or an S3 bucket. Contracts and signatures are legal records. Back up the database, the documents and the signing certificate.
- Service: Email (SMTP) (required, usually free to a few dollars): Sends signing requests and receipts.
- Service: Signing certificate (.p12) (required, free to buy): Seals the signed PDF so edits can be detected.
- Service: File storage (database or S3) (optional, free locally): Stores uploaded documents.
- Setting `NEXTAUTH_SECRET` (**secret**: the person enters it themselves, never in chat): Secret used to sign logins. Never paste it into an AI chat.
- Setting `NEXT_PRIVATE_DATABASE_URL` (**secret**: the person enters it themselves, never in chat): Postgres connection string. Contains a password.
- Setting `NEXT_PRIVATE_SIGNING_PASSPHRASE` (**secret**: the person enters it themselves, never in chat): Passphrase of the signing certificate.
- E-signature rules differ by country and document type. Check what applies to you.
- Protect the signing certificate and NEXTAUTH_SECRET. Never paste them into an AI chat.
- Test with dummy documents before sending anything real.

---

# Customising Documenso

Documenso is a Turborepo monorepo. Because signatures are legal records, prefer settings, templates and the API.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Web app | apps/remix/app/ |
| Document and signing logic | packages/lib/ |
| Database schema and migrations | packages/prisma/ |
| Email templates | packages/email/ |
| API | packages/api/ and packages/trpc/ |
| Enterprise features | packages/ee/ (separate licence) |
| Docs | apps/docs/ |

## Use the gentlest change first

1. **Settings (no code):** templates, branding, team roles and email wording.
2. **Extend:** the API, webhooks and embedded signing.
3. **Code:** new screens and notifications, kept away from signing and sealing.

## Recipes

- **Webhook to archive:** subscribe to the document completed event, download the signed PDF with the API, and save it.
- **New email:** add a template in `packages/email/templates` and send it from the relevant flow.

## Running and checking your changes

- Use dummy documents with two signers and open the final PDF in two viewers.
- `npm run lint`, and the tests for the package you touched.
- Check the audit log includes every step.

## Pitfalls

- Don't modify the sealing code without expert review.
- Keep real certificates out of Git.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/documenso/8707e33/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/documenso/8707e33/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/documenso/8707e33/r2/SKILL.md)