{
  "version": "1.0",
  "modules": [
    {
      "name": "SIP Calculations",
      "prefix": "/calculations",
      "endpoints": [
        {
          "method": "POST",
          "path": "/",
          "summary": "Create New SIP Calculation",
          "description": "Creates a new SIP calculation with input parameters (monthly investment, expected return rate, time period). Validates inputs against business rules, applies SIP formula with monthly compounding, computes total investment, estimated returns, and maturity value, generates year-by-year chart data points, and returns the complete calculation with result and chart data immediately.",
          "request_body": {
            "schema_name": "CalculationinputCreate",
            "fields": [
              {
                "name": "monthly_investment",
                "type": "Decimal",
                "required": false
              },
              {
                "name": "expected_return_rate",
                "type": "Decimal",
                "required": false
              },
              {
                "name": "time_period",
                "type": "int",
                "required": false
              }
            ]
          },
          "response": {
            "schema_name": "CalculationWithResultAndChartResponse",
            "fields": [
              {
                "name": "calculation_input",
                "type": "CalculationinputResponse",
                "required": true,
                "fields": [
                  {
                    "name": "id",
                    "type": "StrId",
                    "required": true
                  },
                  {
                    "name": "monthly_investment",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "expected_return_rate",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "time_period",
                    "type": "int",
                    "required": true
                  },
                  {
                    "name": "timestamp",
                    "type": "datetime",
                    "required": true
                  },
                  {
                    "name": "created_at",
                    "type": "datetime",
                    "required": true
                  },
                  {
                    "name": "updated_at",
                    "type": "datetime",
                    "required": true
                  }
                ]
              },
              {
                "name": "calculation_result",
                "type": "CalculationresultResponse",
                "required": true,
                "fields": [
                  {
                    "name": "id",
                    "type": "StrId",
                    "required": true
                  },
                  {
                    "name": "calculation_input_id",
                    "type": "StrId",
                    "required": true
                  },
                  {
                    "name": "total_investment",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "estimated_returns",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "maturity_value",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "created_at",
                    "type": "datetime",
                    "required": true
                  },
                  {
                    "name": "updated_at",
                    "type": "datetime",
                    "required": true
                  }
                ]
              },
              {
                "name": "chart_data_points",
                "type": "List[ChartdatapointResponse]",
                "required": true,
                "is_list": true,
                "item_fields": [
                  {
                    "name": "id",
                    "type": "StrId",
                    "required": true
                  },
                  {
                    "name": "calculation_input_id",
                    "type": "StrId",
                    "required": true
                  },
                  {
                    "name": "year",
                    "type": "int",
                    "required": true
                  },
                  {
                    "name": "invested_amount",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "projected_value",
                    "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": "/{id}",
          "summary": "Retrieve Calculation Input by ID",
          "description": "Returns the calculation input record for the specified ID. Returns 404 if the calculation does not exist.",
          "path_params": [
            {
              "name": "id",
              "type": "str"
            }
          ],
          "response": {
            "schema_name": "CalculationinputResponse",
            "fields": [
              {
                "name": "id",
                "type": "StrId",
                "required": true
              },
              {
                "name": "monthly_investment",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "expected_return_rate",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "time_period",
                "type": "int",
                "required": true
              },
              {
                "name": "timestamp",
                "type": "datetime",
                "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": "/{id}/details",
          "summary": "Retrieve Calculation with Result and Chart Data",
          "description": "Returns the complete calculation including the input parameters, computed result (total investment, estimated returns, maturity value), and all year-by-year chart data points for visualization. Uses eager loading to efficiently fetch all related data in a single query. Returns 404 if the calculation does not exist.",
          "path_params": [
            {
              "name": "id",
              "type": "str"
            }
          ],
          "response": {
            "schema_name": "CalculationDetailsResponse",
            "fields": [
              {
                "name": "id",
                "type": "StrId",
                "required": true
              },
              {
                "name": "monthly_investment",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "expected_return_rate",
                "type": "Decimal",
                "required": true
              },
              {
                "name": "time_period",
                "type": "int",
                "required": true
              },
              {
                "name": "timestamp",
                "type": "datetime",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "calculation_result",
                "type": "CalculationresultResponse",
                "required": false,
                "nullable": true,
                "fields": [
                  {
                    "name": "id",
                    "type": "StrId",
                    "required": true
                  },
                  {
                    "name": "calculation_input_id",
                    "type": "StrId",
                    "required": true
                  },
                  {
                    "name": "total_investment",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "estimated_returns",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "maturity_value",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "created_at",
                    "type": "datetime",
                    "required": true
                  },
                  {
                    "name": "updated_at",
                    "type": "datetime",
                    "required": true
                  }
                ]
              },
              {
                "name": "chart_data_points",
                "type": "List[ChartdatapointResponse]",
                "required": false,
                "is_list": true,
                "item_fields": [
                  {
                    "name": "id",
                    "type": "StrId",
                    "required": true
                  },
                  {
                    "name": "calculation_input_id",
                    "type": "StrId",
                    "required": true
                  },
                  {
                    "name": "year",
                    "type": "int",
                    "required": true
                  },
                  {
                    "name": "invested_amount",
                    "type": "Decimal",
                    "required": true
                  },
                  {
                    "name": "projected_value",
                    "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 All Calculations",
          "description": "Returns a paginated list of all calculation inputs. Supports optional filtering by timestamp range to find calculations performed within a specific time window. Results are ordered by creation timestamp descending (most recent first).",
          "query_params": [
            {
              "name": "limit",
              "type": "int",
              "required": false,
              "default": 20
            },
            {
              "name": "offset",
              "type": "int",
              "required": false,
              "default": 0
            },
            {
              "name": "timestamp_start",
              "type": "datetime",
              "required": false
            },
            {
              "name": "timestamp_end",
              "type": "datetime",
              "required": false
            }
          ],
          "response": {
            "schema_name": "PaginatedResponse[CalculationinputResponse]",
            "is_list": false,
            "fields": []
          },
          "status_code": 200
        },
        {
          "method": "DELETE",
          "path": "/{id}",
          "summary": "Delete Calculation",
          "description": "Deletes the specified calculation input and all associated data (calculation result and chart data points) via cascade delete. Returns 404 if the calculation does not exist. This operation is permanent and cannot be undone.",
          "path_params": [
            {
              "name": "id",
              "type": "str"
            }
          ],
          "status_code": 204
        }
      ]
    }
  ],
  "enums": {}
}