# docusign/sample-app-workflows-node architecture

> Architecture diagram of the GitHub repository docusign/sample-app-workflows-node, 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-workflows-node
- Repository: https://github.com/docusign/sample-app-workflows-node

## Overview

##### Project Type and Purpose
- This is a full-stack sample application built with React (client) and Node.js/Express (server) that demonstrates how to integrate with the DocuSign Maestro API. It provides a web UI for users to authenticate (JWT & ACG flows), list available workflows, trigger them, and view results.

##### High-Level Architecture Components
a. Frontend (React/Vite)
- Runs in the browser (or as a Dockerized static site behind NGINX in production).
- Implements pages (Hero, TriggerWorkflow, TriggerWorkflowForm), UI components (login form, workflow list/description/forms, popups), a Redux store (actions/reducers) and API client layer (`client/src/api/index.js`).

b. Backend (Node.js/Express)
- Exposes REST endpoints under `/auth` and `/workflows`.
- Uses controllers (`server/controllers/*`) to handle incoming requests, middlewares for JWT/ACG auth, services (`server/services/workflowsService.js`) to encapsulate business logic, and utils for logging and generic helpers.
- Reads configuration & secrets from `.env` and RSA private key, and templates/workflows from `server/assets`.

c. Infrastructure
- NGINX (infra/nginx) as a reverse proxy/SSL terminator and static file server for production.
- Docker Compose (`docker-compose.local.yaml`) orchestrates three containers: NGINX, Client, Server.
- Environment (local vs. Docker) controlled by `.env` and compose overrides.

d. External Services
- DocuSign OAuth & Maestro APIs for authentication and workflow execution.

##### Relationships and Data Flows
1. User (browser) ↔ HTTP(S) ↔ NGINX
- In prod, NGINX serves the React app and proxies API calls to the Express server.
2. React App → Express API
- Login requests (`/auth`) → server issues JWT or performs ACG.
- Workflow list/trigger requests (`/workflows`) → server orchestrates DocuSign Maestro calls.
3. Express Server → DocuSign API
- Uses RSA key to obtain access tokens (JWT grant).
- Calls Maestro endpoints to list/trigger workflows and returns results to client.

##### Architectural Patterns and Principles
- Separation of concerns: UI vs. API vs. infra.
- Layered backend: routes → controllers → services → utilities.
- Stateful Redux store on client to manage auth status and workflow data.
- Environment-driven configuration for local vs. Docker vs. prod.

