# Feedback Form — Design Document

> **Date:** 2026-02-18
> **Revised:** 2026-02-18 — added DB persistence, feedback type helper text, confirmation email, future TODO notes

## Overview

A feedback form page where logged-in users can submit bug reports, feature requests, and general feedback. Submissions are persisted to a `feedback` database table and emailed to a configurable address via the existing Resend infrastructure. A confirmation email is sent back to the submitter.

## Feedback Types

| Type | Helper Text |
|------|-------------|
| Bug Report | Something is broken or not working as expected |
| Feature Request | An idea for something new you'd like to see |
| Usability Issue | Something works but is confusing or hard to use |
| Documentation | Feedback on help docs, tooltips, or in-app guidance |
| General Feedback | Anything else — thoughts, impressions, suggestions |

## Email Format

### Admin Notification Email

**Subject:**
```
[ResolutionFlow Feedback] Bug Report — 2026-02-18 — ACC-7X3K
```

Where `ACC-7X3K` is the user's account display code.

**Body:**
```
Feedback Type: Bug Report
Submitted By: engineer@example.com
Account: Contoso IT Services (ACC-7X3K)
Date: February 18, 2026

---

User's written feedback text goes here...
```

Reply-to is set to the submitter's email for direct replies.

### Confirmation Email (to submitter)

**Subject:** `Thanks for your feedback — ResolutionFlow`

**Body:** Brief thank you, echoes back the feedback type and a preview of their message (first ~100 chars). Dark-themed HTML matching existing email templates.

Fire-and-forget: if this email fails, it's logged but doesn't affect the user's submission response.

## Database

### `feedback` table

| Column | Type | Notes |
|--------|------|-------|
| `id` | UUID | PK |
| `account_id` | UUID | FK to `accounts`, nullable, SET NULL on delete |
| `user_id` | UUID | FK to `users`, SET NULL on delete |
| `email` | String(255) | The reply-to email submitted |
| `feedback_type` | String(50) | Enum value |
| `message` | Text | Full feedback text |
| `created_at` | DateTime(tz) | Timestamp |

Indexes on `account_id`, `user_id`, `created_at`.

No admin view or API read endpoints — queryable directly in the DB when needed.

**Important:** DB write happens *before* email sending. Email failure does NOT prevent the feedback from being saved.

## Frontend

### Page

`FeedbackPage.tsx` — form page inside the app shell.

### Access Points

- Sidebar nav item (icon + "Feedback" label) — visible to all roles
- Link card on `AccountSettingsPage`

### Route

`/feedback` — top-level app shell route (not nested under `/account`).

### Form Fields

| Field | Details |
|-------|---------|
| Email | Auto-filled from logged-in user, editable |
| Feedback Type | Custom dropdown with description text per option |
| Message | Textarea, required, min 10 chars |
| Submit | `bg-gradient-brand`, disabled while submitting |

### UX Flow

1. Form loads with email pre-filled
2. User opens feedback type dropdown — sees label + helper description for each option
3. User selects type, writes message, submits
4. Button shows loading state during submission
5. On success: success message with confirmation email note, form resets
6. On error: inline error, form stays populated for retry

### Styling

Standard page layout — `container mx-auto`, `bg-card border border-border rounded-xl` form card, `max-w-2xl` width.

### API Client

`feedbackApi.submit()` in a new `api/feedback.ts` module.

## Backend

### Endpoint

`POST /feedback` in `endpoints/feedback.py`

### Schema

`FeedbackSubmission` in `schemas/feedback.py`:
- `email: EmailStr` — validated as email
- `feedback_type: FeedbackType` — enum-validated against the 5 types
- `message: str` — min 10 chars, max 5000 chars

### Auth

Requires `get_current_active_user`. Account display code pulled from user's account relationship server-side.

### Config

`FEEDBACK_EMAIL: Optional[str] = None` in `config.py`. Endpoint returns 503 if not configured.

### Email Service

Two new static methods on `EmailService`:
- `send_feedback_email()` — admin notification with reply-to
- `send_feedback_confirmation_email()` — thank-you to submitter (fire-and-forget)

Both use existing Resend client and dark-themed HTML matching existing email templates.

### Rate Limiting

One submission per minute per user.

## Future Consideration

**Post-session contextual feedback prompt** — do NOT build now. TODO comments in `FeedbackPage.tsx` and `endpoints/feedback.py` serve as breadcrumbs. Concept: after completing a troubleshooting session, show a subtle inline prompt that opens a lightweight version of the feedback form pre-tagged with tree/session context. The feedback infrastructure (DB table, email service, API endpoint) built here should be directly reusable.

## Not Included (YAGNI)

- No admin view for feedback
- No file attachments
- No public (unauthenticated) access