docuseal/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is DocuSeal - an open-source document filling and signing platform built with Ruby on Rails. The codebase is a brownfield Rails 7 application that provides secure digital document signing with PDF form building, multi-signer workflows, and API/webhook integrations.

Tech Stack

Backend:

• Ruby 3.4.2, Rails 7.x
• PostgreSQL/MySQL/SQLite (via DATABASE_URL)
• Sidekiq for background jobs
• Devise for authentication with 2FA support
• Cancancan for authorization
• HexaPDF for PDF generation and signing

Frontend:

• Vue.js 3 with Composition API
• TailwindCSS 3.4.17 + DaisyUI 3.9.4
• Shakapacker 8.0 (Webpack)
• Hotwire Turbo for Rails UJS

Storage:

• Active Storage with S3, Google Cloud, Azure, or local disk
• Supports multiple storage backends simultaneously

Common Commands

Development

# Start development server
bin/rails server

# Start with foreman (includes Sidekiq)
bundle exec foreman start -f Procfile.dev

# Run specific test
bundle exec rspec spec/path/to/spec.rb:line_number

# Run all tests
bundle exec rspec

# Lint Ruby
bundle exec rubocop -A

# Lint JavaScript/Vue
yarn eslint app/javascript/**/*.{js,vue} --fix

# Run database migrations
bin/rails db:migrate

# Setup database from scratch
bin/rails db:setup

Production

# Precompile assets
bin/rails assets:precompile

# Start production server
bundle exec puma -C config/puma.rb

# With Docker
docker run --name docuseal -p 3000:3000 -v.:/data docuseal/docuseal

Architecture

Core Models Hierarchy

Account (Tenant/Organization)
├── Users (Devise authentication)
├── Templates (Document templates with form fields)
│   ├── TemplateDocuments (PDF files)
│   └── TemplateFolders (Organization)
├── Submissions (Completed document workflows)
│   ├── Submitters (Signers/participants)
│   ├── CompletedDocuments (Final PDFs)
│   └── SubmissionEvents (Audit trail)
└── AccountConfig (Settings)

Key Concepts

Templates:

• WYSIWYG PDF form builder with 12 field types (Signature, Date, File, Checkbox, etc.)
• Supports PDF upload or HTML-based template creation
• Multiple submitters per template
• Field tagging system for dynamic content

Submissions:

• Multi-signer document workflows
• State tracking (pending → completed)
• Email notifications and reminders
• Document generation and signing

Submitters:

• Individual participants in a submission
• Can fill and sign specific fields
• Receive email invitations and reminders
• Support for 2FA and identity verification

Directory Structure

app/models/ - Core business logic

• submission.rb, submitter.rb, template.rb - Main entities
• user.rb, account.rb - Authentication and multi-tenancy
• All models inherit from ApplicationRecord with strip_attributes

app/controllers/ - Request handling

• RESTful controllers for templates, submissions, submitters
• API controllers under app/controllers/api/
• Settings controllers for user/account configuration

app/javascript/ - Frontend code

• application.js - Main entry point with Vue app initialization
• template_builder/ - PDF form builder UI
• elements/ - Custom web components (Web Components + Vue)
• submission_form/ - Multi-step signing interface

lib/ - Utility modules

• submissions.rb, submitters.rb - Business logic helpers
• pdf_utils.rb, pdfium.rb - PDF processing
• send_webhook_request.rb - Webhook handling

config/ - Rails configuration

• routes.rb - Main routing (includes API routes)
• database.yml - Database configuration
• shakapacker.yml - Webpack configuration

Authentication & Authorization

Authentication:

• Devise with modules: database_authenticatable, registerable, recoverable, rememberable, validatable, omniauthable, two_factor_authenticatable
• JWT tokens for API access
• OAuth support via omniauth

Authorization:

• Cancancan with Ability class
• Role-based access control via AccountAccess model
• Template and submission sharing via TemplateSharing

PDF Processing

HexaPDF is used for:

• PDF generation from templates
• Form field rendering
• Digital signature embedding
• Signature verification

PDFium provides:

• PDF rendering and preview
• Document manipulation
• Multi-page handling

API Structure

Base URL: /api/v1/

Key Endpoints:

• POST /templates - Create template
• POST /submissions - Start submission workflow
• GET /submissions/:id - Get submission status
• POST /submitters/:id/complete - Complete submitter workflow
• POST /webhooks - Webhook events

