mirror of https://github.com/docusealco/docuseal
This file provides guidance for Claude Code when working in this repository, including: - Development commands for testing, linting, and database management - Architecture overview of Rails backend and Vue frontend - Testing structure with RSpec, Capybara, and Cuprite - Deployment configurations for Docker and cloud platforms - Key libraries, patterns, and conventions - Multitenant support and environment configuration Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>pull/599/head
Marcelo Paiva
1 month ago
parent
6ab68cc36b
commit
bb7a233863
@ -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 `<script setup>` or Options API
|
||||||
|
- Frozen string literals enabled by default
|
||||||
|
- Rails 8.1 conventions and best practices
|
||||||
|
|
||||||
|
### Accessibility Focus
|
||||||
|
|
||||||
|
This codebase is specifically being enhanced for accessibility (a11y). When making changes:
|
||||||
|
- Follow WCAG 2.2 guidelines
|
||||||
|
- Test with screen readers
|
||||||
|
- Ensure keyboard navigation
|
||||||
|
- Maintain proper ARIA labels
|
||||||
|
- Check color contrast ratios
|
||||||
Loading…
Reference in new issue