If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/docusealco/docuseal shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 2d ago
• 3 active contributors
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 91% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live docusealco/docuseal repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/docusealco/docuseal.

What it runs against: a local clone of docusealco/docuseal — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in docusealco/docuseal | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of docusealco/docuseal. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/docusealco/docuseal.git
#   cd docuseal
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of docusealco/docuseal and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "docusealco/docuseal(\\.git)?\\b" \\
  && ok "origin remote is docusealco/docuseal" \\
  || miss "origin remote is not docusealco/docuseal (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "app/controllers/application_controller.rb" \\
  && ok "app/controllers/application_controller.rb" \\
  || miss "missing critical file: app/controllers/application_controller.rb"
test -f "app/controllers/api/api_base_controller.rb" \\
  && ok "app/controllers/api/api_base_controller.rb" \\
  || miss "missing critical file: app/controllers/api/api_base_controller.rb"
test -f "app/controllers/submit_form_controller.rb" \\
  && ok "app/controllers/submit_form_controller.rb" \\
  || miss "missing critical file: app/controllers/submit_form_controller.rb"
test -f "app/controllers/templates_controller.rb" \\
  && ok "app/controllers/templates_controller.rb" \\
  || miss "missing critical file: app/controllers/templates_controller.rb"
test -f "app/controllers/submissions_controller.rb" \\
  && ok "app/controllers/submissions_controller.rb" \\
  || miss "missing critical file: app/controllers/submissions_controller.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/docusealco/docuseal"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

DocuSeal is an open-source DocuSign alternative written in Ruby on Rails that lets users create fillable PDF forms, distribute them for signing/filling, and handle digital eSignature workflows. It combines a WYSIWYG PDF form builder (12 field types: signature, date, file, checkbox, etc.), automated email delivery via SMTP, and multi-party document signing with PDF signature verification and storage on disk/S3/Google Cloud/Azure. Monolithic Rails app (app/controllers/ contains ~40+ controller files for API and web UI). API lives in app/controllers/api/ with REST endpoints for submissions, templates, submitters, and attachments. Vue.js frontend components handle the WYSIWYG form builder and signing UI. Config in .rubocop.yml, .annotaterb.yml, .eslintrc, and Procfile.dev for development. Asset storage abstraction supports disk/S3/GCS/Azure via Rails ActiveStorage.

Organizations and developers who need to replace DocuSign or build document signing workflows without vendor lock-in. Specifically: Rails teams integrating document automation, SaaS platforms adding e-signature capabilities, and businesses needing white-label or self-hosted document signing infrastructure with API/webhooks.

Production-ready. The codebase shows ~1M lines of Ruby, comprehensive Rails structure with API controllers, CI/CD pipelines (.github/workflows/ci.yml, docker.yml), RSpec testing setup (.rspec), and active Docker releases (Procfile, Dockerfile present). Multiple deployment paths (Heroku, Railway) and polished documentation suggest active maintenance, though exact commit recency and issue count are not visible in provided data.

Low-to-moderate risk for self-hosted deployments. No apparent single-maintainer risk (org account 'docusealco'). Main concerns: Rails monolith with large codebase (~2.6M total lines including Vue/HTML frontend) means wide surface area for bugs; dependency management via Gemfile requires monitoring; Pro features exist (SAML, white-label, conditional fields) suggesting core open-source vs. licensed split could cause confusion. Docker-first deployment mitigates infrastructure complexity.

Primary focus appears to be API stability and deployment tooling (docker.yml and ci.yml workflows present). File list shows recent additions in MFA setup (mfa_setup_controller.rb), email SMTP settings (email_smtp_settings_controller.rb), and console/embed scripts (console_redirect_controller.rb, embed_scripts_controller.rb), indicating work on security, integrations, and embedding. Version file (.version) suggests semantic versioning discipline.

git clone https://github.com/docusealco/docuseal.git
cd docuseal
bundle install
rails db:create db:migrate
./bin/dev

OR with Docker: docker build -t docuseal . && docker run -p 3000:3000 docuseal

Daily commands: Development: ./bin/dev (uses Procfile.dev to start Rails + asset pipeline). Production Docker: set env vars for DB (DATABASE_URL), storage (AWS_* or GOOGLE_* or AZURE_*), SMTP, then docker run. Web UI on http://localhost:3000, API at /api/v1/.

