{
  "version": "1.0",
  "modules": [
    {
      "name": "Loan Calculations",
      "prefix": "/calculations",
      "endpoints": [
        {
          "method": "POST",
          "path": "/",
          "summary": "Create Loan Calculation",
          "description": "Creates a new loan calculation with input parameters (principal, annual interest rate, loan term). Automatically calculates monthly payment, total interest, and generates complete amortization schedule. Returns 400 if validation fails.",
          "request_body": {
            "schema_name": "CalculationCreate",
            "fields": [
              {
                "name": "principal",
                "type": "Decimal",
                "required": false
              },
              {
                "name": "annual_interest_rate",
                "type": "Decimal",
                "required": false
              },
              {
                "name": "loan_term_months",
                "type": "int",
                "required": false
              },
              {
                "name": "calculation_method",
                "type": "str",
                "required": false
              },
              {
                "name": "start_date",
                "type": "date",
                "required": false,
                "nullable": true
              }
            ]
          },
          "response": {
            "schema_name": "CalculationResponse",
            "fields": [
              {
                "name": "id",
                "type": "StrId",
                "required": true
              },
              {
                "name": "principal",
                "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_interest",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "total_amount_paid",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "calculation_method",
                "type": "str",
                "required": true
              },
              {
                "name": "start_date",
                "type": "date",
                "required": false,
                "nullable": 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 Calculation Summary",
          "description": "Retrieves a single loan calculation summary by ID without amortization schedule entries. Returns 404 if calculation does not exist.",
          "path_params": [
            {
              "name": "calculation_id",
              "type": "str"
            }
          ],
          "response": {
            "schema_name": "CalculationResponse",
            "fields": [
              {
                "name": "id",
                "type": "StrId",
                "required": true
              },
              {
                "name": "principal",
                "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_interest",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "total_amount_paid",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "calculation_method",
                "type": "str",
                "required": true
              },
              {
                "name": "start_date",
                "type": "date",
                "required": false,
                "nullable": 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 Calculation With Schedule",
          "description": "Retrieves a loan calculation with full amortization schedule including all payment entries. Each entry shows payment number, date, balances, principal/interest breakdown, and cumulative interest. Returns 404 if calculation does not exist.",
          "path_params": [
            {
              "name": "calculation_id",
              "type": "str"
            }
          ],
          "response": {
            "schema_name": "CalculationDetailResponse",
            "fields": [
              {
                "name": "id",
                "type": "StrId",
                "required": true
              },
              {
                "name": "principal",
                "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_interest",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "total_amount_paid",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "calculation_method",
                "type": "str",
                "required": true
              },
              {
                "name": "start_date",
                "type": "date",
                "required": false,
                "nullable": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "amortization_schedule_entries",
                "type": "List[AmortizationscheduleentryResponse]",
                "required": true,
                "is_list": true,
                "item_fields": [
                  {
                    "name": "id",
                    "type": "StrId",
                    "required": true
                  },
                  {
                    "name": "calculation_id",
                    "type": "StrId",
                    "required": true
                  },
                  {
                    "name": "payment_number",
                    "type": "int",
                    "required": true
                  },
                  {
                    "name": "payment_date",
                    "type": "date",
                    "required": true
                  },
                  {
                    "name": "beginning_balance",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "payment_amount",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "principal_payment",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "interest_payment",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "ending_balance",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "cumulative_interest",
                    "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": "/",
          "summary": "List Calculations",
          "description": "Returns a paginated list of all loan calculations ordered by creation date (newest first). Supports standard pagination via limit and offset parameters.",
          "query_params": [
            {
              "name": "limit",
              "type": "int",
              "required": false,
              "default": 20
            },
            {
              "name": "offset",
              "type": "int",
              "required": false,
              "default": 0
            }
          ],
          "response": {
            "schema_name": "PaginatedCalculationResponse",
            "fields": [
              {
                "name": "items",
                "type": "List[CalculationResponse]",
                "required": true,
                "is_list": true,
                "item_fields": [
                  {
                    "name": "id",
                    "type": "StrId",
                    "required": true
                  },
                  {
                    "name": "principal",
                    "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_interest",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "total_amount_paid",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "calculation_method",
                    "type": "str",
                    "required": true
                  },
                  {
                    "name": "start_date",
                    "type": "date",
                    "required": false,
                    "nullable": 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": "DELETE",
          "path": "/{calculation_id}",
          "summary": "Delete Calculation",
          "description": "Deletes a loan calculation and cascades deletion to all associated amortization schedule entries. Returns 404 if calculation does not exist.",
          "path_params": [
            {
              "name": "calculation_id",
              "type": "str"
            }
          ],
          "status_code": 204
        }
      ]
    }
  ],
  "enums": {}
}