# domande.ch — Comprehensive AI Agent & Technical Developer Manual

Welcome to the full AI integration manual for **domande.ch**, a modern form builder and survey analytics platform powered by Next.js 15, Firebase Cloud Firestore, and Google Gemini AI.

---

## 1. System Architecture & Concepts

### Form Data Model
Each form in domande.ch consists of:
- `id`: string (e.g. `form_1723640000000_abc12`)
- `creatorId`: string (User ID of creator)
- `title`: string
- `description`: string (optional)
- `theme`: string (`neutral` | `indigo` | `emerald` | `amber` | `rose` | `sky`)
- `status`: string (`draft` | `published`)
- `createdAt`: ISO 8601 string
- `updatedAt`: ISO 8601 string
- `fields`: FieldObject[]

### Supported Field Types
1. `text`: Single-line text input.
2. `paragraph`: Multi-line text area.
3. `radio`: Single choice radio buttons (requires `options: string[]`).
4. `checkbox`: Multiple choice checkboxes (requires `options: string[]`).
5. `rating`: 1 to 5 star rating scale.
6. `dropdown`: Select dropdown menu (requires `options: string[]`).

Field Object Schema:
```json
{
  "id": "full_name",
  "type": "text",
  "label": "Nome Completo",
  "required": true,
  "placeholder": "Inserisci il tuo nome",
  "options": []
}
```

---

## 2. Authentication

API Requests to management endpoints require an API Key.
API Keys start with the prefix `dom_sk_`.

Authentication headers (either of the following):
- `Authorization: Bearer dom_sk_YOUR_API_KEY`
- `x-api-key: dom_sk_YOUR_API_KEY`

Unauthenticated users can read published forms (`GET /api/v1/forms/{formId}`) and submit answers (`POST /api/v1/forms/{formId}/submissions`).

---

## 3. Public REST API v1 Specification

### 3.1 Create Form
`POST /api/v1/forms`
Creates a form manually or generates it automatically from a natural language prompt via Gemini AI.

**Request Body (Manual):**
```json
{
  "title": "Sondaggio di Gradimento Evento",
  "description": "Dicci cosa ne pensi della conferenza",
  "theme": "indigo",
  "status": "published",
  "fields": [
    {
      "id": "rating_overall",
      "type": "rating",
      "label": "Valutazione complessiva",
      "required": true
    },
    {
      "id": "comments",
      "type": "paragraph",
      "label": "Suggerimenti per il futuro",
      "required": false
    }
  ]
}
```

**Request Body (AI Prompt):**
```json
{
  "prompt": "Crea un form per raccogliere feedback da studenti universitari dopo un esame, con domande sulla difficoltà e chiarezza",
  "status": "published"
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "message": "Modulo creato con successo",
  "form": {
    "id": "form_1739500000000_xy9z8",
    "title": "Feedback Esame Universitario",
    "description": "...",
    "status": "published",
    "theme": "indigo",
    "fields": [...]
  }
}
```

### 3.2 Get Form Details
`GET /api/v1/forms/{formId}`
Retrieves details and fields of a published form (or any form owned by authenticated user).

### 3.3 Update Form
`PATCH /api/v1/forms/{formId}`
Updates title, description, status, theme, or fields of a form owned by authenticated user.

### 3.4 Delete Form
`DELETE /api/v1/forms/{formId}`
Deletes a form owned by authenticated user.

### 3.5 Submit Form Response
`POST /api/v1/forms/{formId}/submissions`
Submits user answers to a published form. Does not require authentication.

**Request Body:**
```json
{
  "answers": {
    "rating_overall": 5,
    "comments": "Organizzazione eccellente!"
  }
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "message": "Risposta inviata con successo",
  "submissionId": "sub_1739500500000_k9m2p"
}
```

### 3.6 Read Submissions (Owner only)
`GET /api/v1/forms/{formId}/submissions`
Requires Authentication. Returns all submitted responses for the specified form.

---

## 4. Model Context Protocol (MCP) Server

**Endpoint**: `POST /api/mcp`
**Protocol**: JSON-RPC 2.0 over HTTP

### Available Tools:
1. `create_form`: Creates or AI-generates a form.
2. `list_forms`: Lists all forms owned by authenticated user.
3. `get_form`: Fetches full details for a form ID.
4. `update_form`: Updates form configuration or fields.
5. `delete_form`: Removes a form.
6. `get_submissions`: Fetches form responses.

**Example `tools/call` JSON-RPC payload:**
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "create_form",
    "arguments": {
      "prompt": "Modulo per registrazione webinar con nome, email e interesse principale",
      "status": "published"
    }
  },
  "id": 1
}
```

---

## 5. Client Integration Code Snippets

### Node.js / JavaScript Fetch
```javascript
async function createFormWithAI(promptText, apiKey) {
  const res = await fetch('https://domande.ch/api/v1/forms', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ prompt: promptText, status: 'published' })
  });
  const data = await res.json();
  return data.form;
}
```

### Python Requests
```python
import requests

def submit_answer(form_id, answers_dict):
    url = f"https://domande.ch/api/v1/forms/{form_id}/submissions"
    res = requests.post(url, json={"answers": answers_dict})
    return res.json()
```

---

## 6. Security Invariants
- Submissions are **write-only & immutable** for respondents. No public reading of others' answers (Zero PII Leak).
- Status Lock: Submissions are rejected for forms in `draft` status.
- Strict data sanitization on fields and options.