documenso-reference-architecture
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".
69
Quality
63%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Securityby
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/saas-packs/documenso-pack/skills/documenso-reference-architecture/SKILL.mdDocumenso 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.jsonLayer 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
- Services never import
@documenso/sdk-typescriptdirectly -- use the client wrapper - Webhook processors are isolated -- one file per event type
- Error handling happens at the client layer, not in controllers
Data Flow
User 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)Setup Script
#!/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."Key Design Decisions
| 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 |
Error Handling
| 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 |
Resources
Next Steps
For multi-environment setup, see documenso-multi-env-setup.
- Commit
3a2d27d
- Last updated
- Created
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.