E-Signature Routing & Approval Workflow

Route contracts through configurable internal approval chains, then trigger e-signature. Track execution status and store executed copies.

Getting Started

Option 1: Run Locally (Easiest)

./start.sh          # macOS/Linux
start.bat           # Windows

This installs dependencies, starts the API and frontend, and opens your browser.

Option 2: Docker

cp .env.example .env    # Configure settings
docker compose up

• Frontend: http://localhost:8501
• API + Swagger docs: http://localhost:8000/docs

Option 3: Deploy to Railway

Or deploy manually using Dockerfile.railway.

Features

• Approval Rules Engine — configurable rules based on contract type, value thresholds, and department
• Value-Based Routing — contracts over $100K need VP approval; over $500K need C-suite
• Parallel Approvals — multiple approvers at the same level must all approve
• Token-Based Approval Links — approvers click a link in email/Slack to approve or reject (no login required)
• Email + Slack Notifications — configurable SMTP and Slack webhook alerts
• E-Signature Integration — real DocuSeal integration; DocuSign, PandaDocs, Adobe Sign stubbed
• Document Upload — attach PDF/DOCX contracts with secure file handling
• Audit Trail — append-only log of every action
• Dashboard — track contract status, pending approvals, and metrics
• Admin Panel — create, edit, and manage approval rules via the UI

How It Works

1. Submit a contract with metadata and file upload
2. Rules engine evaluates approval rules and builds an ordered approval chain
3. Approvers receive email/Slack notifications with unique approval links
4. Each approver reviews and approves or rejects via a simple web page
5. On full approval, trigger e-signature via DocuSeal
6. Signed contracts are stored and tracked

Configuration

Copy .env.example to .env and configure:

Variable	Description
SMTP_HOST / SMTP_USER / SMTP_PASSWORD	Email notifications (optional)
SLACK_WEBHOOK_URL	Slack notifications (optional)
DOCUSEAL_API_KEY	DocuSeal e-signature integration
ESIGNATURE_PROVIDER	docuseal, docusign, pandadoc, or adobe_sign

The app works without any external services configured — notifications and e-signature are optional.

For Developers

Tech Stack

• Backend: Python 3.11+, FastAPI, SQLAlchemy 2.0, Pydantic v2
• Frontend: Streamlit
• Database: SQLite (PostgreSQL-ready via SQLAlchemy)
• Testing: pytest

Project Structure

esw_app/          # FastAPI backend
  models/         # SQLAlchemy models (9 tables)
  schemas/        # Pydantic request/response models
  routers/        # API endpoints
  services/       # Business logic (rules engine, workflow, tokens, notifications)
  providers/      # E-signature providers (DocuSeal + stubs)

esw_frontend/     # Streamlit frontend
  pages/          # Dashboard, submit, approve, admin rules
  components/     # Shared UI components

API Documentation

Start the API and visit http://localhost:8000/docs for interactive Swagger documentation.

Running Tests

pip install -e ".[dev]"
pytest -v

Key API Endpoints

Method	Path	Description
POST	/api/contracts	Create contract (multipart)
POST	/api/contracts/{id}/submit	Submit for approval
GET	/api/approvals/by-token/{token}	Get approval details
POST	/api/approvals/by-token/{token}	Approve/reject
POST	/api/esignature/{id}/send	Trigger e-signature
GET	/api/dashboard/stats	Dashboard metrics

License

MIT License. Copyright (c) 2026 Noam Raz and Pleasant Secret Labs.