### Makefile: Setup Commands

Source: https://github.com/lerianstudio/midaz/blob/develop/llms-full.txt

Commands for setting up the development environment, including copying environment files and installing tools and git hooks.

```bash
# Setup
make set-env                  # Copy .env.example → .env for all components
make dev-setup                # Install tools + git hooks + env files
make setup-git-hooks          # Configure git hooks
```

--------------------------------

### Setup and Run Midaz Project

Source: https://github.com/lerianstudio/midaz/blob/develop/AGENTS.md

These commands are used to set up the environment, start the project services, run unit tests, and perform code linting.

```bash
make set-env     # Create .env files
make up          # Start everything (infra → ledger → CRM)
make test-unit   # Run unit tests
make lint        # Lint all code
```

--------------------------------

### Install bash-completion on Ubuntu

Source: https://github.com/lerianstudio/midaz/wiki/Mdz-(CLI)

Use apt to install bash-completion for Bash shell autocompletion.

```shell
sudo apt install bash-completion
```

--------------------------------

### Linter Output Example

Source: https://github.com/lerianstudio/midaz/blob/develop/scripts/migration_linter/docs/MIGRATION_GUIDELINES.md

Example of the migration linter's output format, showing detected issues and suggestions for specific files.

```text
Analyzing 3 migrations in ./components/ledger/migrations/onboarding

---> 000006_create_account_type_table.up.sql
  1. [WARNING] Line 19: CREATE INDEX without CONCURRENTLY blocks table. Use CREATE INDEX CONCURRENTLY.
  2. [WARNING] Line 25: CREATE INDEX without CONCURRENTLY blocks table. Use CREATE INDEX CONCURRENTLY.

  Suggestions:
    [#1, #2]
      Use CONCURRENTLY option:
          CREATE INDEX CONCURRENTLY idx_name ON table (column);
          CREATE UNIQUE INDEX CONCURRENTLY idx_name ON table (column);
          Note: Cannot be used inside a transaction block

---> 000010_add_user_column.up.sql
  1. [ERROR] Line 5: Adding NOT NULL column without DEFAULT requires table rewrite. Add DEFAULT value.

  Suggestions:
    [#1]
      Add DEFAULT value to avoid table rewrite:
          ALTER TABLE table_name ADD COLUMN column_name TYPE NOT NULL DEFAULT value;

          Or use multi-step approach:
          1. ADD COLUMN column_name TYPE DEFAULT value;
          2. UPDATE table SET column_name = value WHERE column_name IS NULL;
          3. ALTER COLUMN column_name SET NOT NULL;

Summary: 1 error(s), 2 warning(s)

Validation failed!
```

--------------------------------

### RabbitMQ Consumer Setup

Source: https://github.com/lerianstudio/midaz/blob/develop/docs/PROJECT_RULES.md

Illustrates how to set up RabbitMQ consumer routes and initialize a multi-queue consumer.

```go
routes := rabbitmq.NewConsumerRoutes(connection,
    cfg.RabbitMQNumbersOfWorkers,
    cfg.RabbitMQNumbersOfPrefetch,
    logger, telemetry)
multiQueueConsumer := NewMultiQueueConsumer(routes, useCase)
```

--------------------------------

### Install zsh-autosuggestions on Ubuntu

Source: https://github.com/lerianstudio/midaz/wiki/Mdz-(CLI)

Use apt to install zsh-autosuggestions for Zsh shell autocompletion.

```shell
sudo apt install zsh-autosuggestions
```

--------------------------------

### Install bash-completion on Arch Linux

Source: https://github.com/lerianstudio/midaz/wiki/Mdz-(CLI)

Use pacman to install bash-completion for Bash shell autocompletion.

```shell
sudo pacman -S bash-completion
```

--------------------------------

### Install zsh-autosuggestions on Fedora

Source: https://github.com/lerianstudio/midaz/wiki/Mdz-(CLI)

Use dnf to install zsh-autosuggestions for Zsh shell autocompletion.

```shell
sudo dnf install zsh-autosuggestions
```

--------------------------------

### Install bash-completion on macOS

Source: https://github.com/lerianstudio/midaz/wiki/Mdz-(CLI)

Use Homebrew to install bash-completion for Bash shell autocompletion.

