{
  "version": "1.0",
  "modules": [
    {
      "name": "Loan Calculations",
      "prefix": "/loan-calculations",
      "endpoints": [
        {
          "method": "POST",
          "path": "/",
          "summary": "Create Loan Calculation With Schedule",
          "description": "Creates a new loan calculation and generates the complete amortization schedule. Validates input parameters, calculates monthly payment using standard amortization formula, computes total amount paid and total interest paid, and generates all schedule entries showing payment breakdown for each period. Returns the created loan calculation with computed results.",
          "request_body": {
            "schema_name": "LoancalculationCreate",
            "fields": [
              {
                "name": "principal_amount",
                "type": "Decimal",
                "required": false
              },
              {
                "name": "annual_interest_rate",
                "type": "Decimal",
                "required": false
              },
              {
                "name": "loan_term_months",
                "type": "int",
                "required": false
              }
            ]
          },
          "response": {
            "schema_name": "LoancalculationResponse",
            "fields": [
              {
                "name": "id",
                "type": "StrId",
                "required": true
              },
              {
                "name": "principal_amount",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "annual_interest_rate",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "loan_term_months",
                "type": "int",
                "required": true
              },
              {
                "name": "monthly_payment",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "total_amount_paid",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "total_interest_paid",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 201
        },
        {
          "method": "GET",
          "path": "/{calculation_id}",
          "summary": "Get Loan Calculation Summary",
          "description": "Retrieves a loan calculation summary by ID. Returns the calculation input parameters and computed results including monthly payment, total amount paid, and total interest paid. Returns 404 if the calculation ID does not exist.",
          "path_params": [
            {
              "name": "calculation_id",
              "type": "str"
            }
          ],
          "response": {
            "schema_name": "LoancalculationResponse",
            "fields": [
              {
                "name": "id",
                "type": "StrId",
                "required": true
              },
              {
                "name": "principal_amount",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "annual_interest_rate",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "loan_term_months",
                "type": "int",
                "required": true
              },
              {
                "name": "monthly_payment",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "total_amount_paid",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "total_interest_paid",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 200
        },
        {
          "method": "GET",
          "path": "/{calculation_id}/details",
          "summary": "Get Loan Calculation With Schedule",
          "description": "Retrieves a loan calculation with the complete amortization schedule. Returns the calculation summary plus all schedule entries showing payment number, payment date (if set), payment amount, principal portion, interest portion, remaining balance, and cumulative totals for each payment period over the loan lifetime. Returns 404 if the calculation ID does not exist.",
          "path_params": [
            {
              "name": "calculation_id",
              "type": "str"
            }
          ],
          "response": {
            "schema_name": "LoancalculationWithScheduleResponse",
            "fields": [
              {
                "name": "id",
                "type": "StrId",
                "required": true
              },
              {
                "name": "principal_amount",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "annual_interest_rate",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "loan_term_months",
                "type": "int",
                "required": true
              },
              {
                "name": "monthly_payment",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "total_amount_paid",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "total_interest_paid",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "amortization_schedule_entries",
                "type": "List[AmortizationscheduleentrySummary]",
                "required": true,
                "is_list": true,
                "item_fields": [
                  {
                    "name": "payment_number",
                    "type": "int",
                    "required": true
                  },
                  {
                    "name": "payment_date",
                    "type": "date",
                    "required": false,
                    "nullable": true
                  },
                  {
                    "name": "payment_amount",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "principal_portion",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "interest_portion",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "remaining_balance",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "cumulative_interest",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "cumulative_principal",
                    "type": "Decimal",
                    "required": true
                  }
                ]
              }
            ],
            "is_list": false
          },
          "status_code": 200
        },
        {
          "method": "GET",
          "path": "/",
          "summary": "List Loan Calculations",
          "description": "Returns a paginated list of all loan calculations ordered by creation date descending. Supports pagination via limit and offset query parameters.",
          "query_params": [
            {
              "name": "limit",
              "type": "int",
              "required": false,
              "default": 20
            },
            {
              "name": "offset",
              "type": "int",
              "required": false,
              "default": 0
            }
          ],
          "response": {
            "schema_name": "PaginatedLoancalculationResponse",
            "fields": [
              {
                "name": "items",
                "type": "List[LoancalculationResponse]",
                "required": true,
                "is_list": true,
                "item_fields": [
                  {
                    "name": "id",
                    "type": "StrId",
                    "required": true
                  },
                  {
                    "name": "principal_amount",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "annual_interest_rate",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "loan_term_months",
                    "type": "int",
                    "required": true
                  },
                  {
                    "name": "monthly_payment",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "total_amount_paid",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "total_interest_paid",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "created_at",
                    "type": "datetime",
                    "required": true
                  },
                  {
                    "name": "updated_at",
                    "type": "datetime",
                    "required": true
                  }
                ]
              },
              {
                "name": "total",
                "type": "int",
                "required": true
              },
              {
                "name": "limit",
                "type": "int",
                "required": true
              },
              {
                "name": "offset",
                "type": "int",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 200
        },
        {
          "method": "PATCH",
          "path": "/{calculation_id}",
          "summary": "Update Loan Calculation",
          "description": "Updates one or more fields of an existing loan calculation. Only provided fields are updated; unset fields remain unchanged. Returns 404 if the calculation ID does not exist, 400 if no fields are provided.",
          "path_params": [
            {
              "name": "calculation_id",
              "type": "str"
            }
          ],
          "request_body": {
            "schema_name": "LoancalculationUpdate",
            "fields": [
              {
                "name": "principal_amount",
                "type": "Decimal",
                "required": false,
                "nullable": true
              },
              {
                "name": "annual_interest_rate",
                "type": "Decimal",
                "required": false,
                "nullable": true
              },
              {
                "name": "loan_term_months",
                "type": "int",
                "required": false,
                "nullable": true
              },
              {
                "name": "monthly_payment",
                "type": "Decimal",
                "required": false,
                "nullable": true
              },
              {
                "name": "total_amount_paid",
                "type": "Decimal",
                "required": false,
                "nullable": true
              },
              {
                "name": "total_interest_paid",
                "type": "Decimal",
                "required": false,
                "nullable": true
              }
            ]
          },
          "response": {
            "schema_name": "LoancalculationResponse",
            "fields": [
              {
                "name": "id",
                "type": "StrId",
                "required": true
              },
              {
                "name": "principal_amount",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "annual_interest_rate",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "loan_term_months",
                "type": "int",
                "required": true
              },
              {
                "name": "monthly_payment",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "total_amount_paid",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "total_interest_paid",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 200
        },
        {
          "method": "DELETE",
          "path": "/{calculation_id}",
          "summary": "Delete Loan Calculation",
          "description": "Deletes a loan calculation and cascade deletes all associated amortization schedule entries. Returns 404 if the calculation ID does not exist.",
          "path_params": [
            {
              "name": "calculation_id",
              "type": "str"
            }
          ],
          "status_code": 200
        }
      ]
    }
  ],
  "enums": {}
}