API Reference
=============

This guide is intended for developers who wish to build their own frontend applications or integrations on top of the Calyntro API.

The API is built with **FastAPI** and follows RESTful principles. All responses are JSON-formatted.

.. note::
   The Base URL for all endpoints is ``/v1``.

Common Concepts
---------------

Request Format
~~~~~~~~~~~~~~
Most analysis endpoints accept ``POST`` requests to allow for complex filtering parameters in the body.
Dates should be provided in ISO 8601 format (e.g., ``2023-01-01T00:00:00``).

**Standard Filter Parameters:**

Many endpoints use a common filter structure:

*   ``start_date``: The beginning of the analysis time window.
*   ``end_date``: The end of the analysis time window.
*   ``module_name``: Optional. Filter results to a specific architectural component/module.

.. note::
   Some older endpoints use ``from`` (aliased from ``from_``) and ``to`` instead of ``start_date`` and ``end_date``. These are noted in the respective sections.

Response Format
~~~~~~~~~~~~~~~
Most list-based responses wrap the results in an ``items`` array:

.. code-block:: json

   {
     "items": [
       { ... },
       { ... }
     ]
   }

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

Lines of Code (LOC)
-------------------

Endpoints for analyzing the size of the codebase.

Get LOC per File
~~~~~~~~~~~~~~~~
Returns the Lines of Code count for each file, based on the latest commit within the selected timeframe.

*   **URL:** ``/v1/analysis/loc/files``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "start_date": "2023-01-01T00:00:00",
     "end_date": "2023-12-31T23:59:59",
     "module_name": "optional_module_name"
   }

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "name": "src/main.py",
         "loc": 150
       }
     ]
   }

Get LOC per Module
~~~~~~~~~~~~~~~~~~
Returns the aggregated Lines of Code for each defined module.

*   **URL:** ``/v1/analysis/loc/modules``
*   **Method:** ``POST``

**Request Body:** Same as *Get LOC per File*.

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "name": "src/core/",
         "loc": 5240
       }
     ]
   }

Get Total LOC
~~~~~~~~~~~~~
Returns the grand total Lines of Code for the entire project (or filtered selection).

*   **URL:** ``/v1/analysis/loc/total``
*   **Method:** ``POST``
*   **Request Body:** Same as *Get LOC per File*.

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "name": "Total",
         "loc": 15420
       }
     ]
   }

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

Evolution & Pulse
-----------------

Endpoints for analyzing how the codebase changes over time.

Change Frequency (Files)
~~~~~~~~~~~~~~~~~~~~~~~~
Retrieves commit activity for files, including commit counts, author metrics, and last modification details.

*   **URL:** ``/v1/analyze/commits``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "start_date": "2023-01-01T00:00:00",
     "end_date": "2023-12-31T23:59:59",
     "module_name": "optional_module_name"
   }

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "file_path": "src/core/analysis.py",
         "commit_count": 42,
         "last_modified": "2023-12-01T10:00:00",
         "main_contributor": "John Doe",
         "author_count": 3,
         "last_commit_message": "Refactor analysis engine"
       }
     ]
   }

Change Frequency (Modules)
~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieves commit activity aggregated by module.

*   **URL:** ``/v1/analyze/modules/commits``
*   **Method:** ``POST``
*   **Request Body:** Same as *Change Frequency (Files)*.

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "module_name": "src/api/",
         "commit_count": 85,
         "last_modified": "2023-12-15T14:30:00",
         "main_contributor": "Jane Smith",
         "author_count": 5,
         "last_commit_message": "Fix API authentication"
       }
     ]
   }

Change Recency (Files)
~~~~~~~~~~~~~~~~~~~~~~
Returns the age of files (time since first and last commit).