```shell
brew install bash-completion
```

--------------------------------

### Install zsh-autosuggestions using Git

Source: https://github.com/lerianstudio/midaz/wiki/Mdz-(CLI)

Clone the zsh-autosuggestions repository into the Oh My Zsh custom plugins directory.

```shell
git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions
```

--------------------------------

### Makefile: Build and Run Commands

Source: https://github.com/lerianstudio/midaz/blob/develop/llms-full.txt

Commands for building, running, and managing the project services. Includes options for starting, stopping, restarting, and rebuilding services.

```bash
# Build & Run
make build                    # Build ledger + CRM
make up                       # Start all services (infra → ledger → CRM)
make down                     # Stop all services
make restart                  # Restart all services
make rebuild-up               # Rebuild and restart
make logs                     # Show logs
```

--------------------------------

### Install zsh-autosuggestions on Arch Linux

Source: https://github.com/lerianstudio/midaz/wiki/Mdz-(CLI)

Use pacman to install zsh-autosuggestions for Zsh shell autocompletion.

```shell
sudo pacman -S zsh-autosuggestions
```

--------------------------------

### Commit Message Examples

Source: https://github.com/lerianstudio/midaz/blob/develop/docs/PROJECT_RULES.md

Examples of valid commit messages following the specified type and scope format.

```git
feat(auth): add login functionality
```

```git
fix(ledger): correct balance calculation
```

```git
docs: update README
```

```git
test(crm): add user validation tests
```

--------------------------------

### Newman CLI Setup and Execution

Source: https://github.com/lerianstudio/midaz/blob/develop/postman/README.md

Configuration and execution command for Newman to run the Postman collection, including environment loading and report generation.

```bash
newman run "Complete API Workflow.postman_collection.json" --environment MIDAZ.postman_environment.json --reporters cli,html --reporter-html-export report.html
```

--------------------------------

### API URL Structure Example

Source: https://github.com/lerianstudio/midaz/blob/develop/docs/PROJECT_RULES.md

Illustrates the standard URL structure for the API, including versioning, organization and ledger IDs, resources, and actions.

```plaintext
/v1/organizations/{organization_id}/ledgers/{ledger_id}/{resources}/{action}
```

--------------------------------

### Generate Postman Collection and Run Tests

Source: https://github.com/lerianstudio/midaz/blob/develop/postman/README.md

Quick start commands to generate the Postman collection from OpenAPI specs and run the complete API workflow tests.

```bash
# Generate Postman collection from OpenAPI specs
make generate-docs

# Run complete API workflow tests
make newman
```

--------------------------------

### Create an Organization

Source: https://github.com/lerianstudio/midaz/wiki/RFC:-Onboarding

Registers a new organization on the platform. This is the initial step for a company to start using Midaz.

```APIDOC
## POST v1/organizations

### Description
Registers a new organization on the platform. This is the initial step for a company to start using Midaz.

### Method
POST

### Endpoint
v1/organizations

### Parameters
#### Request Body
- **legalName** (string) - Required - The legal name of the organization.
- **parentOrganizationId** (string) - Optional - The ID of the parent organization, if this organization is a subsidiary.
- **doingBusinessAs** (string) - Optional - The name the organization does business as.
- **legalDocument** (string) - Required - The legal document identifier for the organization.
- **status** (object) - Optional - The status of the organization. Defaults to ACTIVE.
  - **code** (string) - Optional - The status code. Defaults to "ACTIVE".
  - **description** (string) - Optional - A description for the status.
- **address** (object) - Required - The physical address of the organization.
  - **line1** (string) - Required - The first line of the address.
  - **line2** (string) - Optional - The second line of the address.
  - **zipCode** (string) - Required - The postal code.
  - **city** (string) - Required - The city.
  - **state** (string) - Required - The state or province.
  - **country** (string) - Required - The country code (ISO 3166-1 alpha2).
- **metadata** (object) - Optional - Additional key-value metadata for the organization.
  - **key** (string) - Required - The metadata key.
  - **value** (any) - Required - The metadata value.

### Request Example
```json
{
  "legalName": "Lerian Studio",
  "parentOrganizationId": null,
  "doingBusinessAs": "Lerian",
  "legalDocument": "123456789",
  "status": {
    "code": "ACTIVE"
  },
  "address": {
    "line1": "Avenida Paulista, 10000",
    "line2": "Centro",
    "zipCode": "04023060",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR"
  },
  "metadata": {
    "key": "value",
    "boolean": true,
    "double": 10.5,
    "int": 1
  }
}
```
```

