> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# What is Reporter?

> Automate regulatory and business reporting from your financial data with Reporter — produce CSV, XML, HTML, TXT, or PDF outputs from `.tpl` templates.

**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](https://github.com/LerianStudio/reporter).

| Template format        | Output format    |
| ---------------------- | ---------------- |
| CSV-structured `.tpl`  | CSV file         |
| XML-structured `.tpl`  | XML file         |
| HTML-structured `.tpl` | HTML or PDF file |
| TXT-structured `.tpl`  | TXT 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

<Frame>
  <img src="https://mintcdn.com/lerian-49cb71fc/sdyhZmZWJuB1Arvv/images/en/docs/reporter-workflow.jpg?fit=max&auto=format&n=sdyhZmZWJuB1Arvv&q=85&s=4c7b8ef64035ee47c14535d152e9ceef" alt="Reporter workflow showing the process from template to rendered report" width="1291" height="1209" data-path="images/en/docs/reporter-workflow.jpg" />
</Frame>

### 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.

<Frame>
  <img src="https://mintcdn.com/lerian-49cb71fc/sdyhZmZWJuB1Arvv/images/en/docs/reporter-layers.jpg?fit=max&auto=format&n=sdyhZmZWJuB1Arvv&q=85&s=0cc47433d0fd206dd081c462e1688a07" alt="Reporter architecture layers showing the component structure" width="1333" height="1172" data-path="images/en/docs/reporter-layers.jpg" />
</Frame>

## 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.

<Danger>
  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.**
</Danger>

## 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](/en/reference/reporter/connections/create-connection).

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

### Recommended naming

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.

<Note>
  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.
</Note>

For detailed configuration options including environment variables and multi-schema setup, see [Using Reporter -- Configuring external data sources](/en/reporter/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 }}
```

<Info>
  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 }}
  ```
</Info>

## 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](/en/reporter/template-reference).

For advanced report filtering with operators like `eq`, `gt`, `between`, `in`, and more, see the [Advanced filtering](/en/reporter/template-reference#advanced-filtering) section.

## Need inspiration?

***

Check out the [Template examples](/en/reporter/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](/en/platform/access-manager/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.

<Tip>
  Access Manager is an optional feature available under the **Enterprise model**. For details on enabling it, see the [Access Manager documentation](/en/platform/access-manager/access-manager).
</Tip>

## Next steps

***

<CardGroup cols={2}>
  <Card title="Explore the Reporter API" icon="terminal" href="en/reference/reporter/reporter-developer-quick-start">
    Browse endpoints for templates, reports, and data sources.
  </Card>

  <Card title="Using Reporter" icon="rocket" href="/en/reporter/using-reporter">
    Learn how to create and submit your first report template.
  </Card>
</CardGroup>