*   **URL:** ``/v1/analyze/age``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "from_": "2023-01-01T00:00:00",
     "to": "2023-12-31T23:59:59",
     "module": "optional_module_name",
     "nbr_items": 50
   }

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "file_path": "src/utils.py",
         "first_commit": "2021-01-01T12:00:00",
         "last_commit": "2023-11-15T09:30:00",
         "age_days": 1048,
         "revisions": 15
       }
     ]
   }

Change Recency (Modules)
~~~~~~~~~~~~~~~~~~~~~~~~
Returns the age aggregated by module.

*   **URL:** ``/v1/analyze/modules/age``
*   **Method:** ``POST``
*   **Request Body:** Same as *Change Recency (Files)*.

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "module_name": "src/core/",
         "first_commit": "2020-05-10T08:00:00",
         "last_commit": "2023-12-01T16:45:00",
         "age_days": 1300,
         "revisions": 450
       }
     ]
   }

Absolute Churn
~~~~~~~~~~~~~~
Returns the absolute churn (added + deleted lines) per file.

*   **URL:** ``/v1/analyze/abs_churn/files``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "from": "2023-01-01T00:00:00",
     "to": "2023-12-31T23:59:59",
     "module": "optional_module_name",
     "nbr_items": 100
   }

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "file_path": "src/db/connection.py",
         "abs_churn": 1250,
         "total_added": 800,
         "total_deleted": 450,
         "first_change": "2023-01-15T10:00:00",
         "last_change": "2023-11-20T15:30:00",
         "revisions": 12
       }
     ]
   }

Absolute Churn (Modules)
~~~~~~~~~~~~~~~~~~~~~~~~
Returns the absolute churn aggregated by module.

*   **URL:** ``/v1/analyze/abs_churn/modules``
*   **Method:** ``POST``
*   **Request Body:** Same as *Absolute Churn*.

Development Trend
~~~~~~~~~~~~~~~~~
Analyzes the evolution of hotspots by comparing a baseline time window with a current time window.

*   **URL:** ``/v1/analyze/hotspot_trends``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "baseline": {
       "from": "2023-01-01T00:00:00",
       "to": "2023-06-30T23:59:59"
     },
     "current": {
       "from": "2023-07-01T00:00:00",
       "to": "2023-12-31T23:59:59"
     },
     "module": "optional_module_name",
     "nbr_items": 50
   }

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "file_path": "src/core/analysis.py",
         "churn_baseline": 450,
         "churn_current": 820,
         "scores": {
           "structural": {
             "baseline": 0.45,
             "current": 0.82,
             "delta": 0.37,
             "delta_norm": 0.5,
             "norm": 0.6,
             "trend": "up"
           },
           "activity": {
             "baseline": 15,
             "current": 25,
             "delta": 10,
             "delta_norm": 0.4,
             "norm": 0.5,
             "trend": "up"
           }
         }
       }
     ]
   }

File Trend History
~~~~~~~~~~~~~~~~~~
Returns the historical development of metrics for a specific file.

*   **URL:** ``/v1/analyze/file_trend``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "file_path": "src/core/service.py",
     "start_date": "2023-01-01T00:00:00",
     "end_date": "2023-12-31T23:59:59",
     "bucket_days": 14,
     "metric": "churn"
   }

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "file_path": "src/core/service.py",
         "metric": "churn",
         "from_date": "2023-01-01T00:00:00",
         "to_date": "2023-12-31T23:59:59",
         "bucket_days": 14,
         "series": [
           {
             "t": "2023-01-01T00:00:00",
             "value": 150
           },
           {
             "t": "2023-01-15T00:00:00",
             "value": 240
           }
         ]
       }
     ]
   }

Module Trend History
~~~~~~~~~~~~~~~~~~~~
Returns the historical development of a single churn-based metric for one module.

*   **URL:** ``/v1/analyze/module_trend``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "module_name": "src/api/",
     "start_date": "2023-01-01T00:00:00",
     "end_date": "2023-12-31T23:59:59",
     "bucket_days": 14,
     "metric": "churn"
   }

