diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..fb66d472 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,271 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Overview + +DocuSeal is an open-source document signing and filling platform built with Ruby on Rails 8.1. It provides secure PDF form creation, digital signatures, and document processing with a mobile-optimized interface. + +**Key Technologies:** +- Backend: Rails 8.1 with Ruby 4.0.1 +- Database: PostgreSQL (default), MySQL/Trilogy, or SQLite3 +- Frontend: Vue 3 components with Hotwire Turbo, Tailwind CSS + DaisyUI +- JavaScript bundling: Shakapacker (webpack) +- Background jobs: Sidekiq +- PDF processing: HexaPDF, ruby-vips, pdfium +- Storage: Local disk, AWS S3, Google Cloud Storage, or Azure Blob + +## Development Commands + +### Setup +```bash +# Install dependencies +bundle install +yarn install + +# Setup database +rails db:create db:migrate + +# Start development servers (Rails + webpack dev server) +foreman start -f Procfile.dev +# Or individually: +# rails s -p 3000 +# ./bin/shakapacker-dev-server +``` + +### Testing +```bash +# Run all specs +bundle exec rspec + +# Run specific test file +bundle exec rspec spec/requests/api/submissions_spec.rb + +# Run system tests (with browser) +HEADLESS=false bundle exec rspec spec/system/ + +# Run with coverage +COVERAGE=true bundle exec rspec +``` + +### Code Quality +```bash +# Lint Ruby code +bundle exec rubocop + +# Lint Ruby code with auto-fix +bundle exec rubocop -A + +# Lint JavaScript/Vue +yarn eslint + +# Lint ERB templates +bundle exec erblint --lint-all + +# Security scan +bundle exec brakeman +``` + +### Database +```bash +# Create migration +rails g migration AddFieldToTable field:type + +# Run migrations +rails db:migrate + +# Rollback +rails db:rollback + +# Reset database (drop, create, migrate, seed) +rails db:reset +``` + +### Assets +```bash +# Precompile assets for production +rails assets:precompile + +# Compile webpack bundles +./bin/shakapacker +``` + +## Architecture + +### Backend Structure + +**Core Models:** +- `Account` - Multi-tenant account/organization +- `User` - User authentication and management (Devise) +- `Template` - PDF form template with field definitions +- `Submission` - Document instance created from template +- `Submitter` - Individual who fills/signs a submission +- `CompletedSubmitter` - Final state after signing +- `CompletedDocument` - Generated signed PDF documents + +**Key Service Modules (lib/):** +- `Submissions` - Handle submission lifecycle +- `Submitters` - Manage submitter workflow +- `Templates` - Template operations and cloning +- `Accounts` - Account configuration +- `PdfUtils` - PDF processing and manipulation +- `DownloadUtils` - File download handling +- `SendWebhookRequest` - Webhook delivery + +**Background Jobs (app/jobs/):** +- Document generation +- Email sending +- Webhook delivery +- File processing + +**Controllers:** +- Standard Rails controllers in `app/controllers/` +- API namespace in `app/controllers/api/` with JSON responses +- RESTful design following Rails conventions + +### Frontend Structure + +**Custom Web Components (`app/javascript/elements/`):** +- Built with `@github/catalyst` for custom element registration +- Located in `app/javascript/elements/` +- Examples: `file_dropzone.js`, `clipboard_copy.js`, `fetch_form.js` +- Autonomous, reusable components following web standards + +**Vue 3 Applications:** +- `template_builder/` - WYSIWYG PDF form builder + - Drag-and-drop field placement + - Field settings and validation + - Multi-submitter support +- `submission_form/` - Document signing interface + - Step-by-step submission flow + - Signature capture + - Field completion + +**Styling:** +- Tailwind CSS utility classes +- DaisyUI component library +- Multiple Tailwind configs: + - `tailwind.config.js` - Main application + - `tailwind.application.config.js` - Application-specific + - `tailwind.form.config.js` - Form-specific + +**JavaScript Entry Points:** +- `application.js` - Main app bundle +- `form.js` - Public form bundle +- `draw.js` - Drawing/signature tools + +### Database Configuration + +The app supports multiple database adapters configured via environment variables: + +- **PostgreSQL** (default for dev/test): Set `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_USER`, `DATABASE_PASSWORD`, `DATABASE_NAME` +- **MySQL/Trilogy**: Set `DATABASE_URL` with `mysql://` or `trilogy://` protocol +- **SQLite3**: Default for production when no DATABASE_URL is set + +Connection pool size: `RAILS_MAX_THREADS` (default 15) + `SIDEKIQ_THREADS` (default 5) + +### API + +RESTful JSON API at `/api/*`: +- Authentication via access tokens +- Endpoints for submissions, templates, submitters, attachments +- Event tracking endpoints +- Webhook support for integrations +- See `config/routes.rb` API namespace for full endpoint list + +### Testing + +**Test Framework:** RSpec with FactoryBot + +**Test Types:** +- Request specs (`spec/requests/`) - API endpoint testing +- System specs (`spec/system/`) - Full browser integration tests using Cuprite (headless Chrome) +- Job specs (`spec/jobs/`) - Background job testing +- Mailer specs (`spec/mailers/`) + +**Test Configuration:** +- Capybara with Cuprite driver for system tests +- WebMock for HTTP request stubbing +- Sidekiq testing (fake mode default, inline for specific tests) +- SimpleCov for coverage (enable with `COVERAGE=true`) +- Headful mode for debugging: `HEADLESS=false bundle exec rspec` + +### Deployment + +**Docker:** +```bash +docker run --name docuseal -p 3000:3000 -v.:/data docuseal/docuseal +``` + +**Docker Compose:** +```bash +curl https://raw.githubusercontent.com/docusealco/docuseal/master/docker-compose.yml > docker-compose.yml +sudo HOST=your-domain.com docker compose up +``` + +**Supported Platforms:** +- Heroku, Railway, DigitalOcean, Render +- See README.md for one-click deploy buttons + +### Environment Configuration + +Key environment variables: +- `DATABASE_URL` - Database connection string +- `HOST` - Application host domain +- `APP_URL` - Application URL (default: http://localhost:3000) +- `MULTITENANT` - Enable multi-tenant mode +- Storage: `AWS_*`, `GOOGLE_*`, `AZURE_*` configs +- SMTP: Email delivery configuration +- `CERTS` - Custom SSL certificates (JSON) +- `TIMESERVER_URL` - Timestamp server for signatures + +### Multitenant Support + +The app supports multitenant deployment via `MULTITENANT=true`: +- Account-scoped data isolation +- Subdomain-based routing +- Console interface at `console.#{HOST}` +- CDN at `cdn.#{HOST}` + +### Key Libraries and Patterns + +**Authentication:** Devise with 2FA (TOTP) support via `devise-two-factor` + +**Authorization:** CanCanCan for permissions + +**PDF Processing:** +- HexaPDF for PDF generation and manipulation +- ruby-vips for image processing +- pdfium bindings for advanced PDF operations + +**Background Jobs:** Sidekiq with Redis + +**Frontend State Management:** +- Vue 3 Composition API +- Turbo Drive for page navigation +- Custom elements for isolated widgets + +**File Storage:** ActiveStorage with multiple backends (disk, S3, GCS, Azure) + +**API Integrations:** +- Webhooks for events +- REST API with JWT authentication +- Embedded signing widgets (React/Vue/Angular npm packages available) + +### Code Style and Conventions + +- Ruby: Follow Rubocop rules in `.rubocop.yml` (Standard Ruby style) +- JavaScript: ESLint with Standard style + Vue 3 recommended rules +- ERB: erb_lint for template validation +- Vue: Single-file components with `