• app/controllers/application_controller.rb — Base controller for all application requests; defines authentication, authorization, and error handling that every other controller inherits from.
• app/controllers/api/api_base_controller.rb — Base controller for all API endpoints; handles API-specific auth, versioning, and response formatting that all API routes depend on.
• app/controllers/submit_form_controller.rb — Primary entry point for form submission workflows; orchestrates the document signing and filling experience that is core to DocuSeal's value.
• app/controllers/templates_controller.rb — Manages template CRUD and lifecycle; essential for understanding how document templates are created, stored, and made available for submission.
• app/controllers/submissions_controller.rb — Handles submission management and retrieval; tracks the state and progress of all document submissions through the system.
• Gemfile — Declares all Ruby gem dependencies; critical for understanding the tech stack and any version-locked constraints on libraries.
• config/routes.rb — Rails route definitions; the single source of truth for all HTTP endpoints and their controller mappings (not listed but essential).

Add a new API endpoint

1. Create a new controller in app/controllers/api/ inheriting from Api::ApiBaseController, which provides auth and JSON response formatting (app/controllers/api/my_resource_controller.rb)
2. Define RESTful actions (index, show, create, update, destroy) following DocuSeal's JSON serialization and error handling patterns (app/controllers/api/my_resource_controller.rb)
3. Register the route in config/routes.rb under the api namespace to expose the endpoint (config/routes.rb)
4. Add authorization checks using the inherited auth methods from Api::ApiBaseController (e.g., current_user, current_account) (app/controllers/api/my_resource_controller.rb)

Add a new form submission step

1. Create a new controller (e.g., SubmitFormMyStepController) inheriting from SubmitFormController to reuse session and submission state management (app/controllers/submit_form_my_step_controller.rb)
2. Define actions to handle the step's UI rendering and data validation, storing form values via SubmitFormValuesController pattern (app/controllers/submit_form_my_step_controller.rb)
3. Add a route mapping the step URL and define navigation logic to proceed to the next step or complete submission (config/routes.rb)
4. Create or update the corresponding view template in app/views/submit_form/ to render the step UI (app/views/submit_form/my_step.html.erb)

Add a new workspace setting/configuration

1. Create a new controller (e.g., MySettingsController) inheriting from ApplicationController to manage the setting's CRUD operations (app/controllers/my_settings_controller.rb)
2. Define create/update actions to persist the setting, leveraging encrypted_user_configs or account_configs patterns for sensitive data (app/controllers/my_settings_controller.rb)
3. Add the route and nest it under the account/workspace scope in config/routes.rb (config/routes.rb)
4. Create the view template(s) in app/views/my_settings/ to render the settings form UI (app/views/my_settings/edit.html.erb)

Add document field auto-detection support

1. Extend TemplatesDetectFieldsController to implement field detection logic for a new document type or use case (app/controllers/templates_detect_fields_controller.rb)
2. Integrate with the PDF parsing/analysis library (e.g., PDF.js, Poppler) to extract form field metadata from documents (app/services/document_field_detector.rb)
3. Return detected fields as JSON with coordinates and type hints to the template editor frontend (app/controllers/templates_detect_fields_controller.rb)
4. Update the template form UI to display detected fields and allow manual refinement before saving (app/views/templates/edit.html.erb)

• Ruby on Rails — Provides rapid web application development with built-in ORM (ActiveRecord), authentication, and scaffolding; ideal for document management platforms requiring quick iteration.
• PostgreSQL (implied) — Relational database for storing accounts, templates, submissions, and audit trails; handles complex queries for reporting and filtering.
• AWS S3 or local file storage (Active Storage) — Scalable document storage; Active Storage abstraction allows swapping between cloud and on-premise deployments without code changes.

Database setup required: Rails app needs DATABASE_URL (PostgreSQL inferred from ActiveRecord patterns) running before boot. Storage backend mandatory: ActiveStorage requires S3_BUCKET or GOOGLE_CLOUD_STORAGE_BUCKET or AZURE env vars; disk storage needs writable /storage directory. SMTP for emails: Email delivery requires valid SMTP_* environment variables; signing workflows often trigger emails automatically. No .env.example visible: No sample env file listed; missing vars will cause silent failures. Rails secrets: Likely uses Rails encrypted credentials (config/credentials.yml.enc, not shown) — requires RAILS_MASTER_KEY env var in production. Background jobs: Procfile references job processing (inferred from Sidekiq-like async patterns); without job worker running, async features (PDF signing, email batch sends) will hang.