**Response:** Same structure as *File Trend History*.

Per-Module Trends (Visual View)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns bucketed time series for **four metrics simultaneously** across all modules
(or a requested subset). This is the data source for the Trend Analysis visual view
in the dashboard. All modules share an identical time axis so the frontend can
render them on a common x-axis without further alignment.

*   **URL:** ``/v1/analysis/trends/modules``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "start_date":   "2024-01-01T00:00:00",
     "end_date":     "2024-12-31T23:59:59",
     "bucket_days":  30,
     "module_names": ["core", "api"]
   }

.. list-table:: Request Parameters
   :header-rows: 1
   :widths: 20 10 70

   * - Parameter
     - Required
     - Description
   * - ``start_date``
     - No
     - Start of the analysis window; defaults to 12 months before ``end_date``.
   * - ``end_date``
     - No
     - End of the analysis window; defaults to now.
   * - ``bucket_days``
     - No
     - Width of each time bucket in days. Default: ``30``.
   * - ``module_names``
     - No
     - List of component names to include. ``null`` or omitted returns all modules.

**Response:**

.. code-block:: json

   {
     "items": {
       "bucket_days": 30,
       "buckets": [
         "2024-01-01T00:00:00",
         "2024-02-01T00:00:00"
       ],
       "modules": [
         {
           "module_name": "core",
           "complexity":  [21.3, 22.1],
           "loc":         [14200, 14850],
           "silo_ratio":  [16.4, 17.1],
           "commits":     [42, 38]
         }
       ]
     }
   }

.. list-table:: Response Fields
   :header-rows: 1
   :widths: 20 80

   * - Field
     - Description
   * - ``bucket_days``
     - The bucket width used (echoes the request value).
   * - ``buckets``
     - Ordered list of bucket start timestamps. Shared across all modules.
   * - ``modules``
     - One entry per module. Each metric is an array aligned to ``buckets``; ``null`` at a position means no data exists for that module in that bucket.
   * - ``complexity``
     - Average cognitive complexity per bucket.
   * - ``loc``
     - Total lines of code per bucket (latest snapshot per file within bucket).
   * - ``silo_ratio``
     - Percentage of silo files per bucket (ownership ≥ 80 %).
   * - ``commits``
     - Distinct commit count per bucket.

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

Quality & Risk
--------------

Hotspot Analysis (Age & Churn)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Identifies "Hotspots" based on the intersection of high churn and file age.

*   **URL:** ``/v1/analyze/hotspots/churnage``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "from": "2023-01-01T00:00:00",
     "to": "2023-12-31T23:59:59",
     "module": "optional_module_name",
     "nbr_items": 50
   }

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "file_path": "src/core/logic.py",
         "age_days": 450,
         "churn": 1200,
         "hotspot_score": 0.89
       }
     ]
   }

Hotspot Analysis (Complexity & Churn)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Identifies hotspots by combining cognitive complexity with churn metrics.

*   **URL:** ``/v1/analyze/hotspots/complexity``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "start_date": "2023-01-01T00:00:00",
     "end_date": "2023-12-31T23:59:59",
     "component_name": "optional_module_name"
   }

**Response:**

.. code-block:: json

   [
     {
       "file_path": "src/complex_logic.py",
       "complexity": 150,
       "churn": 2500,
       "hotspot_score": 0.85
     }
   ]

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

Structure & Logic
-----------------

Combined Complexity (Files)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns complexity metrics (Cyclomatic, Cognitive, Efforts, LOC) combined with a trend indicator.

*   **URL:** ``/v1/analysis/complexity/combined``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "start_date": "2023-01-01T00:00:00",
     "end_date": "2023-12-31T23:59:59",
     "module_name": "optional_module_name"
   }

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "file_path": "src/main.py",
         "cognitive": 12,
         "cyclomatic": 8,
         "loc": 150,
         "efforts": 450.5,
         "trend_indicator": 2.0
       }
     ]
   }

