# docusign/sample-app-insurance-python architecture

> Architecture diagram of the GitHub repository docusign/sample-app-insurance-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/docusign/sample-app-insurance-python
- Repository: https://github.com/docusign/sample-app-insurance-python

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        Browser["User's Browser"]:::frontend
        ReactSPA["React SPA"]:::frontend
        subgraph "Pages"
            BN["Buy New Insurance Flow"]:::frontend
            SC["Submit Claim Flow"]:::frontend
            RA["Request Auto Renewal Flow"]:::frontend
            HV["History View"]:::frontend
            HP["Home Page"]:::frontend
        end
        Contexts["React Contexts (JWT & modal)"]:::frontend
        APIHelper["Axios API Helper"]:::frontend
        Interceptors["Axios Interceptors"]:::frontend
        subgraph "API Endpoints"
            AuthAPI["Auth API"]:::frontend
            DownloadAPI["Download API"]:::frontend
            HistoryAPI["History API"]:::frontend
            InsuranceAPI["Insurance API"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend Layer"
        Run["run.py"]:::backend
        subgraph "Flask API Server"
            AuthModule["Authentication Module"]:::backend
            ClickwrapModule["Clickwrap Module"]:::backend
            RequestsModule["Envelope/Requests Module"]:::backend
            CommonUtils["Common Utilities"]:::backend
            SessionStore["Session Storage"]:::backend
            DSClient["DocuSign Client"]:::backend
            DSConfig["DocuSign Config"]:::backend
            EnvelopeBL["Envelope Business Logic"]:::backend
            ClickwrapBL["Clickwrap Business Logic"]:::backend
            DocumentBL["Document Utility Logic"]:::backend
            FlaskConfig["Flask Configuration"]:::backend
            Templates["HTML & Docx Templates"]:::backend
            Images["Static Images"]:::backend
        end
        EnvFile[".env"]:::backend
        ReqTxt["requirements.txt"]:::backend
        PackageJSON["package.json"]:::backend
        PackageLock["package-lock.json"]:::backend
        Scripts["Deployment & Helper Scripts"]:::backend
    end

    %% External Services
    subgraph "External Services"
        AuthServer["DocuSign Auth Server"]:::external
        EsignAPI["DocuSign eSignature API"]:::external
        ClickAPI["DocuSign Click API"]:::external
        Stripe["Stripe Demo Payment Gateway"]:::external
    end

    %% Connections
    Browser --> ReactSPA
    ReactSPA --> BN
    ReactSPA --> SC
    ReactSPA --> RA
    ReactSPA --> HV
    ReactSPA --> HP
    ReactSPA --> Contexts
    ReactSPA --> APIHelper
    ReactSPA --> Interceptors
    ReactSPA --> AuthAPI
    ReactSPA --> DownloadAPI
    ReactSPA --> HistoryAPI
    ReactSPA --> InsuranceAPI

    AuthAPI -->|"/api/auth"| Run
    DownloadAPI -->|"/api/download"| Run
    HistoryAPI -->|"/api/history"| Run
    InsuranceAPI -->|"/api/insurance"| Run

    Run --> AuthModule
    Run --> ClickwrapModule
    Run --> RequestsModule
    Run --> CommonUtils
    Run --> SessionStore
    Run --> DSClient
    Run --> DSConfig
    Run --> EnvelopeBL
    Run --> ClickwrapBL
    Run --> DocumentBL
    Run --> FlaskConfig
    Run --> Templates
    Run --> Images

    AuthModule -->|JWT grant| AuthServer
    ClickwrapModule -->|REST call| ClickAPI
    RequestsModule -->|eSignature & payment| EsignAPI
    RequestsModule -->|payment tabs| Stripe

    EsignAPI -->|embedded signing URL| Browser
    Browser -->|sign documents| EsignAPI
    EsignAPI -->|callback| RequestsModule
    RequestsModule -->|status update| ReactSPA

    %% Click Events - Frontend
    click ReactSPA "https://github.com/docusign/sample-app-insurance-python/tree/master/src/"
    click BN "https://github.com/docusign/sample-app-insurance-python/tree/master/src/pages/buyNewInsurance/"
    click SC "https://github.com/docusign/sample-app-insurance-python/tree/master/src/pages/submitClaim/"
    click RA "https://github.com/docusign/sample-app-insurance-python/tree/master/src/pages/requestAutoRenewal/"
    click HV "https://github.com/docusign/sample-app-insurance-python/tree/master/src/pages/history/"
    click HP "https://github.com/docusign/sample-app-insurance-python/tree/master/src/pages/home/"
    click Contexts "https://github.com/docusign/sample-app-insurance-python/tree/master/src/contexts/"
    click APIHelper "https://github.com/docusign/sample-app-insurance-python/blob/master/src/api/apiHelper.js"
    click Interceptors "https://github.com/docusign/sample-app-insurance-python/blob/master/src/api/interceptors.js"
    click AuthAPI "https://github.com/docusign/sample-app-insurance-python/blob/master/src/api/auth.js"
    click DownloadAPI "https://github.com/docusign/sample-app-insurance-python/blob/master/src/api/download.js"
    click HistoryAPI "https://github.com/docusign/sample-app-insurance-python/blob/master/src/api/history.js"
    click InsuranceAPI "https://github.com/docusign/sample-app-insurance-python/blob/master/src/api/insuranceAPI.js"

    %% Click Events - Backend
    click Run "https://github.com/docusign/sample-app-insurance-python/blob/master/run.py"
    click AuthModule "https://github.com/docusign/sample-app-insurance-python/blob/master/app/api/auth.py"
    click ClickwrapModule "https://github.com/docusign/sample-app-insurance-python/blob/master/app/api/clickwrap.py"
    click RequestsModule "https://github.com/docusign/sample-app-insurance-python/blob/master/app/api/requests.py"
    click CommonUtils "https://github.com/docusign/sample-app-insurance-python/blob/master/app/api/common.py"
    click SessionStore "https://github.com/docusign/sample-app-insurance-python/blob/master/app/api/session_data.py"
    click DSClient "https://github.com/docusign/sample-app-insurance-python/blob/master/app/ds_client.py"
    click DSConfig "https://github.com/docusign/sample-app-insurance-python/blob/master/app/ds_config.py"
    click EnvelopeBL "https://github.com/docusign/sample-app-insurance-python/blob/master/app/envelope.py"
    click ClickwrapBL "https://github.com/docusign/sample-app-insurance-python/blob/master/app/clickwrap.py"
    click DocumentBL "https://github.com/docusign/sample-app-insurance-python/blob/master/app/document.py"
    click FlaskConfig "https://github.com/docusign/sample-app-insurance-python/blob/master/app/config.py"
    click Templates "https://github.com/docusign/sample-app-insurance-python/tree/master/app/templates/"
    click Images "https://github.com/docusign/sample-app-insurance-python/tree/master/app/images/"
    click EnvFile "https://github.com/docusign/sample-app-insurance-python/blob/master/.env"
    click ReqTxt "https://github.com/docusign/sample-app-insurance-python/blob/master/requirements.txt"
    click PackageJSON "https://github.com/docusign/sample-app-insurance-python/blob/master/package.json"
    click PackageLock "https://github.com/docusign/sample-app-insurance-python/blob/master/package-lock.json"
    click Scripts "https://github.com/docusign/sample-app-insurance-python/tree/master/scripts/"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#004d40
    classDef backend fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    classDef external fill:#fff3e0,stroke:#ef6c00,color:#e65100
```