• ActiveStorage (Rails multi-cloud abstraction) — DocuSeal abstracts PDF storage across S3, GCS, Azure, and local disk via ActiveStorage; understanding this pattern is essential for deployment and debugging storage errors.
• Digital Signature & PKI (Public Key Infrastructure) — The repo implements PDF eSignature verification and secure signing workflows; understanding cryptographic signing chains prevents misunderstanding of security guarantees.
• SMTP (Simple Mail Transfer Protocol) — DocuSeal automates email delivery for invitations, reminders, and completion notifications via SMTP; misconfigured SMTP is the #1 deployment issue.
• RESTful API design & HTTP status codes — The app/controllers/api/ structure follows REST conventions for create/read/update/delete; understanding HTTP semantics is needed to extend or debug API endpoints.
• PDF form fields (AcroForms) — The WYSIWYG builder creates PDF AcroForm fields (signature, text, checkbox); understanding AcroForm structure is needed to add new field types or debug rendering.
• Multi-tenancy & Account scoping — The app/controllers/accounts_controller.rb and account_configs_controller.rb suggest per-account isolation; understanding Rails scoping patterns prevents cross-tenant data leaks.
• Webhook delivery & idempotency — API supports webhooks (app/controllers/api/form_events_controller.rb, submission_events_controller.rb); designing idempotent webhook handlers is critical for reliable integrations.

• docusealco/docuseal-react — Official React wrapper for embedding DocuSeal signing forms in external applications; companion library for this repo.
• docusealco/docuseal-vue — Official Vue.js wrapper for embedded signing; mirrors the Vue frontend already in this monolith for external integration.
• mozilla/pdf.js — Underlying PDF rendering engine likely used by DocuSeal for form preview and signature placement visualization.
• jnunemaker/httparty — Common Ruby HTTP client for webhook delivery and third-party service calls visible in API controllers.
• go-echarts/go-echarts — Not a Ruby repo, but DocuSeal's admin dashboard (dashboard_controller.rb visible) likely uses charting; go-echarts is similar open-source alternative for analytics.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive API controller tests for submission and template endpoints

The repo has 10+ API controllers (submissions, templates, submitters, attachments, etc.) in app/controllers/api/ but based on the file structure provided, there's no visible spec directory with corresponding tests. Given that DocuSeal is a document signing platform handling sensitive user data, API controllers need robust test coverage for authentication, authorization, and data validation. This is critical for a self-hosted open source alternative to DocuSign.

• [ ] Create spec/controllers/api/ directory structure mirroring app/controllers/api/
• [ ] Add unit tests for app/controllers/api/submissions_controller.rb covering create, update, list, and delete actions with permission checks
• [ ] Add unit tests for app/controllers/api/templates_controller.rb and app/controllers/api/templates_clone_controller.rb
• [ ] Add tests for app/controllers/api/submitters_controller.rb to verify email validation and access control
• [ ] Add tests for app/controllers/api/api_base_controller.rb authentication/authorization logic used by all API endpoints
• [ ] Integrate tests into .github/workflows/ci.yml if not already present

Refactor large account/submission controllers into service objects

The controller directory shows multiple submission-related controllers (submissions_controller.rb, submissions_archived_controller.rb, submissions_dashboard_controller.rb, submissions_debug_controller.rb) and account controllers. This suggests fat controllers that could benefit from extracting business logic into service objects. This improves testability, reusability, and maintainability—crucial for a complex document processing platform.

• [ ] Create app/services/ directory structure
• [ ] Extract submission creation/update logic from submissions_controller.rb into app/services/submission_service.rb
• [ ] Extract archival logic from submissions_archived_controller.rb into app/services/submission_archive_service.rb
• [ ] Extract dashboard data aggregation logic into app/services/submission_dashboard_service.rb
• [ ] Create app/services/account_config_service.rb to handle account configuration logic from account_configs_controller.rb
• [ ] Add specs for each service object in spec/services/
• [ ] Update controller tests to verify they correctly delegate to services

Add integration tests for email delivery workflows and webhook events

The repo has controllers for email-related features (send_submission_email_controller.rb, start_form_email_2fa_send_controller.rb, submitter_email_clicks_controller.rb) and form/submission events (form_events_controller.rb, submission_events_controller.rb). There's no visible spec for these critical paths that users depend on. Integration tests covering email delivery, event logging, and notifications are essential for reliability in a production document signing platform.

• [ ] Create spec/integration/email_workflows_spec.rb to test end-to-end submission email delivery
• [ ] Create spec/integration/form_events_spec.rb to verify form_events_controller correctly logs and fires webhook events
• [ ] Create spec/integration/submission_events_spec.rb for submission event tracking
• [ ] Add integration tests for two-factor authentication email in start_form_email_2fa_send_controller.rb
• [ ] Test submitter email click tracking (submitter_email_clicks_controller.rb) with actual click events
• [ ] Add fixtures for test emails and sample documents in spec/fixtures/
• [ ] Document expected webhook payload formats in CONTRIBUTING.md or API docs