Combined Complexity (Modules)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns aggregated complexity metrics for modules.

*   **URL:** ``/v1/analysis/complexity/modules``
*   **Method:** ``POST``
*   **Request Body:** Same as *Combined Complexity (Files)*.

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "file_path": "src/core/",
         "cognitive": 120,
         "cyclomatic": 85,
         "loc": 5240,
         "efforts": 12500.0,
         "trend_indicator": 1.5
       }
     ]
   }

Complexity Trend History
~~~~~~~~~~~~~~~~~~~~~~~~
Returns the historical complexity trend for a specific file.

*   **URL:** ``/v1/analyze/hotspots/complexity/trend``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "file_path": "src/core/service.py",
     "module_name": null,
     "start_date": "2023-01-01T00:00:00",
     "end_date": "2023-12-31T23:59:59"
   }

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "author_date": "2023-01-15T10:00:00",
         "complexity": 15,
         "cognitive": 12,
         "efforts": 450.0,
         "loc": 120,
         "commit_churn": 25
       }
     ]
   }

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

Team & Knowledge
----------------

Code Ownership (Files)
~~~~~~~~~~~~~~~~~~~~~~
Returns the number of distinct authors per file and identifies the main contributor.

*   **URL:** ``/v1/analysis/contributors/files``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "start_date": "2023-01-01T00:00:00",
     "end_date": "2023-12-31T23:59:59",
     "module_name": "optional_module_name"
   }

Code Ownership (Modules)
~~~~~~~~~~~~~~~~~~~~~~~~
Returns ownership statistics aggregated by module.

*   **URL:** ``/v1/analysis/contributors/modules``
*   **Method:** ``POST``
*   **Request Body:** Same as *Code Ownership (Files)*.

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "module_name": "src/api/",
         "author_count": 8,
         "main_contributor": "Jane Smith"
       }
     ]
   }

Knowledge Silos (Files)
~~~~~~~~~~~~~~~~~~~~~~~
Returns all files classified as a knowledge silo — files where a single developer accounts for
at least ``silo_threshold`` (default 80 %) of all commits. Results are ordered by ownership
percentage descending.

*   **URL:** ``/v1/analysis/silos/files``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "start_date": "2023-01-01T00:00:00",
     "end_date": "2023-12-31T23:59:59",
     "module_name": "optional_module_name",
     "silo_threshold": 0.80,
     "min_commits": 5
   }

.. list-table:: Request Parameters
   :header-rows: 1
   :widths: 20 10 70

   * - Parameter
     - Required
     - Description
   * - ``start_date``
     - No
     - ISO 8601 timestamp. Only commits on or after this date are considered.
   * - ``end_date``
     - No
     - ISO 8601 timestamp. Only commits on or before this date are considered.
   * - ``module_name``
     - No
     - Restrict analysis to a specific component name.
   * - ``silo_threshold``
     - No
     - Fractional ownership threshold (0.5–1.0). A file is a silo when the top contributor meets or exceeds this value. Default: ``0.80``.
   * - ``min_commits``
     - No
     - Minimum total commits a file must have to be included. Filters out rarely touched files. Default: ``5``.

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "file_path": "src/core/engine.py",
         "component_name": "core",
         "silo_developer": "alice",
         "ownership_pct": 94.3,
         "total_commits": 87,
         "risk": "high"
       }
     ]
   }

.. list-table:: Response Fields
   :header-rows: 1
   :widths: 25 75

   * - Field
     - Description
   * - ``file_path``
     - Path to the silo file.
   * - ``component_name``
     - The architectural component this file belongs to (``null`` if unassigned).
   * - ``silo_developer``
     - The developer who holds sole knowledge of this file.
   * - ``ownership_pct``
     - Percentage of commits attributed to the silo developer (0–100).
   * - ``total_commits``
     - Total number of commits to this file within the filtered time window.
   * - ``risk``
     - Risk classification: ``low`` (80–89 %), ``medium`` (90–94 %), ``high`` (95–99 %), ``critical`` (100 %).

