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