--------------------------------

### Swagger Documentation for Create Transaction Endpoint

Source: https://github.com/lerianstudio/midaz/blob/develop/docs/PROJECT_RULES.md

Example of Swagger annotations for documenting the Create Transaction API endpoint, including parameters, responses, and routing.

```go
// @Summary      Create a Transaction
// @Description  Create a Transaction with the input payload
// @Tags         Transactions
// @Accept       json
// @Produce      json
// @Param        Authorization    header  string  true   "Authorization Bearer Token"
// @Param        organization_id  path    string  true   "Organization ID"
// @Param        transaction      body    CreateTransactionInput  true  "Transaction Input"
// @Success      201  {object}  Transaction
// @Failure      400  {object}  mmodel.Error
// @Failure      422  {object}  mmodel.Error
// @Router       /v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/json [post]
func (h *TransactionHandler) CreateTransactionJSON(p any, c *fiber.Ctx) error
```

--------------------------------

### Multi-Source Transaction Example

Source: https://github.com/lerianstudio/midaz/wiki/RFC:-Transactions

Employ this format when drawing funds from multiple source accounts for a single transaction. It allows specifying amounts from each source, summing up to the total transaction value.

```Midaz DSL
(transaction v1
  (send BRL 30|4 
    (source
      (from @John_Doe :amount BRL 15|4),
      (from @Jane_Doe :amount BRL 15|4)
  ) )
  (distribute
    (to @Jane_Son :share 100)
  )
)
```

--------------------------------

### Install zsh-autosuggestions on Alpine

Source: https://github.com/lerianstudio/midaz/wiki/Mdz-(CLI)

Use apk to install zsh-autosuggestions for Zsh shell autocompletion.

```shell
sudo apk add zsh-autosuggestions
```

--------------------------------

### Query Building with Squirrel

Source: https://github.com/lerianstudio/midaz/blob/develop/docs/PROJECT_RULES.md

Demonstrates how to build SQL queries using the Squirrel library, including selecting columns, specifying the table, and applying filters.

```go
findQuery := squirrel.Select(columnList...). 
    From("organization").
    Where(squirrel.Eq{"id": id}).
    Where(squirrel.Eq{"deleted_at": nil}).
    PlaceholderFormat(squirrel.Dollar)

query, args, err := findQuery.ToSql()
row := db.QueryRowContext(ctx, query, args...)
```

--------------------------------

### UP File Example for Adding User Preferences

Source: https://github.com/lerianstudio/midaz/blob/develop/scripts/migration_linter/docs/MIGRATION_TEMPLATE.md

This SQL script adds a JSONB column for user preferences and creates a GIN index for efficient querying. It includes checks to prevent errors if the column or index already exists.

```sql
-- 000017_add_account_preferences.up.sql

ALTER TABLE account ADD COLUMN IF NOT EXISTS preferences JSONB;

CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_account_preferences
ON account USING GIN (preferences);
```

--------------------------------

### Install zsh-autosuggestions on macOS

Source: https://github.com/lerianstudio/midaz/wiki/Mdz-(CLI)

Use Homebrew to install zsh-autosuggestions for Zsh shell autocompletion.

```shell
brew install zsh-autosuggestions
```

--------------------------------

### Build Commands

Source: https://github.com/lerianstudio/midaz/blob/develop/llms-full.txt

Commands for running unit tests, integration tests, and linting migrations.

```bash
make coverage-unit
# Unit test coverage
make coverage-integration
# Integration test coverage
make coverage
# All coverage

# Migrations
make migrate-lint
# Lint migrations
make migrate-create COMPONENT=onboarding NAME=my_migration

# Docs
make generate-docs
# Generate Swagger docs
```

--------------------------------

### Go Import Organization

Source: https://github.com/lerianstudio/midaz/blob/develop/docs/PROJECT_RULES.md