Knowledge Silos (Modules)
~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns the silo density for each component — the fraction of files within the module that are
knowledge silos — and identifies which developer is responsible for the most silos in that module.
Results are ordered by silo ratio descending.

*   **URL:** ``/v1/analysis/silos/modules``
*   **Method:** ``POST``
*   **Request Body:** Same as *Knowledge Silos (Files)*.

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "component_name": "core",
         "total_files": 24,
         "silo_files": 9,
         "silo_ratio": 0.375,
         "dominant_silo_developer": "alice",
         "risk": "medium"
       }
     ]
   }

.. list-table:: Response Fields
   :header-rows: 1
   :widths: 25 75

   * - Field
     - Description
   * - ``component_name``
     - Name of the architectural component.
   * - ``total_files``
     - Total number of distinct files active in the module within the time window.
   * - ``silo_files``
     - Number of files in the module that are classified as silos.
   * - ``silo_ratio``
     - Fraction of files that are silos (``silo_files / total_files``).
   * - ``dominant_silo_developer``
     - The developer responsible for the highest number of silos within this module.
   * - ``risk``
     - Risk derived from ``silo_ratio``: ``low`` (< 25 %), ``medium`` (25–49 %), ``high`` (50–74 %), ``critical`` (≥ 75 %).

Knowledge Silos (Developers)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns the silo footprint of each developer — how many files and modules they are the sole
knowledge holder of. Results are ordered by silo file count descending.

*   **URL:** ``/v1/analysis/silos/developers``
*   **Method:** ``POST``
*   **Request Body:** Same as *Knowledge Silos (Files)*.

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "developer": "alice",
         "silo_file_count": 14,
         "silo_module_count": 3,
         "avg_ownership_pct": 91.7,
         "risk": "high"
       }
     ]
   }

.. list-table:: Response Fields
   :header-rows: 1
   :widths: 25 75

   * - Field
     - Description
   * - ``developer``
     - Developer name.
   * - ``silo_file_count``
     - Number of files for which this developer is the sole knowledge holder.
   * - ``silo_module_count``
     - Number of distinct components containing at least one of their silo files.
   * - ``avg_ownership_pct``
     - Average ownership percentage across all their silo files.
   * - ``risk``
     - Risk derived from ``silo_file_count``: ``low`` (1–2), ``medium`` (3–9), ``high`` (10–19), ``critical`` (≥ 20).

Module Ownership by Teams
~~~~~~~~~~~~~~~~~~~~~~~~~
Shows how much of each module is owned by different teams (Team-centric view).

*   **URL:** ``/v1/analysis/alignment/modules``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "start_date": "2023-01-01T00:00:00",
     "end_date": "2023-12-31T23:59:59",
     "component_name": "optional_module_name"
   }

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "team_name": "Frontend Team",
         "module_name_1": "UI Components",
         "ratio_1": 0.85,
         "module_name_2": "Icons",
         "ratio_2": 0.10,
         "module_name_3": "Tests",
         "ratio_3": 0.05,
         "health_status": "healthy"
       }
     ]
   }

Top Team Contributors
~~~~~~~~~~~~~~~~~~~~~
Shows the top 3 contributing teams for each module (Module-centric view).

*   **URL:** ``/v1/analysis/alignment/teams``
*   **Method:** ``POST``
*   **Request Body:** Same as *Module Ownership by Teams*.

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "component_name": "src/core/",
         "team_name_1": "Core Team",
         "ratio_1": 0.75,
         "team_name_2": "DevOps",
         "ratio_2": 0.20,
         "team_name_3": "Unassigned/Others",
         "ratio_3": 0.05,
         "health_status": "monopoly"
       }
     ]
   }

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