Authentication: Bearer token in Authorization header

Webhooks

Events:

• submission.created - New submission started
• submission.completed - All signers finished
• submitter.completed - Individual signer finished
• template.created - New template

Delivery: POST to configured URLs with JSON payload, retry with exponential backoff

Background Jobs (Sidekiq)

Queues:

• default - General tasks
• mailers - Email delivery
• webhooks - Webhook delivery
• pdf - PDF generation

Key Jobs:

• SubmissionEmailJob - Send submission invitations
• ReminderJob - Send reminder emails
• WebhookDeliveryJob - Deliver webhook events
• DocumentGenerationJob - Generate final PDFs

Database Schema

Core Tables:

• accounts - Multi-tenancy root
• users - Devise authentication
• templates - Document templates
• submissions - Document workflows
• submitters - Signers/participants
• completed_documents - Final signed PDFs
• template_documents - Template PDF files

Supporting Tables:

• account_access - User permissions
• template_sharing - Template sharing links
• submission_events - Audit trail
• webhook_events - Webhook delivery tracking
• email_events - Email delivery tracking

Configuration

Environment Variables:

• DATABASE_URL - Database connection
• SECRET_KEY_BASE - Rails secrets
• AWS_*, GOOGLE_*, AZURE_* - Storage configs
• SMTP_* - Email delivery
• REDIS_URL - Sidekiq backend

Feature Flags:

• Docuseal.multitenant? - Multi-tenant mode
• Docuseal.pro? - Pro features enabled

Testing

RSpec with:

• spec/models/ - Model specs
• spec/requests/ - API/request specs
• spec/system/ - System/feature specs
• spec/factories/ - FactoryBot factories

Helpers:

• signing_form_helper.rb - Form signing utilities
• rails_helper.rb - Rails test configuration

BMAD Core Integration

This repository uses BMAD Core for AI-assisted development:

• Configuration: .bmad-core/core-config.yaml
• Tasks: .bmad-core/tasks/ (e.g., create-doc.md, document-project.md)
• Templates: .bmad-core/templates/ (e.g., brownfield-prd-tmpl.yaml)
• Agents: .bmad-core/agent-teams/

Slash Commands:

• /BMad:agents:pm - Product Manager agent
• /BMad:agents:dev - Developer agent

FloDoc Enhancement (Current Work)

Context: Transforming DocuSeal into a 3-portal cohort management system for training institutions.

Key Changes:

• New models: Cohort, CohortEnrollment, Institution, Sponsor
• Three portals: Admin, Student, Sponsor
• Workflow: Admin creates cohort → Students enroll → Admin verifies → Sponsor signs → Admin finalizes
• Excel export for cohort data (FR23)
• Custom UI/UX (not DaisyUI)

PRD Location: docs/prd.md

Important Files

• README.md - Project overview and deployment
• SECURITY.md - Security policy
• Gemfile - Ruby dependencies
• package.json - JavaScript dependencies
• config/routes.rb - All routes including API
• app/models/user.rb - Authentication model
• app/javascript/application.js - Frontend entry point

Gotchas

1. Multi-tenancy: Check Docuseal.multitenant? before assuming single-account mode
2. Storage: Active Storage configs in config/storage.yml and lib/load_active_storage_configs.rb
3. PDF Processing: HexaPDF requires proper license for commercial use
4. Sidekiq: Requires Redis connection, configured via REDIS_URL
5. Devise 2FA: Requires devise-two-factor setup per user
6. Vue + Rails: Uses Shakapacker, not standard Webpack config
7. Email Templates: Stored in app/views/mailers/, use ERB variables

Common Issues

Database errors: Run bin/rails db:setup or check DATABASE_URL Asset compilation: Run bin/rails assets:precompile for production Sidekiq not processing: Check Redis connection and config/sidekiq.yml PDF generation fails: Verify HexaPDF installation and PDF permissions Webhook delivery fails: Check network access and SSL certificates

Next Steps for FloDoc Enhancement

1. Architect Review: Winston needs to review authentication strategy and multi-tenancy
2. Database Migrations: Create new tables for cohorts, enrollments, institutions
3. Portal Development: Build three separate Vue portals
4. Workflow Integration: Connect to existing DocuSeal submission system
5. Excel Export: Implement using rubyXL gem (already in Gemfile)
6. Testing: Add specs for new cohort workflows