documenso-reference-architecture

name	documenso-reference-architecture
description	Implement Documenso reference architecture with best-practice project layout. Use when designing new Documenso integrations, reviewing project structure, or establishing architecture standards for document signing applications. Trigger with phrases like "documenso architecture", "documenso best practices", "documenso project structure", "how to organize documenso".
allowed-tools	Read, Grep
version	1.13.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","documenso","documenso-reference"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Documenso Reference Architecture

Overview

Production-ready architecture for Documenso document signing integrations. Covers project layout, layered service architecture, webhook processing, and data flow.

Prerequisites

• Understanding of layered architecture principles
• Documenso SDK knowledge (see documenso-sdk-patterns)
• TypeScript project with Node.js 18+

Recommended Project Structure

my-signing-app/
├── src/
│   ├── documenso/
│   │   ├── client.ts              # Singleton SDK client
│   │   ├── errors.ts              # Custom error classes
│   │   ├── retry.ts               # Retry/backoff logic
│   │   └── types.ts               # Shared types
│   ├── services/
│   │   ├── document-service.ts    # Document CRUD operations
│   │   ├── template-service.ts    # Template-based workflows
│   │   └── signing-service.ts     # Orchestrates signing flows
│   ├── webhooks/
│   │   ├── handler.ts             # Express webhook router
│   │   ├── verify.ts              # Secret verification
│   │   └── processors/
│   │       ├── document-completed.ts
│   │       ├── document-signed.ts
│   │       └── document-rejected.ts
│   ├── api/
│   │   ├── health.ts              # Health check endpoint
│   │   └── routes.ts              # API routes
│   └── config/
│       └── index.ts               # Environment configuration
├── scripts/
│   ├── verify-connection.ts       # Quick health check
│   ├── create-test-doc.ts         # Test document generator
│   └── cleanup-test-docs.ts       # Test data cleanup
├── tests/
│   ├── unit/
│   │   └── document-service.test.ts
│   ├── integration/
│   │   └── document-lifecycle.test.ts
│   └── mocks/
│       └── documenso.ts           # Mock client factory
├── .env.development
├── .env.production
├── docker-compose.yml             # Self-hosted Documenso (dev)
└── package.json

Layer Architecture

┌─────────────────────────────────────────────────────────┐
│  API / Controllers                                       │
│  Routes, request validation, response formatting         │
├─────────────────────────────────────────────────────────┤
│  Service Layer                                           │
│  Business logic, orchestration, authorization            │
│  (document-service, template-service, signing-service)   │
├─────────────────────────────────────────────────────────┤
│  Documenso Client Layer                                  │
│  SDK wrapper, retry, error handling, caching             │
│  (client.ts, retry.ts, errors.ts)                       │
├─────────────────────────────────────────────────────────┤
│  External Services                                       │
│  Documenso API, S3/GCS storage, email, database         │
└─────────────────────────────────────────────────────────┘

Rules:

• Controllers never call Documenso directly -- always go through services