d2

D2 Diagram Rendering Service

A microservice for rendering D2 (Declarative Diagramming) diagrams to SVG or PNG format.

Features

• Multiple output formats: SVG (default) and PNG
• Theme support: 9 built-in D2 themes
• Layout engines: dagre (default) and elk
• Sketch mode: Hand-drawn style diagrams
• Configurable padding: Adjust spacing around diagrams
• Health checks: Built-in monitoring endpoint

API Endpoints

POST /render

Render a D2 diagram.

Request Body:

{
  "source": "x -> y: my label",
  "format": "svg",
  "theme": 0,
  "layout": "dagre",
  "sketch": false,
  "pad": 100
}

Response: SVG or PNG image

GET /health

Health check endpoint.

Response:

{
  "status": "healthy",
  "service": "d2-renderer",
  "d2_version": "v0.x.x"
}

GET /

Service information and available options.

Themes

• 0: Neutral default
• 1: Neutral grey
• 2: Flagship Terrastruct
• 3: Cool classics
• 4: Mixed berry blue
• 5: Grape soda
• 6: Aubergine
• 7: Colorblind clear
• 8: Vanilla nitro cola

Development

Local Development

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

# Run the service
python -m d2service.main

# Or with uvicorn
uvicorn d2service.main:app --reload --port 8020

Running Tests

# Install test dependencies
uv pip install -r requirements.txt pytest pytest-cov httpx

# Run unit tests
uv run pytest tests/test_main.py -v

# Run all tests with coverage
uv run pytest --cov=d2service --cov-report=html

# Run integration tests (requires service to be running)
uv run python tests/integration_test.py

Container Deployment

D2 is deployed as part of the complete AI4MDE system using Podman Compose. See the main README for deployment options.

# From the project root directory
cd /path/to/chatbot

# Start D2 service
podman compose up -d d2

The service runs internally on port 8020 and is exposed on port 8030. It will be available at http://localhost:8030

Testing Examples

# Test with curl (when running via compose - port 8030)
curl -X POST http://localhost:8030/render \
  -H "Content-Type: application/json" \
  -d '{
    "source": "x -> y: Hello D2",
    "format": "svg"
  }' > output.svg

# For standalone local development (port 8020)
curl -X POST http://localhost:8020/render \
  -H "Content-Type: application/json" \
  -d '{
    "source": "x -> y: Hello D2",
    "format": "svg"
  }' > output.svg

Integration

The service is designed to integrate with the AI4MDE chatbot platform, similar to the PlantUML service.

Dependencies

• Python 3.13+
• FastAPI
• Uvicorn
• D2 CLI (installed via curl script)

License

See LICENSE file in the project root for details.