Dashboard KPIs
--------------

Lightweight aggregate endpoints that power the four KPI cards, the three sparkline
panels, and the warnings list on the overview dashboard. All computation happens in
the backend; the frontend receives pre-calculated values and renders them directly.

Project Summary
~~~~~~~~~~~~~~~
Returns the four headline metrics for the current period together with their
trend percentages compared to an explicit baseline period. Powers all four KPI cards.

*   **URL:** ``/v1/analysis/summary``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "start_date":          "2024-01-01T00:00:00",
     "end_date":            "2024-12-31T23:59:59",
     "baseline_start_date": "2023-01-01T00:00:00",
     "baseline_end_date":   "2023-12-31T23:59:59",
     "module_name": null
   }

.. list-table:: Request Parameters
   :header-rows: 1
   :widths: 25 10 65

   * - Parameter
     - Required
     - Description
   * - ``start_date``
     - Yes
     - Start of the current analysis period.
   * - ``end_date``
     - Yes
     - End of the current analysis period.
   * - ``baseline_start_date``
     - Yes
     - Start of the baseline period used for trend calculation.
   * - ``baseline_end_date``
     - Yes
     - End of the baseline period used for trend calculation.
   * - ``module_name``
     - No
     - Restrict analysis to a specific component.

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "total_commits":            1808,
         "total_commits_trend_pct":  12.5,
         "avg_file_age_days":         47,
         "avg_file_age_trend_pct":   -5.3,
         "avg_complexity":            23.4,
         "avg_complexity_trend_pct":  3.1,
         "silo_ratio_pct":            18.2,
         "silo_ratio_trend_pct":      1.4
       }
     ]
   }

.. list-table:: Response Fields
   :header-rows: 1
   :widths: 30 70

   * - Field
     - Description
   * - ``total_commits``
     - Total commit count in the current period.
   * - ``total_commits_trend_pct``
     - Signed percentage change vs. baseline (positive = more commits).
   * - ``avg_file_age_days``
     - Average file age in days across all files in the current period.
   * - ``avg_file_age_trend_pct``
     - Signed percentage change in average file age vs. baseline.
   * - ``avg_complexity``
     - Average cognitive complexity across all files.
   * - ``avg_complexity_trend_pct``
     - Signed percentage change in average complexity vs. baseline (positive = worse).
   * - ``silo_ratio_pct``
     - Percentage of files where a single developer owns ≥ 80 % of commits.
   * - ``silo_ratio_trend_pct``
     - Signed percentage change in silo ratio vs. baseline (positive = more silos).

Trends Overview
~~~~~~~~~~~~~~~
Returns time-bucketed trend series for complexity, LOC, silo ratio, and commit
activity. Powers the three sparkline panels on the overview dashboard.

*   **URL:** ``/v1/analysis/trends/overview``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "start_date":  "2024-01-01T00:00:00",
     "end_date":    "2024-12-31T23:59:59",
     "module_name": null,
     "bucket_days": 30
   }

.. list-table:: Request Parameters
   :header-rows: 1
   :widths: 20 10 70

   * - Parameter
     - Required
     - Description
   * - ``start_date``
     - No
     - Start of the analysis window; defaults to 12 months before ``end_date``.
   * - ``end_date``
     - No
     - End of the analysis window; defaults to now.
   * - ``module_name``
     - No
     - Restrict all series to a specific component.
   * - ``bucket_days``
     - No
     - Width of each time bucket in days. Default: ``30``.

**Response:**

