API: Initial Diagnosis
=======================

Base URL: ``/diagnosis``

The initial diagnosis assesses co-design readiness through 12 structured
questions across 5 dimensions.

Endpoints
----------

Get Questions (Flat List)
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: http

   GET /diagnosis/questions

Returns all 12 diagnosis questions as a flat list.

**Response (200):**

.. code-block:: json

   [
     {
       "questionId": 1,
       "dimension": "Service Definition",
       "text": "What service are you co-designing?",
       "type": "text"
     },
     ...
   ]

Get Questions (Paginated by Dimension)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: http

   GET /diagnosis/questions/pages

Returns questions grouped into 5 pages (one per dimension).

**Response (200):**

.. code-block:: json

   [
     {
       "page": 1,
       "dimension": "Service Definition",
       "questions": [
         {"questionId": 1, "text": "What service...", "type": "text"},
         {"questionId": 2, "text": "Who are the...", "type": "text"}
       ]
     },
     {
       "page": 2,
       "dimension": "Stakeholder Awareness",
       "questions": [...]
     }
   ]

Submit Flash Diagnosis
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: http

   POST /diagnosis/flash/submit

Submit a standalone diagnosis (not attached to a project).

**Request Body:**

.. code-block:: json

   {
     "responses": [
       {"questionId": 1, "value": "Climate monitoring for agriculture"},
       {"questionId": 2, "value": "Yes, 5 stakeholders identified"},
       {"questionId": 3, "value": "Local authorities and farmers"},
       ...
     ]
   }

**Response (201):**

.. code-block:: json

   {
     "id": "uuid",
     "mode": "flash",
     "responses": [...],
     "llmSynthesis": "Based on your responses, your project shows strong stakeholder awareness but needs further technical definition...",
     "recommendations": "1. Define specific EO data sources\n2. Identify user personas\n3. Map existing solutions...",
     "createdAt": "2026-01-15T10:30:00Z"
   }

Convert Flash Diagnosis to Project
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: http

   POST /diagnosis/flash/{diagnosisId}/convert

Convert a completed flash diagnosis into a full co-design project.

**Request Body:**

.. code-block:: json

   {
     "name": "Climate Monitoring Service",
     "slug": "climate-monitoring",
     "description": "Based on diagnosis insights",
     "objectives": "monitor,predict",
     "domain": "climate",
     "organization": "Eurobios",
     "expertise": "Remote sensing",
     "serviceIdea": "Real-time crop monitoring"
   }

**Response (201):** Full project response (same as ``POST /projects``).

Diagnosis Modes
----------------

**Flash Mode:**
   Standalone discovery — user explores readiness before committing to a project.
   Can optionally be converted to a project later.

**Project Mode:**
   Integrated with a specific project — diagnosis is linked to the project and
   contributes to maturity assessment.

Dimensions
-----------

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

   * - #
     - Dimension
     - Focus
   * - 1
     - Service Definition
     - What service is being co-designed
   * - 2
     - Stakeholder Awareness
     - Identification of key actors
   * - 3
     - User Needs
     - Understanding of end-user needs
   * - 4
     - Technical Readiness
     - Technology stack clarity
   * - 5
     - Collaboration Setup
     - Methods and tools for collaboration