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

# Performance Reports Overview

> Architecture and schema overview for the Mission Control reporting engine

## Overview

The Performance Report system is **fully configuration-driven** -- no backend code changes are required to create new reports. The reporting engine dynamically reads metrics, filters by source, applies templates, and builds SQL queries automatically.

## Architecture

The database is designed with 6 layers:

```mermaid theme={null}
graph LR
    A[Categories] --> B[Sources]
    B --> C[Data Dictionary]
    C --> D[Reports]
    D --> E[Report Templates]
    E --> F[User Data]
```

| Layer               | Description                     | Example                                   |
| ------------------- | ------------------------------- | ----------------------------------------- |
| **Categories**      | Logical groupings               | Media, Commerce, Analytics/Attribution    |
| **Sources**         | Platforms within categories     | Google Ads, Facebook Ads, Shopify, GA4    |
| **Data Dictionary** | Metrics and dimensions          | Clicks, Revenue, ROAS, CTR                |
| **Reports**         | System + custom reports         | LinkedIn Ads Report, Cross-Channel Report |
| **Templates**       | Column configuration per report | Which metrics appear, ordering, labels    |
| **User Data**       | Planning/target data            | User-entered budgets and goals            |

## Key Tables

<CardGroup cols={2}>
  <Card title="Data Dictionary" icon="book" href="/mission-control/performance-reports-data-dictionary">
    Central repository for all metrics, dimensions, and formulas. The source of truth.
  </Card>

  <Card title="Creating Reports" icon="plus" href="/mission-control/performance-reports-creating-reports">
    Step-by-step guide to creating system-defined reports via configuration.
  </Card>

  <Card title="Example: LinkedIn Ads" icon="linkedin" href="/mission-control/performance-reports-example">
    End-to-end walkthrough of building a LinkedIn Ads system report.
  </Card>

  <Card title="Feature Flags" icon="flag" href="/mission-control/feature-flags">
    Control which features and modules are available per client.
  </Card>
</CardGroup>

## Table Relationships

| Table                    | Purpose                                                    |
| ------------------------ | ---------------------------------------------------------- |
| `category_master`        | Logical groupings (Paid Media, Commerce, etc.)             |
| `source_master`          | Platforms (Google Ads, Shopify, etc.) linked to categories |
| `report_data_dictionary` | All metrics, dimensions, formulas -- the source of truth   |
| `report_custom_fields`   | Maps metrics/dimensions to sources and categories          |
| `report_master`          | Report definitions (name, type, metadata)                  |
| `report_source_master`   | Maps reports to their data sources                         |
| `report_template_master` | Column config per report (order, labels, sticky columns)   |

## System Report Rules

System-defined reports follow specific constraints:

* Always aggregated (no granular drill-down)
* Always daily granularity
* Only top-level metrics included in templates

| Source Type     | Level Used       |
| --------------- | ---------------- |
| Paid Media      | Account          |
| Shopify         | null             |
| Analytics       | Analytics Report |
| Mission Control | null             |