social-media/docs/FEATURES/product-feedback.md

Feature: Product Feedback

Status

Draft

Goal

Allow authenticated users to report bugs, suggestions, and requests from inside the app without interrupting their workflow, and give developers a lightweight place to review, discuss, and resolve that feedback.

This is product-level support data for the SaaS operator. It may capture workspace and page context for debugging, but it is not workspace-owned workflow data.

User Stories

• As an authenticated user, I want to submit feedback from any app page so that I can report a bug, suggestion, or request when I notice it.
• As an authenticated user, I want to optionally capture and annotate the current app viewport so that I can explain visual issues clearly.
• As an authenticated user, I want a global My Feedback page so that I can track my submitted feedback across all workspaces.
• As a developer, I want a global feedback review page so that I can see all submitted product feedback.
• As a developer, I want to comment, update status/type, and add tags so that feedback can be reviewed without turning the app into a ticketing system.
• As a reporter, I want notifications when a developer comments or changes status so that I know when feedback needs my attention.
• As a developer, I want notifications for new reports and reporter replies so that feedback does not stall silently.

Frontend Areas

• Global authenticated app shell floating Feedback button
• Feedback submission dialog
• Screenshot capture and annotation editor
• /app/my-feedback
• /app/my-feedback/:id
• /app/feedback
• /app/feedback/:id
• Existing notification bell
• frontend/src/features/feedback/

Backend Modules

• Identity
• Notifications
• Feedback
• Infrastructure blob storage

Access Rules

• Only authenticated users can submit feedback.
• Any authenticated user can submit feedback from any authenticated app page.
• A new Developer role can access the global developer feedback review pages and APIs.
• Developers can view every feedback report across the SaaS.
• Reporters can view only feedback they submitted.
• Feedback detail access is limited to the reporter and users with the Developer role.
• Feedback screenshot access must be authenticated and must follow the same reporter/developer access rules as the report.
• Feedback does not have public or shared links in v1.

Submission Rules

• The global Feedback button appears on every authenticated app page.
• Submitting feedback is intentionally user-initiated and non-intrusive.
• Feedback type is required and must be one of:
  • Bug
  • Suggestion
  • Request
• Description is required and plain text.
• Screenshot capture is optional.
• Users explicitly click Capture screen; opening feedback does not automatically capture the page.
• Capture is limited to the app viewport.
• If capture fails, the user can still submit text-only feedback.
• If a user closes a dirty feedback dialog, the app warns that unsent feedback will be discarded.
• Draft persistence is out of scope for v1.
• Reporters cannot edit or delete submitted feedback in v1.
• Reporters can add follow-up comments.

Screenshot And Annotation Rules

• Screenshots are uploaded through the blob storage abstraction, not embedded in feedback database rows.
• Feedback screenshots should use a dedicated storage area or prefix.
• Feedback screenshot records store blob container/path metadata and expose a protected API download path, not a public blob URL.
• Annotated captures are exported as compressed image files.
• Backend upload size and content type validation must be enforced.
• The UI must show a friendly error when an image is too large or invalid.
• Annotation tools should support:
  • crop
  • arrows
  • circles or ellipses
  • lines
  • freehand marks
  • text labels
  • undo
  • clear/reset
• Frontend implementation may use established capture and annotation libraries rather than custom screenshot tooling.
• Developers can preview and download/open the annotated screenshot.
• Reporters can preview the annotated screenshot.
• If feedback deletion is added in the future, associated screenshot blobs must be deleted with the report.
• Feedback reports and screenshots are retained indefinitely until a future retention/deletion feature exists.

Captured Metadata

Each report should capture useful debugging context automatically when available:

• reporter user id
• reporter name and email
• current app URL/path
• active workspace id/name
• active client id/name
• active campaign id/name
• active content item id/title
• browser user agent
• viewport size
• app version, if available
• created timestamp

Status Model

Feedback status is deliberately lightweight:

• New
• Planned
• Resolved
• Won't Do
• Cancelled

