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

# Guides templates

> Adopt the official Lerian templates for narrative docs — product overviews, architecture, getting started, entity references, and how-to guides.

This page provides the official templates for all narrative and task-oriented documentation in the Lerian ecosystem: product overviews, architecture pages, getting started guides, entity references, how-to guides, and plugin overviews.

These templates reflect the structure and patterns established in the Midaz documentation. Use them as a starting point for any new page. Apply [voice and tone](/en/partners-hub/voice-tone) and [capitalization](/en/partners-hub/capitalization) rules regardless of which template you use.

For API endpoint documentation, see [API Reference templates](/en/partners-hub/api-reference-template).

## Product overview page

***

The entry point for a product or plugin. Answers three questions: what is it, why use it, and how does it work.

<Steps>
  <Step title="Title and subtitle">
    Use "What is \[Product]?" as the title. Add a one-line subtitle in the frontmatter `description` field that summarizes the product in plain language.

    ```yaml theme={null}
    ---
    title: "What is [Product]?"
    description: "[Product] does [X] for [audience]."
    ---
    ```
  </Step>

  <Step title="Opening paragraph">
    Two to three sentences. State what the product is, what it does, and where it fits in the Lerian ecosystem. Mention the licensing model (source-available, proprietary) and link to the GitHub repo if applicable.

    <Tip>
      Reference: [What is Midaz?](/en/midaz/what-is-midaz) opens with a single paragraph that covers product definition, licensing, and source availability.
    </Tip>
  </Step>

  <Step title="Why use [Product]">
    Frame the problem the product solves. Use a bullet list for the key value propositions. Each bullet starts with a bold label followed by a colon and a one-line explanation.

    ```markdown theme={null}
    * **Own your ledger**: Source-available means full transparency and no vendor lock-in
    * **Move fast**: Modular architecture lets you add products without re-architecting
    ```
  </Step>

  <Step title="What [Product] does">
    List core capabilities as bullets. Follow with a "Built for" subsection if the product serves distinct audiences (fintechs, banks, enterprises).
  </Step>

  <Step title="Common use cases">
    Use an `<AccordionGroup>` with 3–5 use cases. Each accordion has a short title and a 2–3 sentence description of the scenario.

    ```jsx theme={null}
    <AccordionGroup>
      <Accordion title="Digital banking">
        Launch checking accounts, savings products, and instant transfers.
      </Accordion>
    </AccordionGroup>
    ```
  </Step>

  <Step title="How [Product] works">
    Use a `<Steps>` component to walk through the high-level workflow (4–6 steps). Each step has a verb-based title and a 1–2 sentence explanation.
  </Step>

  <Step title="Integrations (optional)">
    A table mapping related Lerian products to what they add.

    | Product                                | Integration                                                 |
    | -------------------------------------- | ----------------------------------------------------------- |
    | [Matcher](/en/matcher/what-is-matcher) | Reconcile ledger transactions against external data sources |
  </Step>

  <Step title="Next steps">
    A `<CardGroup cols={2}>` with 3–4 cards pointing to: architecture/concepts, quick start, use cases, and API reference.
  </Step>
</Steps>

**Reference pages:** [What is Midaz?](/en/midaz/what-is-midaz) · [What is CRM?](/en/midaz/crm/crm-overview) · [Pix in Lerian](/en/midaz/plugins/pix/pix-overview)

## Architecture and concepts page

***

Explains the internal structure of a product — its domains, entities, and how they relate. This is the "About \[Product]" page.

<Steps>
  <Step title="Opening paragraph">
    One paragraph that positions the product architecturally. Mention the domain-driven design if applicable.
  </Step>

  <Step title="Domains or components">
    Break the product into its logical domains (e.g., Onboarding Domain, Transaction Domain). Each domain gets an H3 heading with:

    * A short description of its purpose
    * A bullet list of its components, each with a bold name and a one-line definition

    Use glossary tooltips for domain-specific terms on first mention:

    ```jsx theme={null}
    <GLedger>Ledger</GLedger>
    ```
  </Step>

  <Step title="Summary table">
    End with an "In short" section containing a table that maps domains to their purpose and key APIs.

    | Domain         | Purpose                     | Key APIs                       |
    | :------------- | :-------------------------- | :----------------------------- |
    | **Onboarding** | Structure and configuration | Organizations, Ledgers, Assets |
  </Step>
</Steps>

**Reference page:** [About Midaz](/en/midaz/about-midaz)

## Getting started page

***

A hands-on tutorial that takes the reader from zero to a working setup. Target: under 15 minutes.

<Steps>
  <Step title="Title and subtitle">
    Use "Getting started with \[Product]" as the title. The subtitle should set expectations: what the reader will accomplish and how long it takes.
  </Step>

  <Step title="Prerequisites">
    A table listing required tools with minimum versions and check commands.

    | Tool | Minimum version | Check command |
    | ---- | --------------- | ------------- |
    | Go   | 1.24+           | `go version`  |

    Add a `<Note>` for OS compatibility.
  </Step>

  <Step title="Numbered steps">
    Each step is an H2 with the format "Step N — \[Verb] \[object]" (e.g., "Step 1 — Clone the repository"). Inside each step:

    * A 1–2 sentence explanation of what the step does and why
    * A code block with the exact command
    * A `<Tip>` or `<Note>` for important details (ports, default values, gotchas)

    Link to the full API reference for each endpoint used:

    ```markdown theme={null}
    <Tip>
      For the complete endpoint specification, see [Create an Organization](/en/reference/midaz/create-an-organization).
    </Tip>
    ```
  </Step>

  <Step title="Verification step">
    Always include a final step that confirms the setup works (e.g., check a balance, query a status endpoint).
  </Step>

  <Step title="Next steps">
    A `<CardGroup cols={2}>` pointing to entities, transactions, use cases, and API explorer.
  </Step>
