reports

Report templating with Jinja2 and MJML for SignalRoom. Use when creating new reports, modifying templates, debugging report rendering, or adding new notification channels.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for building, managing, and debugging automated reports within the SignalRoom ecosystem. By leveraging Jinja2 for flexible text formatting and MJML for responsive email design, it allows developers to transform SQL query results into professional, multi-channel notifications for Slack, Email, and SMS.

Use Cases

  • Automated Multi-Channel Reporting: Define SQL queries and create synchronized templates to deliver consistent business insights across Slack, Email, and SMS simultaneously.
  • Responsive Email Development: Utilize MJML integration to generate high-quality, mobile-friendly email reports without the complexity of manual HTML coding.
  • Dynamic Data Visualization: Apply Jinja2 logic for advanced number formatting, conditional alerts, and data looping to create highly readable performance summaries.
  • Report Debugging and Maintenance: Streamline the process of troubleshooting SQL query errors or template rendering issues using built-in local testing commands.
namereports
descriptionReport templating with Jinja2 and MJML for SignalRoom. Use when creating new reports, modifying templates, debugging report rendering, or adding new notification channels.

Report Templating System

Architecture

reports/
├── registry.py      # Report definitions (name, templates, query)
├── renderer.py      # Jinja2 + MJML rendering
├── runner.py        # Execute reports (query → render → send)
├── templates/       # .j2 (Slack/SMS) and .mjml (Email)
└── queries/         # SQL files for report data

Creating a New Report

1. Add SQL Query

Create src/signalroom/reports/queries/{report_name}.sql:

-- Parameters available: :date, :start_date, :end_date
SELECT
    :date AS report_date,
    SUM(conversions) AS total_conversions,
    SUM(revenue) AS total_revenue
FROM everflow.daily_stats
WHERE date = :date

2. Create Templates

Slack (templates/{report_name}.slack.j2):

*{{ title }}* — {{ report_date }}

:chart_with_upwards_trend: *Performance Summary*
• Conversions: {{ "{:,}".format(total_conversions) }}
• Revenue: ${{ "{:,.2f}".format(total_revenue) }}

Email (templates/{report_name}.email.mjml):

<mjml>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-text>
          <h1>{{ title }}</h1>
          <p>Conversions: {{ total_conversions }}</p>
        </mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

SMS (templates/{report_name}.sms.j2):

{{ title }}: {{ total_conversions }} conv, ${{ total_revenue }} rev

3. Register Report

Add to src/signalroom/reports/registry.py:

REPORTS = {
    "my_report": Report(
        name="my_report",
        title="My Report Title",
        query_file="my_report.sql",
        templates={
            "slack": "my_report.slack.j2",
            "email": "my_report.email.mjml",
            "sms": "my_report.sms.j2",
        },
    ),
}

Running Reports

Local Testing (No Send)

python -c "
from signalroom.reports import run_report
print(run_report('daily_ccw', channel='slack'))
"

With Custom Parameters

python -c "
from signalroom.reports import run_report
print(run_report('daily_ccw', params={'date': '2025-12-18'}))
"

Send to Channel

python -c "
from signalroom.reports import run_report
run_report('daily_ccw', channel='slack', send=True)
"

Via Temporal

python scripts/trigger_workflow.py --report daily_ccw -w

Available Reports

Report Channels Description
daily_ccw slack, email, sms Daily CCW performance summary
test_sync slack Simple Everflow + Redtrack totals
alert slack, email, sms Error/warning/info alerts

Channel-Specific Formatting

Slack (mrkdwn)

*bold* _italic_ ~strikethrough~
:emoji_name:
• bullet point
```code```

Email (MJML)

MJML compiles to responsive HTML. Use components:

  • <mj-section> — row container
  • <mj-column> — column within section
  • <mj-text> — text content
  • <mj-button> — CTA button
  • <mj-image> — images

SMS

Keep under 160 characters. No formatting.

Jinja2 Patterns

Number Formatting

{{ "{:,}".format(value) }}           # 1,234,567
{{ "{:.2f}".format(value) }}         # 1234.56
{{ "${:,.2f}".format(value) }}       # $1,234.56
{{ "{:.1%}".format(value) }}         # 12.3%

Conditionals

{% if value > 0 %}
:arrow_up: Up {{ value }}%
{% else %}
:arrow_down: Down {{ value|abs }}%
{% endif %}

Loops

{% for row in affiliates %}
• {{ row.name }}: {{ row.conversions }} conv
{% endfor %}

Date Formatting

{{ report_date.strftime('%B %d, %Y') }}  # December 19, 2025
{{ report_date.strftime('%m/%d') }}       # 12/19

Alert Helper

For quick alerts without full reports:

from signalroom.reports import render_alert

message = render_alert(
    title="Pipeline Failed",
    message="Everflow sync failed with timeout",
    level="error"  # error, warning, info
)

Debugging

Template Not Found

Check path in registry matches actual file in templates/

SQL Error

Run query directly:

python -c "
from signalroom.reports.runner import execute_query
print(execute_query('daily_ccw', {'date': '2025-12-18'}))
"

MJML Compile Error

Test MJML syntax: https://mjml.io/try-it-live

Resources