Quick Start
===========

This guide walks you through creating your first co-design project end-to-end,
from diagnosis to sustainability planning.

1. Start the Platform
---------------------

.. code-block:: bash

   cd codesign-backend
   docker compose up --build -d

   # Verify
   curl http://localhost:8000/health

2. Create a User
-----------------

Users are auto-created from JWT tokens on first API call. The backend extracts
user identity from the ``Authorization`` header (Bearer JWT) or the
``X-User-Id`` header.

.. code-block:: bash

   # Using X-User-Id header (development mode)
   curl -H "X-User-Id: user-001" \
        -H "X-User-Name: Alice" \
        http://localhost:8000/projects

3. Run the Initial Diagnosis
-----------------------------

Before creating a project, use the flash diagnosis to assess readiness:

.. code-block:: bash

   # Get diagnosis questions
   curl http://localhost:8000/diagnosis/questions/pages

   # Submit diagnosis responses
   curl -X POST http://localhost:8000/diagnosis/flash/submit \
     -H "Content-Type: application/json" \
     -H "X-User-Id: user-001" \
     -d '{
       "responses": [
         {"questionId": 1, "value": "Yes, we have identified stakeholders"},
         {"questionId": 2, "value": "Climate adaptation services"},
         ...
       ]
     }'

The platform returns an AI-synthesized analysis and recommendations.

4. Create a Project
--------------------

.. code-block:: bash

   curl -X POST http://localhost:8000/projects \
     -H "Content-Type: application/json" \
     -H "X-User-Id: user-001" \
     -H "X-User-Name: Alice" \
     -d '{
       "userId": "user-001",
       "name": "Climate Resilience EO Service",
       "slug": "climate-resilience",
       "description": "EO-based service for climate adaptation planning",
       "objectives": "monitor,predict,alert",
       "domain": "climate",
       "organization": "Eurobios",
       "expertise": "Remote sensing, Climate science",
       "serviceIdea": "Real-time climate risk assessment using satellite data"
     }'

This returns a project with:

- A unique ``id``
- An ``inviteCode`` for collaboration
- The creator as ``ADMIN``

5. Invite Collaborators
------------------------

Share the invite code with team members:

.. code-block:: bash

   # Get invite code (admin only)
   curl -H "X-User-Id: user-001" \
     http://localhost:8000/projects/{projectId}/invite

   # Another user joins
   curl -X POST http://localhost:8000/projects/join \
     -H "Content-Type: application/json" \
     -H "X-User-Id: user-002" \
     -d '{"code": "AB12CD34"}'

New members join with ``PENDING`` status until the admin approves.

6. Start the Chat Assistant
----------------------------

Create a chat thread to interact with the AI co-design coach:

.. code-block:: bash

   # Create a thread
   curl -X POST http://localhost:8000/projects/{projectId}/chat \
     -H "Content-Type: application/json" \
     -H "X-User-Id: user-001" \
     -d '{
       "project_context": {
         "projectId": "{projectId}",
         "projectName": "Climate Resilience EO Service"
       },
       "phase": 1
     }'

   # Send a message
   curl -X POST http://localhost:8000/projects/{projectId}/chat/{threadId}/messages \
     -H "Content-Type: application/json" \
     -H "X-User-Id: user-001" \
     -d '{
       "content": "Help me identify stakeholders for this climate service",
       "stream": false
     }'

The assistant provides guided help, suggests stakeholders, and can
auto-populate template forms.

7. Work Through the Phases
---------------------------

Use the chat assistant and API to progress through each phase:

**Phase 1 — Identification:**
   Create stakeholder ID cards, project ID cards, and the ecosystem matrix.

**Phase 2 — Data-Information-Value:**
   Build the DIV template with needs identification and user journey mapping.

**Phase 3 — User Research:**
   Capture user profiles, journeys, feedback, and integration challenges.

**Phase 4 — Outcomes & Sustainability:**
   Generate the outcomes diagram and sustainability canvas.

Each template can be created manually via the API or generated with AI
assistance through the chat interface.

Next Steps
----------

- :doc:`/howto/initialize-project` — Detailed project initialization guide
- :doc:`/howto/work-with-templates` — Working with co-design templates
- :doc:`/howto/use-chat-assistant` — Using the AI co-design coach