Demonstrates the standard way to organize Go imports into groups separated by blank lines: standard library, third-party generic, internal lib-commons, internal Midaz project, and external frameworks.

```go
import (
    // 1. Standard library
    "context"
    "encoding/json"
    "errors"

    // 2. Third-party generic packages
    "github.com/shopspring/decimal"

    // 3. Internal: lib-commons (with lib prefix)
    libCommons "github.com/LerianStudio/lib-commons/v4/commons"
    libLog "github.com/LerianStudio/lib-commons/v4/commons/log"

    // 4. Internal: midaz project packages
    "github.com/LerianStudio/midaz/v3/pkg"
    "github.com/LerianStudio/midaz/v3/pkg/mmodel"

    // 5. External: frameworks
    "github.com/gofiber/fiber/v2"
    "github.com/google/uuid"
)
```

--------------------------------

### Microservices Mode Component Communication

Source: https://github.com/lerianstudio/midaz/blob/develop/docs/PROJECT_RULES.md

Go code demonstrating how the onboarding service connects to the transaction service via gRPC in Microservices Mode, using a gRPC adapter.

```go
// gRPC adapter wraps network calls
grpcConnection := &mgrpc.GRPCConnection{Addr: "midaz-transaction:3011"}
balancePort := grpcout.NewBalanceAdapter(grpcConnection)
```

--------------------------------

### Gold DSL Example

Source: https://github.com/lerianstudio/midaz/blob/develop/llms-full.txt

Example of a transaction defined using the Gold DSL. This DSL is ANTLR4-based for defining transactions.

```plaintext
send $100.00 USD
  from @source_account
  to @destination_account
```

--------------------------------

### Get Balance

Source: https://github.com/lerianstudio/midaz/blob/develop/llms-full.txt

Retrieves a specific balance by its ID.

```APIDOC
## GET .../balances/:bid

### Description
Retrieves a specific balance by its ID.

### Method
GET

### Endpoint
.../balances/:bid
```

--------------------------------

### Run Migration Linter

Source: https://github.com/lerianstudio/midaz/blob/develop/scripts/migration_linter/docs/MIGRATION_GUIDELINES.md

Basic usage of the migration linter tool. Use this to check SQL migration files for dangerous patterns.

```bash
# Basic usage
migration-lint <path-to-migrations>
```

```bash
# With strict mode (treats warnings as errors)
migration-lint <path-to-migrations> --strict
```

--------------------------------

### Get Transaction

Source: https://github.com/lerianstudio/midaz/blob/develop/llms-full.txt

Retrieves a specific transaction by its ID.

```APIDOC
## GET .../transactions/:tid

### Description
Retrieves a specific transaction by its ID.

### Method
GET

### Endpoint
.../transactions/:tid
```

--------------------------------

### Load Configuration from Environment Variables

Source: https://github.com/lerianstudio/midaz/blob/develop/docs/PROJECT_RULES.md

Loads configuration into a struct from environment variables. Ensure the Config struct is properly defined with env tags.

```go
cfg := &Config{}
if err := libCommons.SetConfigFromEnvVars(cfg); err != nil {
    return nil, fmt.Errorf("failed to load config: %w", err)
}
```

--------------------------------

### Get Balance at Timestamp

Source: https://github.com/lerianstudio/midaz/blob/develop/llms-full.txt

Retrieves the balance at a specific timestamp.

```APIDOC
## GET .../balances/:bid/history

### Description
Retrieves the balance at a specific timestamp.

### Method
GET

### Endpoint
.../balances/:bid/history
```

--------------------------------

### Get Transaction Route

Source: https://github.com/lerianstudio/midaz/blob/develop/llms-full.txt

Retrieves a specific transaction route by its ID.

```APIDOC
## GET .../transaction-routes/:trid

### Description
Retrieves a specific transaction route by its ID.

### Method
GET

### Endpoint
.../transaction-routes/:trid
```

--------------------------------

### Get Operation Route

Source: https://github.com/lerianstudio/midaz/blob/develop/llms-full.txt

Retrieves a specific operation route by its ID.

```APIDOC
## GET .../operation-routes/:orid

### Description
Retrieves a specific operation route by its ID.

### Method
GET

### Endpoint
.../operation-routes/:orid
```

--------------------------------

### Get Operation

