How docusign/sample-app-insurance-python works
Project type and purpose
• Full-stack sample application demonstrating DocuSign integration
• Backend: Python/Flask (handles JWT authentication, eSignature, Click API, payments)
• Frontend: React single-page app (user UI for buying insurance, renewing policies, submitting claims)
• External dependencies: DocuSign Auth Server, eSignature API, Click API, Payment Gateway (Stripe-demo)
File structure
• Top-level “app/” folder: Flask application
– app/api/*.py: route handlers (auth, clickwrap, requests, common utilities)
– app/ds_client.py, app/ds_config.py: wrapper for DocuSign REST calls & configuration
– app/envelope.py, app/clickwrap.py, app/document.py: business logic around document creation
– app/templates & app/images: HTML/Word templates for envelopes & clickwraps
• “run.py”: Flask server entry point
• “public/” + “src/”: React app (JSX, components, contexts, i18n, SCSS)
• “scripts/”: deployment & helper scripts (install, run, AWS deploy)
• Config files: .env (environment variables), requirements.txt, package.json
Key insights from the README
• Three demo flows:
1. Submit a claim (HTML template + attachment + embedded signing)
2. Renew policy (programmatic clickwrap + embedded flow)
3. Purchase policy (payment request + calculated fields)
• Auth via JWT grant—backend obtains DocuSign access token using DS_CLIENT_ID & DS_PRIVATE_KEY
• Frontend calls backend at /api to start a signing ceremony, then redirects user to DocuSign embedded view
Main components & their interactions
a. Components
• User’s Browser (React SPA)
• React Client
– Pages (buyNewInsurance, submitClaim, requestAutoRenewal, history, home)
– Contexts & interceptors (managing JWT tokens, API base URL)
• Flask API Server
– Auth Module (handles login, JWT token exchange with DocuSign Auth Server)
– Business Modules (envelope.py, clickwrap.py, document.py, requests.py)
– DS Client (HTTP wrapper for DocuSign eSignature & Click REST APIs)
– Session Storage (app/api/session_data.py – in-memory or cookie based)
• External Services
– DocuSign Auth Server (account-d.docusign.com)
– DocuSign eSignature API
– DocuSign Click API
– Stripe‐demo Payment Gateway (via eSignature payment tabs)
b. Relationships & data flows
1. Browser → React (user interactions)
2. React → Flask (REST calls to /api/auth, /api/requests, /api/clickwrap)
3. Flask → DocuSign Auth (JWT grant → access token)
4. Flask → DocuSign APIs (create envelope/clickwrap/payment)
5. DocuSign → Browser (embedded signing ceremony URL)
6. Browser → DocuSign (user signs documents)
7. DocuSign → Flask (webhook or return URL on completion)
8. Flask → React (final status & redirect)
c. Architectural patterns & design principles
• Separation of concerns:
– Presentation (React UI) vs Business/API (Flask) vs External services
• Layered architecture:
– UI Layer → API Layer → Business Logic → External Integration Layer
• Stateless backend (JWT tokens) with session/context management in React
d. Key technologies & frameworks
• React, React Router, Context API, Axios interceptors
• Flask, Flask-RESTful (implicit), python-dotenv
• DocuSign REST APIs (Authentication, eSignature, Click)
• Stripe Payment via DocuSign payment tabs
Detailed capture of architectural elements
• Break the Flask server block into sub-components: Auth module, DS Client, Business logic modules
• In the React block show Contexts, API helper, key Pages