.. code-block:: json

   {
     "bucket_days": 30,
     "complexity": [
       { "t": "2024-01-01T00:00:00", "value": 21.3 },
       { "t": "2024-02-01T00:00:00", "value": 22.1 }
     ],
     "loc": [
       { "t": "2024-01-01T00:00:00", "value": 142300.0 },
       { "t": "2024-02-01T00:00:00", "value": 148700.0 }
     ],
     "silo_ratio": [
       { "t": "2024-01-01T00:00:00", "value": 16.4 },
       { "t": "2024-02-01T00:00:00", "value": 17.1 }
     ],
     "commits": [
       { "t": "2024-01-01T00:00:00", "value": 142.0 },
       { "t": "2024-02-01T00:00:00", "value": 157.0 }
     ]
   }

All four series share identical ``t`` timestamps so they can be aligned on the
same x-axis in the frontend without further processing.

.. list-table:: Response Fields
   :header-rows: 1
   :widths: 20 80

   * - Field
     - Description
   * - ``bucket_days``
     - The bucket width used (echoes the request value).
   * - ``complexity``
     - Average cognitive complexity per bucket.
   * - ``loc``
     - Total lines of code per bucket (latest snapshot per file within bucket).
   * - ``silo_ratio``
     - Percentage of silo files per bucket (ownership ≥ 80 %).
   * - ``commits``
     - Total commit count per bucket.

Warnings
~~~~~~~~
Returns the top-N warnings ranked by severity then normalised risk score.
All warning types are derived exclusively from Git data — no external integrations
required. Powers the warnings list on the overview dashboard.

*   **URL:** ``/v1/analysis/warnings``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "start_date":  "2024-01-01T00:00:00",
     "end_date":    "2024-12-31T23:59:59",
     "module_name": null,
     "limit":       10
   }

.. list-table:: Request Parameters
   :header-rows: 1
   :widths: 20 10 70

   * - Parameter
     - Required
     - Description
   * - ``start_date``
     - Yes
     - Start of the analysis window.
   * - ``end_date``
     - Yes
     - End of the analysis window.
   * - ``module_name``
     - No
     - Restrict analysis to a specific component.
   * - ``limit``
     - No
     - Maximum number of warnings to return. Default: ``10``.

**Response:**

.. code-block:: json

   {
     "items": [
       {
         "module_name":  "PaymentService",
         "reason":       "critical_hotspot",
         "reason_label": "Critical Hotspot",
         "severity":     "critical",
         "metric_value": 94.0,
         "metric_unit":  "normalized_score"
       }
     ]
   }

.. list-table:: Warning Reason Codes
   :header-rows: 1
   :widths: 20 20 20 40

   * - ``reason``
     - ``reason_label``
     - ``metric_unit``
     - Description
   * - ``critical_hotspot``
     - Critical Hotspot
     - ``normalized_score``
     - Relative risk score 0–100 (``hotspot_score / max_hotspot_score × 100``). Critical ≥ 90, high ≥ 70. Score is relative to the worst module in the selected period, not an absolute threshold.
   * - ``silo_risk``
     - Knowledge Silo
     - ``ownership_pct``
     - File dominated by a single developer. Critical ≥ 95 %, high ≥ 80 %.
   * - ``complexity_spike``
     - Complexity Spike
     - ``trend_indicator``
     - Rapid complexity growth. Critical > 4.0×, high > 3.0×.
   * - ``churn_outlier``
     - Churn Outlier
     - ``lines_changed``
     - Absolute churn far above project average. Critical > 5× avg, high > 3× avg.
   * - ``legacy_reactivated``
     - Legacy Reactivated
     - ``days``
     - File dormant > 365 days that is now being heavily modified (churn > 2× avg). Always high.

Results are ordered by severity (``critical`` before ``high``) then by normalised
risk score descending.

Commit Count KPI
~~~~~~~~~~~~~~~~
Returns the total commit count together with a growth percentage for use as a
KPI indicator.

*   **URL:** ``/v1/analyze/commits/count``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "start_date":        "2024-01-01T00:00:00",
     "end_date":          "2024-12-31T23:59:59",
     "module_name":       null,
     "trend_window_days": 30
   }

**Response:**