Source: https://github.com/lerianstudio/midaz/blob/develop/llms-full.txt

Retrieves a specific operation by its ID within an account.

```APIDOC
## GET .../accounts/:aid/operations/:oid

### Description
Retrieves a specific operation by its ID within an account.

### Method
GET

### Endpoint
.../accounts/:aid/operations/:oid
```

--------------------------------

### Test Assertion Strategies with Require and Assert

Source: https://github.com/lerianstudio/midaz/blob/develop/docs/PROJECT_RULES.md

Illustrates the usage of `require` and `assert` packages for making assertions in tests. `require` fails the test immediately upon failure, useful for flow control, while `assert` continues execution.

```go
// Use require for flow control (fails immediately)
require.NoError(t, err)
require.Equal(t, expected, actual)

// Use assert for result verification (continues)
assert.NotNil(t, result)
assert.Equal(t, expected, actual)
```

--------------------------------

### Get Asset Rate

Source: https://github.com/lerianstudio/midaz/blob/develop/llms-full.txt

Retrieves a specific asset rate by its external ID.

```APIDOC
## GET .../asset-rates/:external_id

### Description
Retrieves a specific asset rate by its external ID.

### Method
GET

### Endpoint
.../asset-rates/:external_id
```

--------------------------------

### Get Balance

Source: https://github.com/lerianstudio/midaz/blob/develop/postman/WORKFLOW.md

Retrieves the details of a specific balance. Requires organization, ledger, and balance IDs.

```APIDOC
## GET /v1/organizations/{organizationId}/ledgers/{ledgerId}/balances/{balanceId}

### Description
Retrieves the balance details.

### Method
GET

### Endpoint
/v1/organizations/{organizationId}/ledgers/{ledgerId}/balances/{balanceId}

### Parameters
#### Path Parameters
- **organizationId** (string) - Required - The ID of the organization.
- **ledgerId** (string) - Required - The ID of the ledger.
- **balanceId** (string) - Required - The ID of the balance.
```

--------------------------------

### Handle Prefixed and Non-Prefixed Environment Variables

Source: https://github.com/lerianstudio/midaz/blob/develop/docs/PROJECT_RULES.md

Supports both unified and standalone deployment modes by prioritizing prefixed environment variables and falling back to non-prefixed ones. The envFallback helper function resolves the final value.

```go
// Prefixed (unified mode) - takes precedence
PrefixedPrimaryDBHost string `env:"DB_ONBOARDING_HOST"`

// Non-prefixed (standalone mode) - fallback
PrimaryDBHost string `env:"DB_HOST"`

// Resolution
dbHost := envFallback(cfg.PrefixedPrimaryDBHost, cfg.PrimaryDBHost)
```

--------------------------------

### Infrastructure Environment Variables

Source: https://github.com/lerianstudio/midaz/blob/develop/llms-full.txt

Lists environment variables for infrastructure components, including PostgreSQL, MongoDB, Redis, and RabbitMQ connection details, as well as OpenTelemetry ports. Defaults are provided.

```Go
DB_HOST = "midaz-postgres-primary"
DB_USER = "midaz"
DB_PASSWORD = "lerian"
DB_PORT = 5701
MAX_CONNECTIONS = 3000
SHARED_BUFFERS = "1GB"
DB_REPLICA_HOST = "midaz-postgres-replica"
DB_REPLICA_PORT = 5702
REPLICATION_USER = "replicator"
REPLICATION_PASSWORD = "—"
MONGO_HOST = "midaz-mongodb"
MONGO_USER = "midaz"
MONGO_PASSWORD = "lerian"
MONGO_PORT = 5703
REDIS_HOST = "midaz-valkey"
REDIS_PORT = 5704
REDIS_USER = "midaz"
REDIS_PASSWORD = "lerian"
RABBITMQ_PORT_HOST = 3003
RABBITMQ_PORT_AMQP = 3004
RABBITMQ_DEFAULT_USER = "midaz"
RABBITMQ_DEFAULT_PASS = "lerian"
OTEL_LGTM_INTERNAL_PORT = 3000
OTEL_LGTM_EXTERNAL_PORT = 3100
OTEL_LGTM_RECEIVER_GRPC_PORT = 4317
OTEL_LGTM_RECEIVER_HTTP_PORT = 4318
OTEL_LGTM_ADMIN_USER = "midaz"
OTEL_LGTM_ADMIN_PASSWORD = "lerian"
```

