core/

Doc Engine

Document Assembly System API - A microservice for template management and document generation.

Table of Contents

• Doc Engine
  • Table of Contents
  • Overview
  • Architecture
  • Tech Stack
  • Prerequisites
    • Install Tools
  • Getting Started
    • 1. Clone and Setup
    • 2. Configuration
    • 3. Build and Run
  • Configuration
    • Server
    • Database (PostgreSQL)
    • Auth (Keycloak/JWKS)
    • Internal API
    • Documenso (e-signature)
    • Storage (S3/MinIO)
    • Logging
  • API Endpoints
  • Sandbox & Promotion
  • Development
    • Make Commands
    • Code Style
    • Logging
  • Extensibility
  • Integration Tests
  • Role-Based Access Control

Overview

Doc Engine is a Go-based microservice that provides:

• Workspace Management: Multi-tenant workspace organization with role-based access control
• Template Management: Create, edit, publish, and clone document templates
• Injectable Variables: Define and manage dynamic variables for document generation
• Folder Organization: Hierarchical folder structure for template organization
• Tag System: Flexible tagging for template categorization
• Signer Role Management: Configure signature roles and anchors for e-signature integration

Architecture

The project follows Hexagonal Architecture (Ports and Adapters) with domain-based organization.

For detailed architecture documentation including directory structure, domain organization, and entity files, see docs/backend/architecture.md.

Tech Stack

Prerequisites

• Go 1.25+
• PostgreSQL 15+
• golangci-lint (for linting)
• Wire CLI (for dependency injection)
• swag CLI (for Swagger docs)

Install Tools

# Wire
go install github.com/google/wire/cmd/wire@latest

# Swagger
go install github.com/swaggo/swag/cmd/swag@latest

# golangci-lint
brew install golangci-lint  # macOS

# or
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Getting Started

1. Clone and Setup

cd apps/doc-engine
go mod tidy

2. Configuration

Default values are defined in settings/app.yaml. Override them using environment variables with the DOC_ENGINE_ prefix:

export DOC_ENGINE_DATABASE_PASSWORD=your_password
export DOC_ENGINE_AUTH_JWKS_URL=https://your-keycloak/realms/your-realm/protocol/openid-connect/certs
export DOC_ENGINE_AUTH_ISSUER=https://your-keycloak/realms/your-realm

3. Build and Run

# Using Makefile with default .env
make build
make run

# Or specify a custom env file
make run ENV_FILE=.env.production

# Or directly (requires manually setting env vars)
go build -o bin/doc-engine ./cmd/api
./bin/doc-engine

Configuration

Configuration is loaded from settings/app.yaml and can be overridden with environment variables using the prefix DOC_ENGINE_.

Copy .env.example to .env and configure the required values.

Server

Database (PostgreSQL)

Auth (Keycloak/JWKS)

Internal API

Internal API keys are managed via the admin UI (Administration > API Keys, type "internal").

Documenso (e-signature)

Storage (S3/MinIO)

Logging

API Endpoints

For a complete list of API endpoints, authentication requirements, roles, and required headers, see docs/backend/authorization-matrix.md.

Public Signing Flow

Documents use a shared public URL with email verification. Recipients enter their email to receive a token-based signing link. The flow supports two paths: direct signing (no interactive fields) and form-first signing (with interactive fields).

For detailed documentation including sequence diagrams, security measures, and configuration, see docs/backend/public-signing-flow.md.

Sandbox & Promotion

Doc Engine supports sandbox environments for template development and testing before promoting to production.

For complete documentation on sandbox mode, promotion flow, and examples, see docs/backend/sandbox-promotion.md.

Development

Make Commands

make help             # Show all available commands
make build            # Build the binary
make run [ENV_FILE]   # Build and run (default: .env)
make test             # Run unit tests with coverage
make test-integration # Run integration tests (requires Docker)
make test-all         # Run all tests (unit + integration)
make coverage         # Open HTML coverage report (run 'make test' first)
make coverage-all     # Run all tests and open HTML coverage report
make lint             # Run golangci-lint
make wire             # Generate Wire DI code
make swagger          # Generate Swagger docs
make gen              # Generate all (Wire + Swagger)
make tidy             # Tidy dependencies
make clean            # Clean build artifacts
make dev              # Run with hot reload (requires air)

Code Style

The project uses golangci-lint with errcheck, gosimple, govet, staticcheck, unused, gofmt, goimports, misspell, gocritic, revive, gosec, errorlint, exhaustive.

Run make lint before committing. For comprehensive Go coding standards, see docs/backend/go-best-practices.md.

Logging

The project uses Go's standard log/slog package with a context-based handler. For complete documentation, see docs/backend/logging-guide.md.

Extensibility

Doc Engine supports custom injectors, mappers, and init functions to extend document generation with business-specific logic.

For complete documentation including creating injectors, mappers, init functions, and i18n, see docs/backend/extensibility-guide.md.

Integration Tests

Integration tests validate repository operations against a real PostgreSQL database using Testcontainers.

For complete documentation including setup, running tests, and troubleshooting, see docs/backend/integration-tests.md.

Role-Based Access Control

Workspace roles hierarchy (highest to lowest):

For a complete authorization matrix with all endpoints, roles (System, Tenant, Workspace), and required headers, see docs/backend/authorization-matrix.md.