.. code-block:: json

   {
     "total_commits": 1808,
     "growth_pct":    12.5
   }

.. list-table:: Response Fields
   :header-rows: 1
   :widths: 25 75

   * - Field
     - Description
   * - ``total_commits``
     - Total commit count within the requested period.
   * - ``growth_pct``
     - Signed percentage change vs. the same window shifted back by ``trend_window_days`` (positive = more commits).

Complexity Average KPI
~~~~~~~~~~~~~~~~~~~~~~
Returns the project-wide average cognitive complexity and its growth trend.
Files with zero cognitive complexity (e.g. non-code assets) are excluded.

*   **URL:** ``/v1/analysis/complexity/avg``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "start_date":        "2024-01-01T00:00:00",
     "end_date":          "2024-12-31T23:59:59",
     "module_name":       null,
     "trend_window_days": 30
   }

**Response:**

.. code-block:: json

   {
     "avg_cognitive": 23.4,
     "growth_pct":     3.1
   }

.. list-table:: Response Fields
   :header-rows: 1
   :widths: 25 75

   * - Field
     - Description
   * - ``avg_cognitive``
     - Average cognitive complexity across all files (latest value per file as of ``end_date``).
   * - ``growth_pct``
     - Signed percentage change vs. the window shifted back by ``trend_window_days`` (positive = complexity increased).

Silo Count KPI
~~~~~~~~~~~~~~
Returns the total number of silo files and its growth trend. Consistent with
the other silo endpoints — uses the same threshold and noise filters.

*   **URL:** ``/v1/analysis/silos/count``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "start_date":        "2024-01-01T00:00:00",
     "end_date":          "2024-12-31T23:59:59",
     "module_name":       null,
     "silo_threshold":    0.80,
     "min_commits":       5,
     "trend_window_days": 30
   }

All parameters are optional. Defaults: ``silo_threshold`` = ``0.80``,
``min_commits`` = ``5``, ``trend_window_days`` = ``30``.

**Response:**

.. code-block:: json

   {
     "silo_count": 14,
     "growth_pct":  7.7
   }

.. list-table:: Response Fields
   :header-rows: 1
   :widths: 25 75

   * - Field
     - Description
   * - ``silo_count``
     - Number of silo files in the requested period.
   * - ``growth_pct``
     - Signed percentage change vs. the window shifted back by ``trend_window_days`` (positive = more silos).

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

Configuration
-------------

Get Modules
~~~~~~~~~~~
Returns a list of all configured modules/components.

*   **URL:** ``/v1/config/modules``
*   **Method:** ``GET``

Average File Age KPI
~~~~~~~~~~~~~~~~~~~~
Returns the project-wide average file age and its growth trend.

*   **URL:** ``/v1/analyze/age/avg``
*   **Method:** ``POST``

**Request Body:**

.. code-block:: json

   {
     "start_date": "2024-01-01T00:00:00",
     "end_date": "2024-12-31T23:59:59",
     "module_name": null,
     "trend_window_days": 30
   }

**Response:**

.. code-block:: json

   {
     "avg_file_age_days": 47.5,
     "growth_pct": -5.3
   }

.. list-table:: Response Fields
   :header-rows: 1
   :widths: 25 75

   * - Field
     - Description
   * - ``avg_file_age_days``
     - Average file age in days across all files in the current period.
   * - ``growth_pct``
     - Signed percentage change vs. the baseline window shifted back by ``trend_window_days``.

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

Get Analysis Start Date
~~~~~~~~~~~~~~~~~~~~~~~
Returns the configured start date for the current analysis session.

*   **URL:** ``/v1/config/analysis-since``
*   **Method:** ``GET``

**Response:**

.. code-block:: json

   {
     "analysis_since": "2020-01-01T00:00:00"
   }


API Info
~~~~~~~~
Returns metadata about the currently running analysis session.

*   **URL:** ``/v1/info``
*   **Method:** ``GET``