AGENT SKILL

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".

License 许可
MIT
最近更新
2026-07-13
Stars
★ 1
Forks
0

01 前言 Front Matter

name
documenso-reference-architecture
tags
[ "saas", "documenso", "documenso-reference" ]
author
Jeremy Longshore <jeremy@intentsolutions.io>
license
MIT
version
1.0.0
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
compatible-with
claude-code, codex, openclaw

03 SKILL.md 正文

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
  • Services never import @documenso/sdk-typescript directly -- 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.

04 同仓库更多 Skills

jukeyman
jukeyman/jukeyman-skills

zustand-store-creator

Create zustand store creator operations. Auto-activating skill for Frontend Development. Triggers on: zustand store creator, zustand store creator Part of the Frontend Development skill category. Use when working with zustand store creator functionality. Trigger with phrases like "zustand store creator", "zustand creator", "zustand".

★ 1
jukeyman
jukeyman/jukeyman-skills

zero-trust-config-helper

Configure with zero trust config helper operations. Auto-activating skill for Security Advanced. Triggers on: zero trust config helper, zero trust config helper Part of the Security Advanced skill category. Use when configuring systems or services. Trigger with phrases like "zero trust config helper", "zero helper", "zero".

★ 1
jukeyman
jukeyman/jukeyman-skills

zapier-integration-helper

Assist with zapier integration helper operations. Auto-activating skill for Business Automation. Triggers on: zapier integration helper, zapier integration helper Part of the Business Automation skill category. Use when working with APIs or building integrations. Trigger with phrases like "zapier integration helper", "zapier helper", "zapier".

★ 1
jukeyman
jukeyman/jukeyman-skills

yaml-config-validator

Validate yaml config validator operations. Auto-activating skill for DevOps Basics. Triggers on: yaml config validator, yaml config validator Part of the DevOps Basics skill category. Use when configuring systems or services. Trigger with phrases like "yaml config validator", "yaml validator", "yaml".

★ 1
jukeyman
jukeyman/jukeyman-skills

xvary-stock-research

Thesis-driven equity analysis from public SEC EDGAR and market data; /analyze, /score, /compare workflows with bundled Python tools (Claude Code, Cursor, Codex).

★ 1
jukeyman
jukeyman/jukeyman-skills

xss-vulnerability-scanner

Scan xss vulnerability scanner operations. Auto-activating skill for Security Fundamentals. Triggers on: xss vulnerability scanner, xss vulnerability scanner Part of the Security Fundamentals skill category. Use when working with xss vulnerability scanner functionality. Trigger with phrases like "xss vulnerability scanner", "xss scanner", "xss".

★ 1