doc-assembly

doc-assembly

Multi-tenant document template builder with digital signature delegation.

Go 1.25 · React 19 · PostgreSQL 16 · Typst

Table of Contents

• Overview
• Monorepo Structure
• Architecture
• Quick Start
• Available Commands
• Configuration
• Digital Signatures
• Background Workers (River)
• Database
• Deployment
• Documentation
• License

Overview

doc-assembly lets organizations build reusable document templates with a rich text editor, inject dynamic data through a variable system, render production-quality PDFs via Typst, and delegate digital signatures to external providers.

The platform is multi-tenant by design: a three-level RBAC model (System, Tenant, Workspace) controls access, while the backend enforces tenant isolation across every query.

Key Features

• Rich text template editor (TipTap) with injectable variables and signature blocks
• PDF rendering powered by Typst (no browser/Chromium dependency)
• Digital signature delegation to Documenso (PandaDoc and DocuSign interfaces planned)
• Three-level RBAC: System, Tenant, and Workspace roles
• Template versioning with publish/archive lifecycle
• Extensibility system via code-generated injectors and mappers
• Internationalization (English & Spanish)
• Folder and tag organization for templates

Monorepo Structure

doc-assembly/
  core/       Go backend (Hexagonal Architecture, Gin, Wire DI)
  app/        React SPA (TanStack Router, Zustand, TipTap)
  db/         Liquibase migrations (PostgreSQL 16)
  docs/       All project documentation
  scripts/    Tooling (docml2json, etc.)

Architecture

Request Flow (Hexagonal)

HTTP Request
 -> Middleware (JWT auth, tenant context, operation ID)
   -> Controller (parse DTO, validate)
     -> UseCase interface
       -> Service (business logic)
         -> Port interface
           -> Repository (SQL via pgx)
             -> PostgreSQL

Multi-Tenant Hierarchy

System
 +-- Tenant A
 |    +-- Workspace 1
 |    +-- Workspace 2
 +-- Tenant B
      +-- Workspace 3

RBAC

Three authorization levels with seven roles:

SUPERADMIN auto-elevates to OWNER in any tenant or workspace.

Quick Start

Prerequisites

Run make doctor to verify all dependencies are installed.

1. Clone and install dependencies

git clone https://github.com/your-org/doc-assembly.git
cd doc-assembly
pnpm install --dir apps/web-client
go -C apps/doc-engine mod download

2. Start PostgreSQL

docker compose -f docker-compose.dev.yml up -d

This starts PostgreSQL 16 on port 5432.

3. Run database migrations

cd db && ./run-migrations.sh && cd ..

4. Start dev servers

make dev-dummy

[!TIP] dev-dummy bypasses JWT authentication so you can develop without setting up Keycloak. The backend runs on :8080 and the frontend on :3001.

The app is now available at http://localhost:3001. The first user to sign up is automatically promoted to SUPERADMIN.

Available Commands

Run make help for the full list.

Pass DUMMY=1 to any target to enable dummy auth: make run DUMMY=1.

Configuration

Backend

Configuration is loaded from apps/doc-engine/settings/app.yaml and can be overridden with environment variables following the pattern DOC_ENGINE_<SECTION>_<KEY>.

Copy the example env file and fill in values:

cp apps/doc-engine/.env.example apps/doc-engine/.env

Key variables:

* Not required when DOC_ENGINE_AUTH_DUMMY=true.

[!NOTE] See apps/doc-engine/settings/app.yaml for all available options including storage, logging, scheduler, Typst renderer, and notification settings.

Frontend

cp apps/web-client/.env.example apps/web-client/.env

Digital Signatures

doc-assembly delegates digital signatures to external providers. Each document has a shared public URL (/public/doc/{id}) that recipients use to verify their email and receive a signing link.

Template (published)
  -> Admin creates document
    -> Recipients notified with public URL (/public/doc/{id})
      -> Recipient visits URL, enters email
        -> System verifies email, sends token link (/public/sign/{token})
          -> Path A (no interactive fields): PDF preview -> Sign
          -> Path B (interactive fields): Fill form -> PDF preview -> Sign
            -> Signing provider handles signature -> Webhooks update status -> Sealed PDF stored

For detailed flow documentation with sequence diagrams, see Public Signing Flow.

Supported Providers

Local Documenso Setup

docker compose -f docker-compose.documenso.yml up -d

[!IMPORTANT] The compose file includes a documenso-cert-init service that auto-generates a self-signed P12 certificate for document sealing. No manual certificate setup is needed.

This starts:

• Documenso on http://localhost:3000
• MailPit (SMTP) on http://localhost:8025 (web UI) and :1025 (SMTP)
• PostgreSQL for Documenso on port 5433

Configure the webhook in Documenso to point to http://host.docker.internal:8080/webhooks/signing/documenso.

Background Workers (River)

Signing execution is attempt-scoped and durable. execution.documents is the business projection, while execution.signing_attempts is the technical source of truth for render, provider submission, retry/reconciliation, cleanup, refresh, and completion dispatch. River runs inside the API process and stores jobs in PostgreSQL; no external broker is required.

Attempt-scoped jobs

ProceedToSigning creates or reuses the active signing attempt and enqueues River work transactionally. Provider upload does not happen inline in the public/authenticated request path.

/public/sign/{token}/proceed
  -> create/reuse active SigningAttempt
  -> INSERT river_job(render_attempt_pdf) in same PostgreSQL transaction
  -> frontend receives step=processing and polls

River render_attempt_pdf
  -> render immutable pre-signed PDF
  -> persist PDF path/checksum + enqueue submit_attempt_to_provider in one transaction

River submit_attempt_to_provider
  -> submit PDF snapshot to provider using correlation key {document_id}:{attempt_id}
  -> persist provider IDs + READY_TO_SIGN projection

Provider webhook
  -> resolve active attempt
  -> update attempt + document projection
  -> enqueue dispatch_attempt_completion in the same transaction

Key properties

SDK Usage

import "github.com/rendis/doc-assembly/core/sdk"

handler := func(ctx context.Context, ev sdk.DocumentCompletedEvent) error {
    log.Printf("Document %s completed in tenant %s", ev.DocumentID, ev.TenantCode)
    for _, r := range ev.Recipients {
        log.Printf("  %s (%s) signed at %v", r.Name, r.RoleName, r.SignedAt)
    }
    return nil // return error to retry completion dispatch
}

Configuration

worker:
  enabled: false              # DOC_ENGINE_WORKER_ENABLED
  max_workers: 10             # DOC_ENGINE_WORKER_MAX_WORKERS
  runtime_environment: local  # DOC_ENGINE_WORKER_RUNTIME_ENVIRONMENT
  failpoints_enabled: false   # DOC_ENGINE_WORKER_FAILPOINTS_ENABLED (dev/test only)
  failpoints: []              # DOC_ENGINE_WORKER_FAILPOINTS

For architecture diagrams, attempt job details, failpoints, and integration test coverage, see Worker Queue Guide.

Database

PostgreSQL 16 with five schemas:

Migrations are managed with Liquibase:

cd db && ./run-migrations.sh

[!WARNING] Do not modify migration files in db/src/ directly. Suggest changes and create new changesets instead.

See db/DATABASE.md for the complete schema documentation.

Deployment

Docker Build

docker build -f apps/doc-engine/Dockerfile -t doc-engine .

The Dockerfile uses a multi-stage build:

1. Builder: golang:1.25-alpine compiles the binary
2. Runtime: alpine:3.21 with Typst v0.13.1 and ca-certificates

The container exposes port 8080.

Required Environment Variables (Production)

Documentation

License

This project is licensed under the MIT License.