Skip to main content

110. Multi-Format System Reports

Status: Accepted Date: 2025-07-06

Context​

The system performance reports generated by the Atlas module need to be delivered to different destinations for different audiences. We need to send rich, detailed reports to developers and analysts, likely stored as artifacts in GitHub. We also need to send concise, readable summaries as notifications to a Telegram channel for operators. These two destinations have very different formatting requirements.

Decision​

The Atlas module will be responsible for generating system reports in two distinct formats from the same underlying data:

  1. GitHub-Flavored Markdown (.md): A detailed, well-structured Markdown format suitable for publishing as a GitHub release artifact or in a repository. This format will contain detailed tables, code blocks for data summaries, and links to relevant entities.
  2. Telegram HTML: A simplified HTML format, which is a subset of HTML supported by Telegram for message styling. This format will use bold tags, line breaks, and monospace fonts to create a summary that is clean, readable, and scannable on a mobile device.

The AtlasService will first gather and aggregate all the required data. It will then pass this data to two separate "renderer" or "template" functions, one for each format, to produce the final report strings.

Consequences​

Positive:

  • Tailored User Experience: Each audience receives the report in the format that is best suited to their context and needs. Developers get a detailed, linkable artifact; operators get a quick, readable notification.
  • Separation of Concerns: The logic for gathering the data is separated from the logic for presenting it. We can easily add a new output format in the future (e.g., PDF or email) by simply adding a new renderer, without changing the data aggregation logic.
  • Reusability: The core data aggregation logic is written once and reused for all report formats.

Negative:

  • Increased Maintenance: We now have two separate report templates to maintain instead of one. A change to the report content needs to be implemented in both the Markdown and HTML templates.

Mitigation:

  • Shared Data Structure: Both renderers will take the exact same, strongly-typed SystemReportData object as input. This ensures that the data being presented is consistent across both formats.
  • Template Abstraction: The rendering logic will be encapsulated in separate, well-named template files or functions (e.g., renderGithubReport.ts, renderTelegramReport.ts), making them easy to find and update in parallel.