Status rules:

• New reports start as New.
• Developers can move reports to Planned, Resolved, or Won't Do.
• Developers can change a report type.
• Developers can add, remove, and update free-form tags.
• Tags are visible to reporters.
• Tag entry should suggest previously used tags.
• Reporters can cancel their own report with an optional plain-text reason.
• Cancelled is final in v1.
• Reporters cannot reopen resolved or cancelled feedback; they can add comments where comments remain allowed.
• Developer reason/comment on Won't Do is optional.
• No severity, priority, assignment, duplicate linking, or Jira-style workflow is included in v1.

Comments And Activity

• Feedback comments are visible to both the reporter and developers.
• Internal/private developer comments are out of scope for v1.
• Status/type/tag changes should be stored as activity history.
• Feedback detail should show a simple mixed timeline of comments and activity.
• Reporters can comment on their own feedback.
• Developers can comment on any feedback report.

Notifications

• New feedback report: notify all users with the Developer role.
• Developer comment: notify the reporter.
• Developer status change: notify the reporter.
• Developer type/tag changes do not notify the reporter.
• Reporter comment: notify developers who have previously commented on that report.
• Feedback notifications use the existing in-app notification system.
• The existing notification bell should show feedback notifications and open the relevant feedback detail page.
• Email notifications are out of scope for v1.
• My Feedback should show an unread indicator for reports with unread developer comments or status changes.

Developer Review Page

The developer review area is global, not workspace-scoped.

/app/feedback should support:

• list all reports by default, including final statuses
• filter by type
• filter by status
• filter by tag
• filter by reporter
• filter by workspace context
• filter by date range
• text search
• sort by newest
• sort by oldest
• sort by last activity

/app/feedback/:id should support:

• report details and captured metadata
• reporter identity details
• current URL/path link
• screenshot preview and developer download/open-original action
• comments
• activity timeline
• status updates
• type updates
• tag management with suggestions

Reporter Pages

/app/my-feedback is global across workspaces and should default to active reports:

• New
• Planned

The page should support:

• list own reports only
• filter by status
• filter by type
• sort by newest
• sort by last activity
• unread indicators
• open feedback detail
• view visible tags

/app/my-feedback/:id should support:

• report details
• current URL/path link
• screenshot preview
• visible tags
• comments
• activity timeline
• cancel with optional reason when status is not final

Localization

• User-facing feedback UI must be available in English and French.
• New strings belong in the existing locale files.

API And Data Expectations

• Backend code should follow the FastEndpoints module pattern under backend/src/Socialize.Api/Modules/Feedback.
• Feedback entities should be added to AppDbContext with explicit model configuration.
• The Developer role should be seeded with the existing identity role setup.
• Screenshot storage should use the existing IBlobStorage abstraction.
• Protected screenshot access may require a feedback-specific download endpoint instead of public static blob URLs.
• Backend contract changes require OpenAPI regeneration while the backend is running.

Out Of Scope For V1

• Public or unauthenticated feedback submission
• Shared feedback links
• Email notifications
• Draft saving
• Feedback deletion UI
• Automatic retention cleanup
• Severity or priority fields
• Assignment/owner workflow
• Duplicate linking
• Internal/private comments
• Workspace-owned exports or audit reports

Done When

• Authenticated users can open a global Feedback dialog from every app page.
• Users can submit feedback with required type and description.
• Users can optionally capture, annotate, and upload an app viewport screenshot.
• Feedback records capture debugging metadata when available.
• Reporters can view their own global My Feedback list and details.
• Developers with the Developer role can view all feedback in /app/feedback.
• Developers can update type, status, and tags.
• Reporters and developers can comment on feedback.
• Feedback activity history is shown with comments.
• Feedback notifications appear in the existing in-app notification system.
• Feedback screenshot access is authenticated and scoped to reporter/developer access.
• English and French UI strings are present.
• Backend build and tests pass.
• Frontend build passes.
• OpenAPI is updated after backend contracts are implemented.