</Steps>

**Reference page:** [Getting started with Midaz](/en/midaz/midaz-getting-started)

## Entity reference page

***

Documents a single core entity (Account, Ledger, Transaction, Holder, etc.). Explains what it is, how it behaves, and how to use it.

<Steps>
  <Step title="Opening definition">
    One paragraph defining the entity, its role in the system, and its relationship to other entities.
  </Step>

  <Step title="Core concepts">
    Explain key behaviors and rules. Use H3 subsections for distinct concepts. Include diagrams (`<Frame>`) when relationships are complex.
  </Step>

  <Step title="Code examples">
    Use `<CodeGroup>` to show JSON and DSL examples side by side when both are supported. Use realistic payloads.

    ````markdown theme={null}
    <CodeGroup>
       ```json JSON Example
       	{ "name": "Revenue Account", "assetCode": "BRL", "type": "deposit" }
       ```
       ```go DSL Example
       	(from @revenue :amount BRL 1000)
       ```
    </CodeGroup>
    ````
  </Step>

  <Step title="Visual diagrams">
    Use `<Frame caption="Figure N. Description">` for architecture, flow, or entity relationship diagrams.
  </Step>

  <Step title="Related pages">
    Link to the API reference, related entities, and relevant guides.
  </Step>
</Steps>

**Reference pages:** [Transactions](/en/midaz/transactions) · [Accounts](/en/midaz/accounts) · [Holders](/en/midaz/crm/holders)

## Guide page

***

Explains how to accomplish a specific task or implement a use case. Task-oriented and contextual — explains the "why" alongside the "how."

<Steps>
  <Step title="Opening context">
    One to two paragraphs explaining what the reader will accomplish, who this guide is for, and what problem it solves. Be specific — not "learn about X" but "configure X to handle Y."
  </Step>

  <Step title="Prerequisites">
    What must already be set up or understood. Link to relevant pages.
  </Step>

  <Step title="Step-by-step instructions">
    Use H2 sections for major phases. Within each phase, use numbered steps or `<Steps>` components. Start each step with a verb.

    Include:

    * Code blocks with realistic payloads
    * `<Tip>` for best practices
    * `<Warning>` for common pitfalls
    * `<Note>` for important context
  </Step>

  <Step title="Verification">
    How the reader confirms the task was completed successfully.
  </Step>

  <Step title="Next steps">
    Cards or links to related guides, deeper concepts, or API references.
  </Step>
</Steps>

<Warning>
  Keep the main guide focused. If a section grows beyond the scope of the task (architecture deep dives, algorithm details, security design), move it to a separate child page and link to it.
</Warning>

**Reference pages:** [Getting started with CRM](/en/midaz/crm/crm-getting-started) · [Setting up the Pix integration](/en/midaz/plugins/pix/indirect-pix-integration)

## Plugin overview page

***

Plugin overviews follow the same structure as [product overview pages](#product-overview-page), with these additions:

* State clearly whether the plugin is **source-available** or **proprietary**, and whether it requires a license.
* Specify the **versioning relationship** with Midaz (e.g., "CRM version always matches the Midaz Core version").
* Include a **deployment model** section: how the plugin is deployed relative to Midaz (independently, same namespace, etc.).
* Add a **requirements** section listing what the institution needs to operate the plugin (ISPB, connectivity provider, DevOps maturity, etc.).
* If applicable, include a **trade-offs and challenges** section that honestly describes the operational responsibilities the plugin introduces.

**Reference pages:** [What is CRM?](/en/midaz/crm/crm-overview) · [Pix in Lerian](/en/midaz/plugins/pix/pix-overview) · [What is Fees Engine?](/en/midaz/plugins/fees-engine/fees-engine-overview)

## Component patterns

***

These Mintlify components appear across all guide templates. Use them consistently.

| Component          | When to use                                                                 |
| ------------------ | --------------------------------------------------------------------------- |
| `<Tip>`            | Best practices, recommendations, cross-references to API specs              |
| `<Note>`           | Important context that isn't a warning (OS compatibility, default values)   |
| `<Warning>`        | Common pitfalls, things that will cause errors if ignored                   |
| `<Danger>`         | Security-critical information, data loss risks, compliance responsibilities |
| `<Steps>`          | Sequential workflows (getting started, how it works)                        |
| `<AccordionGroup>` | Use cases, optional configurations, expandable details                      |
| `<CodeGroup>`      | Multiple code formats for the same operation (JSON + DSL, bash + YAML)      |
| `<CardGroup>`      | Next steps, related pages                                                   |
| `<Frame>`          | Diagrams and illustrations with captions                                    |
| Glossary tooltips  | First occurrence of domain-specific terms in a page                         |