From documenso-pack
Provides reference project structure and layered architecture for Documenso document signing integrations, covering services, webhooks, API routes, tests, and Docker setup.
npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin documenso-packThis skill is limited to using the following tools:
Production-ready architecture for Documenso document signing integrations. Covers project layout, layered service architecture, webhook processing, and data flow.
Sets up local dev environment for Documenso integrations: Docker self-hosting, TypeScript SDK client, test scripts, project structure, and env configs for rapid testing workflows.
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Share bugs, ideas, or general feedback.
Production-ready architecture for Documenso document signing integrations. Covers project layout, layered service architecture, webhook processing, and data flow.
documenso-sdk-patterns)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
┌─────────────────────────────────────────────────────────┐
│ 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:
@documenso/sdk-typescript directly -- use the client wrapperUser Request
│
▼
┌──────────┐ POST /api/sign
│ API │──────────────────────────────┐
│ Router │ │
└──────────┘ ▼
┌──────────────┐
│ Signing │
│ Service │
└──────┬───────┘
│
┌─────────────────────┼─────────────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Template │ │ Document │ │ Your │
│ Service │ │ Service │ │ DB │
└────┬─────┘ └────┬─────┘ └──────────┘
│ │
└────────┬───────────┘
▼
┌──────────────┐
│ Documenso │
│ Client │──→ Documenso API
│ (singleton) │
└──────────────┘
Webhook Flow:
Documenso API ──POST──→ /webhooks/documenso
│
┌────▼────┐
│ Verify │──→ Check X-Documenso-Secret
│ Secret │
└────┬────┘
│
┌────▼────┐
│ Router │──→ Route by event type
└────┬────┘
│
┌──────────────┼──────────────┐
▼ ▼ ▼
completed.ts signed.ts rejected.ts
(archive PDF) (update DB) (alert sender)
#!/bin/bash
set -euo pipefail
mkdir -p src/{documenso,services,webhooks/processors,api,config}
mkdir -p scripts tests/{unit,integration,mocks}
# Create .env.example
cat > .env.example << 'EOF'
DOCUMENSO_API_KEY=
DOCUMENSO_BASE_URL=https://app.documenso.com/api/v2
DOCUMENSO_WEBHOOK_SECRET=
LOG_LEVEL=info
NODE_ENV=development
EOF
echo "Project scaffolded. Copy .env.example to .env and fill in values."
| Decision | Rationale |
|---|---|
| Singleton client | Avoids re-initialization overhead per request |
| Service layer | Separates business logic from API details |
| One processor per webhook event | Isolates side effects, easy to test |
| Mock client for tests | Fast unit tests without API calls |
| Template-first approach | Fewer API calls, consistent field placement |
| Issue | Cause | Solution |
|---|---|---|
| Circular dependencies | Wrong layering | Services import client, never the reverse |
| Config not loading | Wrong env file | Verify NODE_ENV matches config loader |
| Webhook processor crash | Unhandled error in processor | Wrap each processor in try/catch |
| Test isolation | Shared client state | Call resetClient() in beforeEach |
For multi-environment setup, see documenso-multi-env-setup.