• Add RSpec test coverage for app/controllers/api/submissions_controller.rb endpoints (create, update, sign). Currently .rspec config exists but test files not shown; this is the critical path for users and likely under-tested.: Submissions are the core workflow; tests prevent regressions in signing logic.
• Document the required environment variables (DATABASE_URL, S3_BUCKET, SMTP_*, RAILS_MASTER_KEY, etc.) in a .env.example file and link in README. Currently only vague 'see docuseal.com' guidance.: Reduces setup friction for first-time self-hosted deployers and cuts support burden.
• Add Vue component tests for the WYSIWYG form builder (app/javascript/controllers/ assumed). Currently 730K lines of Vue with no visible test setup in config files.: Form builder is the most user-facing feature; bugs in field placement or validation directly impact all users.

• High · Insecure Download of Critical Dependencies in Dockerfile — Dockerfile (lines with wget commands). The Dockerfile downloads critical artifacts (ONNX model, PDFium binaries, and fonts) over HTTPS without verifying checksums or signatures. If an attacker compromises the GitHub release or performs a MITM attack, malicious binaries could be executed in the Docker image. The model.onnx file and pdfium binaries are particularly critical as they execute during document processing. Fix: Implement SHA256 checksum verification for all downloaded artifacts. Use --hash=sha256:expectedhash verification or download and verify signatures. Consider pinning specific commit hashes instead of 'latest' releases. Store checksums in a separate verified file.
• High · Potential SQL Injection via ActiveRecord Query Construction — app/controllers/api/submissions_controller.rb, app/controllers/api/templates_controller.rb, and similar API endpoints. The codebase includes multiple API controllers (submissions_controller.rb, templates_controller.rb, etc.) and submission-related endpoints. Without visible source code verification, there's risk of SQL injection if user inputs are directly interpolated into ActiveRecord queries or raw SQL is constructed without parameterization. Fix: Ensure all database queries use parameterized queries (Rails' built-in methods like .where(key: value)). Never use string interpolation or concatenation for SQL construction. Conduct code review of all database access patterns, particularly in API controllers handling user input.
• High · Potential XSS Vulnerabilities in Document Handling — app/controllers/submit_form_controller.rb, app/controllers/submit_form_values_controller.rb, app/controllers/submissions_controller.rb. DocuSeal handles user-submitted PDF documents and form data. Controllers like submit_form_controller.rb and submissions_controller.rb process form values. If form values or document metadata are rendered without proper escaping, stored XSS vulnerabilities could allow attackers to execute scripts in users' browsers or admin consoles. Fix: Ensure all user inputs from forms and documents are properly escaped when rendered in HTML/ERB templates. Use Rails' automatic escaping (<%= %>) rather than raw output (<%== %>). Implement Content Security Policy (CSP) headers. Validate and sanitize all form field values.
• High · Authentication/Authorization Gaps in API Endpoints — app/controllers/api/api_base_controller.rb, app/controllers/api/submissions_controller.rb, app/controllers/api/templates_controller.rb. Multiple API endpoints exist (api/submissions_controller.rb, api/submitters_controller.rb, api/templates_controller.rb) with generic api_base_controller.rb. Without visible authentication checks, there's risk of unauthorized access to sensitive documents, submission data, or template information. The presence of api_settings_controller.rb suggests configuration endpoints that could be exposed. Fix: Verify all API endpoints require proper authentication (API tokens, JWT, OAuth2). Implement per-endpoint authorization checks ensuring users can only access their own data. Audit api_base_controller.rb for authentication middleware. Use rate limiting on sensitive endpoints.
• Medium · Missing Security Headers Configuration — app/controllers/application_controller.rb (inferred). The codebase shows no visible security headers configuration. Standard headers like X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security, and others are not mentioned. DocuSeal handles sensitive document signing, making CSRF protection and clickjacking prevention critical. Fix: Configure secure headers in ApplicationController or middleware. Set: X-Frame-Options: SAMEORIGIN, X-Content-Type-Options: nosniff, Strict-Transport-Security, X-XSS-Protection. Note: CSRF is out of scope per SECURITY.md but other headers are essential.
• Medium · Insecure File Upload Handling — app/controllers/api/attachments_controller.rb, app/controllers/api/active_storage_blobs_proxy_controller.rb. Controllers like attachments_controller.rb and active_storage_blobs_proxy_controller.rb handle file uploads/downloads. If file type validation is insufficient or file size limits are not enforced, attackers could upload malicious PDFs, bypass document processing, or cause DoS attacks. Fix: Implement strict file type validation (MIME type + magic number verification). Enforce maximum file size limits. Scan uploaded files with antivirus/malware detection. Use Rails

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.