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

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.

# 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:

# 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

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:

# 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:

# 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

• /howto/initialize-project — Detailed project initialization guide

• /howto/work-with-templates — Working with co-design templates

• /howto/use-chat-assistant — Using the AI co-design coach