# TalkForm — AI Voice Interview Platform

A Typeform competitor where forms are built with structured questions but collected via an **AI voice interview**. The AI interviewer understands the schema and conducts a natural, conversational interview.

## Architecture

```
┌─────────────────┐     ┌─────────────────┐
│   Frontend      │     │   Backend       │
│   React + Vite  │────▶│   Express +     │
│   Port 5173     │     │   SQLite        │
│                 │     │   Port 3001     │
└─────────────────┘     └─────────────────┘
                                │
                        ┌───────┴───────┐
                        │   OpenAI API   │
                        │  (AI Voice)   │
                        └───────────────┘
```

## Project Structure

```
workspace/
├── backend/
│   ├── src/
│   │   ├── db.js              # SQLite database setup
│   │   ├── index.js           # Express server entry
│   │   └── routes/
│   │       ├── auth.js        # Registration, login, JWT
│   │       ├── forms.js       # CRUD for forms & questions
│   │       ├── responses.js   # Response collection
│   │       └── interview.js   # AI interview chat & extraction
│   ├── .env                   # Config (PORT, JWT_SECRET, OPENAI_API_KEY)
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── App.jsx            # Router setup
│   │   ├── index.css          # All styles
│   │   ├── main.jsx           # React entry
│   │   └── pages/
│   │       ├── Login.jsx      # Auth sign-in
│   │       ├── Register.jsx   # Auth register
│   │       ├── Dashboard.jsx  # List & create forms
│   │       ├── FormBuilder.jsx# Build structured forms
│   │       ├── Interview.jsx  # AI voice interview UI
│   │       └── Responses.jsx  # View collected responses
│   ├── index.html
│   ├── vite.config.js
│   └── package.json
└── README.md
```

## Setup & Running

### 1. Set your OpenAI API key

Edit `backend/.env`:

```
OPENAI_API_KEY=sk-your-real-key-here
```

### 2. Start the backend

```bash
cd backend
npm start
```

Backend runs on `http://localhost:3001`. Creates `talkform.db` automatically on first run.

### 3. Start the frontend

In a separate terminal:

```bash
cd frontend
npm run dev
```

Frontend runs on `http://localhost:5173`.

### 4. Open the app

- **Register** → create an account
- **Dashboard** → click "+ New Form" to create a form
- **Form Builder** → add structured questions (short text, rating, multiple choice, yes/no, etc.)
- **Interview Mode** → click the "Interview Mode" button (or share the link) to start an AI voice interview
- Inside the interview, **type or use the microphone button** 🎤 to speak your answers
- After the interview, answers are extracted and saved to the structured form

## Database

SQLite file at `backend/talkform.db`. Schema:

- `users` — accounts
- `forms` — form metadata
- `questions` — structured questions (type, label, required, options)
- `responses` — interview sessions
- `answers` — extracted answers linked to questions

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/auth/register` | Create account |
| POST | `/api/auth/login` | Sign in |
| GET | `/api/forms` | List user's forms |
| POST | `/api/forms` | Create form |
| GET | `/api/forms/:id` | Get form + questions |
| PUT | `/api/forms/:id` | Update form |
| DELETE | `/api/forms/:id` | Delete form |
| PUT | `/api/forms/:id/questions` | Batch save questions |
| GET | `/api/forms/public/:id` | Public form access |
| POST | `/api/responses/form/:id/start` | Start interview response |
| POST | `/api/responses/:id/answer` | Submit single answer |
| POST | `/api/responses/:id/complete` | Mark interview complete |
| GET | `/api/responses/:id` | Get response + answers |
| GET | `/api/responses/form/:id` | All responses for form |
| POST | `/api/interview/chat` | AI interview chat |
| POST | `/api/interview/extract` | Extract answers from conversation |

## How the AI Interview Works

1. The form's structured questions (with types, labels, options) are sent to OpenAI as a JSON schema
2. The AI receives a system prompt instructing it to act as a natural voice interviewer
3. The conversation history is sent with each request so the AI maintains context
4. When the interview concludes, a separate extraction call parses the conversation and saves structured answers
5. The frontend supports both text input and browser speech recognition (Web Speech API)