Template Studio

Mobile-first email template and report builder for Arrowstack applications.

Current MVP

• PWA designed from 320px upward
• tap-to-add and tap-to-edit block workflow
• local IndexedDB draft persistence plus debounced server autosave
• report and email template profiles
• sample JSON data and variable bindings
• MJML email rendering
• HTML and A4 PDF report rendering
• immutable publish versions
• stable template keys for consuming apps
• server-side Keycloak OIDC authorization-code + PKCE flow
• authenticated published-template API
• revocable hashed API keys
• PostgreSQL persistence

Consumer API

Drafts are editor-only. Consuming apps can only retrieve or render published versions.

List published templates:

GET /api/v1/templates
X-API-Key: ts_live_...

Pull one published template:

GET /api/v1/templates/{template-key}
X-API-Key: ts_live_...

Render it with runtime data:

POST /api/v1/templates/{template-key}/render
X-API-Key: ts_live_...
Content-Type: application/json

{
  "format": "pdf",
  "data": {
    "customer": {
      "name": "Example Customer"
    }
  }
}

Email templates accept format: "email" and return rendered HTML. Reports accept html or pdf.

Authentication

Anonymous access is rejected.

Two machine authentication modes are supported:

1. X-API-Key using a key generated from the Template Studio Use screen. Keys are displayed once and stored only as SHA-256 hashes.
2. Authorization: Bearer <token> using the Keycloak machine client template-studio-api.

For another Arrowstack/Coolify application, prefer OAuth. The Arrowstack MCP secret broker can inject the existing template-studio-api client credentials directly into the consuming application without returning the client secret.

Local development

Copy .env.example to .env, provide a PostgreSQL database, and leave AUTH_REQUIRED=false for local-only development.

npm install
npm run dev

The production deployment uses Arrowstack MCP to inject DATABASE_URL, KEYCLOAK_ISSUER, KEYCLOAK_CLIENT_ID, and KEYCLOAK_CLIENT_SECRET. Never commit real credentials.

Production

Canonical public repository:

https://git.arrowstack.dev/Admin/template-studio

Production URL:

https://templates.arrowstack.dev

MCP authoring endpoint

Template Studio exposes a Keycloak-protected Streamable HTTP MCP endpoint at:

https://templates.arrowstack.dev/mcp

This endpoint is separate from the published-template consumer API and from the browser editor session. It accepts only:

Authorization: Bearer <Keycloak access token>

The token must be issued by the configured Keycloak realm and its azp client ID must appear in TEMPLATE_MCP_ALLOWED_CLIENTS. API keys and browser cookies are intentionally not accepted for MCP authoring.

The endpoint exposes these tools:

• templates_list
• template_get
• template_create
• template_update_draft
• template_publish
• folders_list
• folder_create
• template_move

template_update_draft accepts expected_updated_at; callers should pass the value returned by template_get to detect concurrent edits instead of silently overwriting them.

The MCP surface does not expose API-key management, authentication administration, template deletion, or arbitrary database access.