##### Technologies & Frameworks to Annotate
- Frontend: React, Vite, Redux (store/actions/reducers), Axios/fetch (api client).
- Backend: Node.js, Express, jsonwebtoken, middleware pattern, template assets.
- Infra: Docker, Docker Compose, NGINX.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker Compose Network Boundary
    subgraph "Docker Compose Network" 
        style DockerCompose fill:none,stroke:#FFA500,stroke-width:2px
        DockerCompose([ ]) 

        subgraph "Client Container (React/Vite)" 
            style ClientContainer fill:#e0ffe0,stroke:#33aa33
            C_index["Static HTML Template<br/>index.html"]
            C_main["React Entry Point<br/>main.jsx"]
            C_api["API Client Layer<br/>index.js"]
            C_store["Redux Store<br/>actions/reducers"]
            C_components["UI Components<br/>components/"]
            C_pages["Pages<br/>pages/"]
        end

        subgraph "Server Container (Node.js/Express)" 
            style ServerContainer fill:#e0ffe0,stroke:#33aa33
            S_entry["Express Entry Point<br/>server.js"]
            S_authRouter["authRouter.js"]
            S_workflowRouter["workflowsRouter.js"]
            S_jwtCtrl["jwtController.js"]
            S_acgCtrl["acgController.js"]
            S_workflowCtrl["workflowsController.js"]
            S_authMw["authMiddleware.js"]
            S_service["workflowsService.js"]
            S_apiFactory["apiFactory.js"]
            S_apiIndex["api/index.js"]
            S_templates["Templates<br/>assets/templates/"]
            S_definitions["Workflows<br/>assets/workflows/"]
            S_config["config.js<br/>constants.js<br/>.env"]
            S_key["example_private.key"]
        end

        Nginx["NGINX Proxy<br/>infra/nginx"]:::infra
    end

    ext["DocuSign OAuth & Maestro API"]:::external

    %% Connections
    Browser -- "HTTP 80/3000" --> Nginx
    Nginx -- "serves index.html" --> C_index
    C_index --> C_main
    C_main --> C_api
    C_api -- "GET/POST /auth" --> S_authRouter
    C_api -- "GET/POST /workflows" --> S_workflowRouter
    S_authRouter --> S_jwtCtrl
    S_authRouter --> S_acgCtrl
    S_workflowRouter --> S_workflowCtrl
    S_jwtCtrl --> S_service
    S_acgCtrl --> S_service
    S_workflowCtrl --> S_service
    S_service --> ext

    ext -->|"responses"| S_service
    S_service -->|"returns data"| C_api

    %% Click Events for Component Mapping
    click C_index "https://github.com/docusign/sample-app-workflows-node/blob/main/client/index.html"
    click C_main "https://github.com/docusign/sample-app-workflows-node/blob/main/client/src/main.jsx"
    click C_api "https://github.com/docusign/sample-app-workflows-node/blob/main/client/src/api/index.js"
    click C_store "https://github.com/docusign/sample-app-workflows-node/tree/main/client/src/store/"
    click C_components "https://github.com/docusign/sample-app-workflows-node/tree/main/client/src/components/"
    click C_pages "https://github.com/docusign/sample-app-workflows-node/tree/main/client/src/pages/"
    click ServerContainer "https://github.com/docusign/sample-app-workflows-node/tree/main/server/"
    click S_entry "https://github.com/docusign/sample-app-workflows-node/blob/main/server/server.js"
    click S_jwtCtrl "https://github.com/docusign/sample-app-workflows-node/blob/main/server/controllers/jwtController.js"
    click S_acgCtrl "https://github.com/docusign/sample-app-workflows-node/blob/main/server/controllers/acgController.js"
    click S_workflowCtrl "https://github.com/docusign/sample-app-workflows-node/blob/main/server/controllers/workflowsController.js"
    click S_authRouter "https://github.com/docusign/sample-app-workflows-node/blob/main/server/routes/authRouter.js"
    click S_workflowRouter "https://github.com/docusign/sample-app-workflows-node/blob/main/server/routes/workflowsRouter.js"
    click S_authMw "https://github.com/docusign/sample-app-workflows-node/blob/main/server/middlewares/authMiddleware.js"
    click S_service "https://github.com/docusign/sample-app-workflows-node/blob/main/server/services/workflowsService.js"
    click S_apiFactory "https://github.com/docusign/sample-app-workflows-node/blob/main/server/api/apiFactory.js"
    click S_apiIndex "https://github.com/docusign/sample-app-workflows-node/blob/main/server/api/index.js"
    click S_templates "https://github.com/docusign/sample-app-workflows-node/tree/main/server/assets/templates/"
    click S_definitions "https://github.com/docusign/sample-app-workflows-node/tree/main/server/assets/workflows/"
    click S_config "https://github.com/docusign/sample-app-workflows-node/blob/main/.env.example"
    click S_key "https://github.com/docusign/sample-app-workflows-node/blob/main/example_private.key"
    click Nginx "https://github.com/docusign/sample-app-workflows-node/blob/main/infra/nginx/conf/default.conf"
    click DockerCompose "https://github.com/docusign/sample-app-workflows-node/blob/main/docker-compose.local.yaml"

    %% Styles
    classDef internal fill:#e0ffe0,stroke:#33aa33,color:#000
    classDef infra fill:#fff0d1,stroke:#ff9900,color:#000
    classDef external fill:#d1e0ff,stroke:#0066cc,color:#000
    class ClientContainer,ServerContainer internal
    class Nginx,DockerCompose infra
    class ext external
```
