API: Templates
===============

Base URL: ``/projects/{projectId}/template``

Endpoints
----------

Create Template Instance
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: http

   POST /projects/{projectId}/template

**Request Body:**

.. code-block:: json

   {
     "instanceName": "European Space Agency",
     "templateCode": "1.0.1",
     "fields": {
       "formalInfo_name": "European Space Agency",
       "formalInfo_type": "Intergovernmental organization",
       "formalInfo_location": "Paris, France",
       "formalInfo_website": "https://www.esa.int"
     },
     "thread_id": "optional-thread-uuid"
   }

**Response (201):**

.. code-block:: json

   {
     "id": "uuid",
     "projectId": "project-uuid",
     "templateCode": "1.0.1",
     "instanceName": "European Space Agency",
     "instanceNumber": 1,
     "status": "in_progress",
     "completionPercentage": 35,
     "fields": { ... },
     "createdAt": "2026-01-15T10:30:00Z"
   }

Update Template Instance
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: http

   PUT /projects/{projectId}/template/{templateId}

**Request Body:**

.. code-block:: json

   {
     "fields": {
       "assessment_policy_score": 4,
       "assessment_policy_observations": "Strong regulatory alignment"
     }
   }

Generate Ecosystem Matrix
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: http

   POST /projects/{projectId}/template/ecosystem-matrix/generate

Generates or updates the ecosystem matrix by having the LLM evaluate all
stakeholder × project connections.

**Prerequisites:** At least 1 stakeholder OR 1 project card must exist.

**Response (200):**

.. code-block:: json

   {
     "id": "uuid",
     "templateCode": "1.0.3",
     "instanceName": "Ecosystem Matrix",
     "connections": [
       {
         "stakeholder_name": "ESA",
         "project_name": "Climate Monitor",
         "role": "Data Provider",
         "contribution": "Satellite imagery and EO expertise"
       }
     ]
   }

Generate Outcomes Diagram
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: http

   POST /projects/{projectId}/template/outcomes-diagram

AI-generated outcomes planning based on project context.

Generate Sustainability Canvas
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: http

   POST /projects/{projectId}/template/sustainability-canvas

AI-generated 6-dimensional sustainability analysis.

Template Codes Reference
-------------------------

.. list-table::
   :header-rows: 1

   * - Code
     - Phase
     - Template Name
     - Cardinality
   * - 1.0.1
     - 1
     - Stakeholder ID Card
     - Multiple
   * - 1.0.2
     - 1
     - Project ID Card
     - Multiple
   * - 1.0.3
     - 1
     - Ecosystem Matrix
     - Singleton
   * - 2.0.1
     - 2
     - Data-Information-Value (DIV)
     - Multiple
   * - 3.0.1
     - 3
     - User Profile
     - Multiple
   * - 3.0.2
     - 3
     - User Journey
     - Multiple
   * - 3.0.3
     - 3
     - User Needs Expansion
     - Multiple
   * - 3.0.4
     - 3
     - Integration Challenges
     - Multiple
   * - 3.0.5
     - 3
     - User Feedback Form
     - Multiple
   * - 3.0.6
     - 3
     - Facilitator Capture Sheet
     - Multiple
   * - 4.0.1
     - 4
     - Outcomes Diagram
     - Multiple
   * - 4.0.2
     - 4
     - Sustainability Canvas
     - Multiple

Field Naming Convention
------------------------

Template fields use a **flat naming convention** with underscore separators:

.. code-block:: text

   {category}_{subcategory}_{field}

Examples:

- ``formalInfo_name`` → Formal information > Name
- ``assessment_policy_score`` → Assessment > Policy > Score
- ``comprehensiveInfo_mainActivities`` → Comprehensive info > Main activities

This flat structure enables partial updates without nested object merging.