Skip to content

r-mccarty/docgen2

BranchesTags

Repository files navigation

DocGen2

A declarative, component-based document generation system that renders Microsoft Word documents from JSON plans. DocGen2 implements a "React for Docs" paradigm with business logic validation, treating document creation as a rendering process with structured error reporting.

Quick Start

HTTP Server (Recommended)

# Run HTTP server
go run ./cmd/server -server

# Or build and run
go build -o docgen-server ./cmd/server
./docgen-server -server

The server will start on port 8080 (configurable via PORT environment variable).

CLI Mode

# Build CLI
go build -o docgen-cli ./cmd/server

# Run CLI
./docgen-cli -shell assets/shell/template_shell.docx \
             -components assets/components/ \
             -schema assets/schemas/rules.cue \
             -plan assets/plans/test_plan_01.json \
             -output output/generated_document.docx

Docker (Production)

# Build image
docker build -t docgen-service:latest .

# Run container
docker run -p 8080:8080 docgen-service:latest

HTTP API

Endpoints

POST /validate-plan

Validate a document plan against business rules without generating a document.

Request:

curl -X POST http://localhost:8080/validate-plan \
  -H "Content-Type: application/json" \
  -d '{
    "body": [
      {
        "component": "DocumentTitle",
        "props": {
          "document_title": "Test Document"
        }
      }
    ]
  }'

Response (Valid):

{
  "status": "valid",
  "valid": true
}

Response (Invalid):

{
  "status": "invalid",
  "valid": false,
  "errors": [
    {
      "path": "body[0].props.document_title",
      "message": "value must not be empty"
    }
  ]
}

POST /generate

Generate a Word document from a JSON document plan. Plans are validated before generation.

Request:

curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{
    "doc_props": {
      "filename": "my_document.docx"
    },
    "body": [
      {
        "component": "DocumentTitle",
        "props": {
          "document_title": "My Test Document"
        }
      },
      {
        "component": "DocumentCategoryTitle",
        "props": {
          "category_title": "TEST DOCUMENT"
        }
      }
    ]
  }' \
  --output generated_document.docx

Response:

  • Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • Content-Disposition: attachment; filename="my_document.docx"
  • Body: Binary DOCX file data

GET /health

Health check endpoint.

curl http://localhost:8080/health

Response:

{
  "status": "healthy",
  "service": "docgen-service",
  "components_loaded": 5,
  "available_components": ["DocumentCategoryTitle", "DocumentTitle", ...]
}

GET /components

List available components.

curl http://localhost:8080/components

Response:

{
  "components": ["DocumentCategoryTitle", "DocumentTitle", ...],
  "count": 5,
  "note": "Detailed component specifications available in /docs/components/"
}

Environment Variables

  • PORT - Server port (default: 8080)
  • DOCGEN_SHELL_PATH - Path to shell document (default: ./assets/shell/template_shell.docx)
  • DOCGEN_COMPONENTS_DIR - Components directory (default: ./assets/components/)
  • DOCGEN_SCHEMA_PATH - Path to CUE validation schema (default: ./assets/schemas/rules.cue)

Development

Running Tests

# Run unit tests
go test ./internal/docgen/...

# Run validation tests
go test ./internal/validator/...

# Run HTTP API tests
go test ./internal/api/...

# Run all tests with verbose output
go test -v ./...

End-to-End Testing

The project includes comprehensive E2E testing through the CLI interface. To run the full test suite:

1. Setup

# Ensure output directory exists
mkdir -p ./output

2. Individual Component Smoke Tests

Run each component in isolation to verify basic functionality:

# DocumentCategoryTitle smoke test
go run ./cmd/server \
    -shell ./assets/shell/template_shell.docx \
    -components ./assets/components/ \
    -schema ./assets/schemas/rules.cue \
    -plan ./assets/plans/smoke_test_DocumentCategoryTitle.json \
    -output ./output/cli_smoke_test_DocumentCategoryTitle.docx

# DocumentTitle smoke test
go run ./cmd/server \
    -shell ./assets/shell/template_shell.docx \
    -components ./assets/components/ \
    -schema ./assets/schemas/rules.cue \
    -plan ./assets/plans/smoke_test_DocumentTitle.json \
    -output ./output/cli_smoke_test_DocumentTitle.docx

# DocumentSubject smoke test
go run ./cmd/server \
    -shell ./assets/shell/template_shell.docx \
    -components ./assets/components/ \
    -schema ./assets/schemas/rules.cue \
    -plan ./assets/plans/smoke_test_DocumentSubject.json \
    -output ./output/cli_smoke_test_DocumentSubject.docx

# TestBlock smoke test
go run ./cmd/server \
    -shell ./assets/shell/template_shell.docx \
    -components ./assets/components/ \
    -schema ./assets/schemas/rules.cue \
    -plan ./assets/plans/smoke_test_TestBlock.json \
    -output ./output/cli_smoke_test_TestBlock.docx

# AuthorBlock smoke test
go run ./cmd/server \
    -shell ./assets/shell/template_shell.docx \
    -components ./assets/components/ \
    -schema ./assets/schemas/rules.cue \
    -plan ./assets/plans/smoke_test_AuthorBlock.json \
    -output ./output/cli_smoke_test_AuthorBlock.docx

3. Full Integration Test

Test all components working together in a complete document:

go run ./cmd/server \
    -shell ./assets/shell/template_shell.docx \
    -components ./assets/components/ \
    -schema ./assets/schemas/rules.cue \
    -plan ./assets/plans/full_integration_test.json \
    -output ./output/cli_full_integration_test.docx

4. Verification

After running the tests:

  1. Check that all commands complete without error
  2. Verify that 6 .docx files are generated in ./output/
  3. Open each document to visually verify correct rendering
  4. Compare outputs between unit tests (/test_output/) and CLI tests (/output/)

Component Library

The system includes 5 production-ready components:

  • DocumentCategoryTitle: Category header with decorative underline
  • DocumentTitle: Main document title with metadata integration
  • DocumentSubject: Document subject/revision line
  • TestBlock: Test form with 5 input fields
  • AuthorBlock: Author contact information block

See /docs/components/ for detailed component documentation and usage examples.

Development Status

Current Status: All Milestones Complete

  • ✅ Milestone 1: CLI Renderer - Functional Go CLI for document generation
  • ✅ Milestone 2: HTTP API - Production-ready HTTP microservice with REST endpoints and Docker containerization
  • ✅ Milestone 3: CUE Validation - Business logic validation layer with structured error reporting

Architecture

DocGen2 follows a strict separation of concerns:

  • Document Plans (JSON): Declarative specifications describing document structure
  • Component Library: Reusable, parameterizable OpenXML snippets
  • Shell Document: Minimal .docx containing document-wide styles
  • Validation Layer: CUE schemas for business rule enforcement with structured error reporting

For complete architecture details, see docs/docgen-vision.md and docs/docgen-mvp-spec.md.

About

A Word document rendering engine

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages