Skip to main content
Reporter is Lerian’s source-available reporting engine that automates the generation of regulatory and business reports from your financial data. Whether you need BACEN-compliant reports, internal analytics, or audit-ready documentation, Reporter produces them consistently and on demand. Under the hood, Reporter uses simple plain-text templates (.tpl files) that render into multiple output formats — CSV, XML, HTML, TXT, or PDF. The source code is publicly available on GitHub.
Template formatOutput format
CSV-structured .tplCSV file
XML-structured .tplXML file
HTML-structured .tplHTML or PDF file
TXT-structured .tplTXT file

​
Why use Reporter?

Financial institutions spend significant time producing recurring reports — for regulators, auditors, and internal stakeholders. Reporter eliminates this manual work by letting you define a report template once and generate updated reports automatically from live data. For technical teams: rather than writing complex SQL queries, you reference domains, tables, and fields through intuitive placeholders. This makes report creation faster, more flexible, and easier to maintain.

​
How it works

​
Workflow

Reporter follows a simple and efficient workflow that turns your templates into production-ready reports:
  1. Submit templates with optional filters and parameters
  2. Reporter retrieves data from configured databases (PostgreSQL, MongoDB)
  3. Template logic is applied (loops, conditions, calculations)
  4. The final output is generated in the requested format
Reporter workflow showing the process from template to rendered report

​
Architecture

Reporter is built on a layered architecture that keeps responsibilities clear and supports growth:
  • Data layer: Connects to databases through configured data sources. Supports PostgreSQL and MongoDB, with multi-schema queries for PostgreSQL.
  • Business logic layer: Manages template parsing, placeholder resolution, and rendering.
  • Storage layer: Stores templates and generated reports using S3-compatible object storage (AWS S3, MinIO, or SeaweedFS).
  • Presentation layer: Returns formatted output through RESTful APIs.
Reporter architecture layers showing the component structure

​
What it can do

  • Dynamic queries with placeholders: Reference any data point via direct paths — no SQL required.
  • Multi-schema support: Query tables across multiple PostgreSQL schemas from a single template using explicit schema syntax.
  • Loop and condition logic: Build dynamic content with for loops, if/elif/else conditionals, and scoped blocks.
  • Math operations and aggregation: Perform calculations with sum_by, avg_by, count_by, min_by, max_by, calc, and aggregate_balance.
  • Counter tracking: Track and display named counters across template iterations with counter and counter_show.
  • Data transformation filters: Transform values inline with where, sum, count, replace, slice, strip_zeros, and percent_of.
  • Async processing: Heavy reports are handled asynchronously via message queue.
  • S3-compatible storage: Templates and reports are stored in any S3-compatible service (AWS S3, MinIO, SeaweedFS).
  • Multiple output formats: Generate CSV, XML, HTML, TXT, or PDF output from a single template engine.

​
Template model

Reporter uses templates that mirror the final document structure. Files must have the .tpl extension regardless of the content format inside.
Even though the file content must follow the output format, make sure to save it with a .tpl extension. This is required for the template to work properly.

​
Setting up your data sources

Before generating reports, you need to configure the database connections that Reporter uses to retrieve data. Reporter connects to your databases through managed data sources, configured via the database connections API. Each data source represents a database connection identified by a unique name (configName), which is then used when defining placeholders and filters in your templates. Through the connections API, you can:
  • Register one or more databases (PostgreSQL or MongoDB)
  • Test connectivity before running reports
  • Validate template fields against your actual database schema
To avoid conflicts — especially when different databases contain tables with the same names — use clear and descriptive identifiers for your data sources. For example:
  • midaz_onboarding (PostgreSQL)
  • midaz_onboarding_metadata (MongoDB)

​
Schema validation

When you create or update a template, Reporter validates that the fields referenced in your placeholders exist in the configured data sources. If a data source is temporarily unavailable during validation, Reporter returns warnings (not errors), allowing you to proceed with template creation.
Valid fields are confirmed against the actual database schema. Unavailable data sources generate a warning with the code DATA_SOURCE_DOWN, not a blocking error. You can fix connectivity issues later without losing your template work.
For detailed configuration options including environment variables and multi-schema setup, see Using Reporter — Configuring external data sources.

​
Using placeholders

The placeholder structure follows a path-based syntax: 
{{ base.table_or_collection.field_or_document }}
This works for both SQL databases (tables and fields) and MongoDB (collections and documents).

​
Multi-schema placeholders

When your PostgreSQL data source has multiple schemas, use the explicit schema syntax to avoid ambiguity: 
{{ base:schema.table.field }}
For example: 
{{ external_db:sales.orders.total }}
{{ external_db:inventory.items.quantity }}
If a table name exists in only one schema, the legacy syntax {{ base.table.field }} still works — Reporter auto-discovers the correct schema. If a table exists in multiple schemas, Reporter defaults to the public schema. If the table is not in public, Reporter returns an error with suggestions:
ambiguous table reference: 'db.orders' exists in multiple schemas: [sales, shipping]
Please use explicit schema syntax:
  {{ db:sales.orders }}
  {{ db:shipping.orders }}

​
Templates and placeholders reference

Reporter includes a rich set of template tags for aggregation (sum_by, avg_by, count_by, min_by, max_by), arithmetic (calc), financial grouping (aggregate_balance), counters, and date/time formatting. It also provides filters for string manipulation, percentage calculation, and array operations. For the complete reference, see Template reference. For advanced report filtering with operators like eq, gt, between, in, and more, see the Advanced filtering section.

​
Need inspiration?

Check out the Template examples page to explore what you can do and start shaping your own template.

​
Authentication and authorization

Reporter does not require authentication by default, but it ships with native Access Manager integration. When enabled, Access Manager provides role-based access control (RBAC) for templates, reports, and data sources — giving you fine-grained control over who can view, create, or manage reporting resources.
Access Manager is an optional feature available under the Enterprise model. For details on enabling it, see the Access Manager documentation.

​
Next steps

Explore the Reporter API

Browse endpoints for templates, reports, and data sources.

Using Reporter

Learn how to create and submit your first report template.