--------------------------------

### Configure Fish for Autocomplete

Source: https://github.com/lerianstudio/midaz/wiki/Mdz-(CLI)

Set up Mdz CLI autocompletion for the Fish shell by sourcing the completion script in config.fish.

```shell
echo "mdz completion fish | source" >> ~/.config/fish/config.fish
```

--------------------------------

### Get Operation

Source: https://github.com/lerianstudio/midaz/blob/develop/postman/WORKFLOW.md

Retrieves the details of a specific operation. Requires organization, ledger, account, and operation IDs.

```APIDOC
## GET /v1/organizations/{organizationId}/ledgers/{ledgerId}/accounts/{accountId}/operations/{operationId}

### Description
Retrieves the operation details.

### Method
GET

### Endpoint
/v1/organizations/{organizationId}/ledgers/{ledgerId}/accounts/{accountId}/operations/{operationId}

### Parameters
#### Path Parameters
- **organizationId** (string) - Required - The ID of the organization.
- **ledgerId** (string) - Required - The ID of the ledger.
- **accountId** (string) - Required - The ID of the account.
- **operationId** (string) - Required - The ID of the operation.
```

--------------------------------

### Unified Mode Component Communication

Source: https://github.com/lerianstudio/midaz/blob/develop/docs/PROJECT_RULES.md

Go code demonstrating in-process calls between transaction and onboarding modules in Unified Mode, using the BalancePort directly.

```go
// Transaction module initialized first to expose BalancePort
transactionService := transaction.InitServiceWithOptionsOrError(&transaction.Options{Logger: logger})
balancePort := transactionService.GetBalancePort()

// Onboarding module uses BalancePort for direct in-process calls (no gRPC overhead)
onboardingService := onboarding.InitServiceWithOptionsOrError(&onboarding.Options{
    UnifiedMode: true,
    BalancePort: balancePort,  // Direct UseCase reference
})
```

--------------------------------

### Migration Phase 2: New Implementation with Fallback

Source: https://github.com/lerianstudio/midaz/blob/develop/scripts/postman-coll-generation/README.md

Transition to using the new workflow implementation, with the ability to fall back to the old implementation in case of failures.

```bash
# Use new implementation, fallback to old on failure
USE_NEW_WORKFLOW_GENERATOR=true node create-workflow-wrapper.js ...
```

--------------------------------

### Get Transaction

Source: https://github.com/lerianstudio/midaz/blob/develop/postman/WORKFLOW.md

Retrieves the details of a specific transaction. Requires organization, ledger IDs, and the transaction ID.

```APIDOC
## GET /v1/organizations/{organizationId}/ledgers/{ledgerId}/transactions/{transactionId}

### Description
Retrieves the transaction details.

### Method
GET

### Endpoint
/v1/organizations/{organizationId}/ledgers/{ledgerId}/transactions/{transactionId}

### Parameters
#### Path Parameters
- **organizationId** (string) - Required - The ID of the organization.
- **ledgerId** (string) - Required - The ID of the ledger.
- **transactionId** (string) - Required - The ID of the transaction.
```

--------------------------------

### Get Ledger

Source: https://github.com/lerianstudio/midaz/blob/develop/postman/WORKFLOW.md

Retrieves the details of a specific ledger within an organization using both organization and ledger IDs.

```APIDOC
## GET /v1/organizations/{organizationId}/ledgers/{ledgerId}

### Description
Retrieves the ledger details.

### Method
GET

### Endpoint
/v1/organizations/{organizationId}/ledgers/{ledgerId}

### Parameters
#### Path Parameters
- **organizationId** (string) - Required - The ID of the organization.
- **ledgerId** (string) - Required - The ID of the ledger to retrieve.
```

--------------------------------

### Direct Usage of New Implementation

Source: https://github.com/lerianstudio/midaz/blob/develop/scripts/postman-coll-generation/README.md

Execute the new workflow generator directly using the command line. Provide input JSON, workflow Markdown, and output JSON file paths.

```bash
node create-workflow-v2.js input.json WORKFLOW.md output.json
```