Skip to content

Developer Guide

Technical Reference

Architecture, API endpoints, and integration details for Signly.

Architecture

┌──────────────┐     ┌──────────────┐     ┌─────────────┐
│   Dashboard  │     │  Upload      │     │  Signing    │
│  (SvelteKit) │     │  (SvelteKit) │     │  (SvelteKit)│
└──────┬───────┘     └──────┬───────┘     └──────┬──────┘
       │                    │                    │
       └────────────────────┼────────────────────┘
                            │
                    ┌───────▼───────┐
                    │   Supabase    │
                    │  (PostgreSQL) │
                    └───────┬───────┘
                            │
              ┌─────────────┼──────────────┐
              │             │              │
        ┌─────▼───┐  ┌──────▼─────┐  ┌────▼────┐
        │Cloudflare│  │  Singpass  │  │ pdf-lib │
        │ R2 Storage│  │  OIDC Auth │  │ (PDF)   │
        └─────────┘  └────────────┘  └─────────┘

Tech Stack

  • Frontend: SvelteKit with TypeScript
  • Database: Supabase (PostgreSQL)
  • Storage: Cloudflare R2 (S3-compatible)
  • Authentication: Singpass OIDC + Custom session management
  • PDF Processing: pdf-lib for digital stamp generation
  • Deployment: Cloudflare Workers

Key Components

PDF Signing Engine (src/lib/server/pdf.ts)

The core signing logic:

  • Stamp Generation — Creates a visual signature card with signer name, date, and QR code
  • Positioning:
  • FlowForms integration: Uses exact coordinates from form system
  • Manual uploads: Offset of 15px left, 20px up from viewer coordinates

Singpass Integration

  • OIDC Flow: Standard OpenID Connect with Singpass
  • ES256 Signing: Uses EC private keys for JWT signing
  • Callback: Redirect URI configured in environment variables

Document Storage

  • Upload: PDFs stored in Cloudflare R2
  • Signed documents: Processed PDF saved back to R2
  • Security: Signed URLs for temporary access

Environment Variables

# Supabase
PUBLIC_SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Cloudflare R2
R2_ACCESS_KEY_ID=your-r2-key
R2_SECRET_ACCESS_KEY=your-r2-secret
R2_BUCKET_NAME=signly-documents
R2_ACCOUNT_ID=your-account-id

# Singpass
SINGPASS_CLIENT_ID=your-client-id
SINGPASS_EC_SIG_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----..."
SINGPASS_EC_ENC_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----..."
SINGPASS_REDIRECT_URI=https://your-domain.com/api/CallbackSP

# Security
VERIFICATION_FROM_FORMS=your-flowforms-secret

Database Schema

Key tables:

Table Purpose
signer_documents Document metadata, signer status, coordinates
signer_users User identity and Singpass verification status
credits Credit balance (shared with Guidesify platform)

API Endpoints

Endpoint Method Purpose
/api/upload POST Upload a document for signing
/api/send POST Send document to signers
/api/sign POST Apply signature to document
/api/CallbackSP GET Singpass OIDC callback

FlowForms Integration

Signly integrates with FlowForms to automatically create signing requests:

  1. FlowForms submission triggers a webhook to Signly
  2. Document is auto-generated from form data
  3. Signing request created with signer details from the form
  4. Status updates sent back to FlowForms

Configuration: Set VERIFICATION_FROM_FORMS secret for secure cross-service communication.