Bug Reports Submission & SuperAdmin Review

Oktivo platform documentation for developers. Covers the in-app "Report a Bug" feature: how reports are submitted, stored, and reviewed by superadmins.

---

Overview

Any authenticated user can submit a bug report from the in-app "Report a Bug" panel. The report is stored in MongoDB, its attachments go to S3, an email notification is sent to the org owner, and superadmins can view and triage all reports across every organization from a dedicated dashboard page.

---

Submission (any authenticated user)

• UI: app/src/components/features/bug-report/BugReportPanel.tsx (opened via BugReportButton in the sidebar).
• Service: app/src/services/bugReport.service.ts → POST /bug-reports (multipart/form-data).
• Fields: summary, details, severity (critical|high|medium|low), auto-collected deviceInfo / browserInfo / pagePath, and up to 5 attachments (PNG/JPEG/GIF/WebP/MP4/WebM, max 5MB each).
• Backend: controllers/bug-report.controller.ts → submitBugReport
  • Validates required fields and severity.
  • Captures reporter identity (reporterEmail, reporterUserId, orgId) from the JWT.
  • Creates a BugReport with status: "open".
  • Uploads attachments to S3 at {orgId}/{customerId}/bugreport/{bugReportId}/{filename}.
  • Sends an email notification to the org owner (fire-and-forget).

---

Data model BugReport

models/BugReport.ts

Field	Type	Notes
summary	string	required
details	string	required
severity	critical | high | medium | low	default medium
status	open | in-progress | resolved | closed	default open
attachments	string[]	S3 keys
reporterEmail	string	from JWT
reporterUserId	string	from JWT
orgId	string	from JWT (orgUID)
deviceInfo / browserInfo / pagePath	string	client metadata
createdAt / updatedAt	Date	timestamps

---

SuperAdmin review

• UI: app/src/pages/superadmin/BugReportsPage.tsx reachable from the superadmin sidebar ("Bug Reports").
• Features:
  • Paginated table: date, summary, severity, status, organization, reporter.
  • Filters: status, severity, and text search (summary / details / email).
  • Row → detail dialog with full details, org details (name, slug, UID), reporter details (name, email, role, UID), environment info (page / device / browser), downloadable attachments (short-lived presigned URLs), and a status dropdown to triage.

API endpoints (superadmin only)

All are under /superadmin/* which already requires verifyJwt + requireRole("superadmin").

Method	Path	What it does
GET	/superadmin/bug-reports	Paginated list, enriched with org + reporter details. Query: page, limit, status, severity, orgId, search
GET	/superadmin/bug-reports/:id	Full report + presigned attachment URLs (10-min expiry)
PATCH	/superadmin/bug-reports/:id/status	Update triage status. Body: { status }

Enrichment (enrichBugReports) joins orgId → Organization (name/slug) and reporterUserId → User (name/email/role), falling back gracefully to the stored email/orgUID when a referenced record no longer exists. Raw S3 keys are never returned only presigned download URLs.

---

Code map

Backend (client_backend/src/)
├── models/BugReport.ts                     # schema (+ status field)
├── controllers/bug-report.controller.ts    # submitBugReport, listBugReports, getBugReport, updateBugReportStatus
├── services/
│   ├── bug-report-s3.service.ts            # attachment upload + S3 key builder
│   └── bug-report-email.service.ts         # org-owner notification email
├── routes/
│   ├── bug-report.routes.ts                # POST /bug-reports (any authed user)
│   └── superadmin.routes.ts                # GET/PATCH /superadmin/bug-reports*

Frontend (app/src/)
├── components/features/bug-report/         # BugReportPanel, BugReportButton, schema, uploader, metadata
├── services/bugReport.service.ts           # submit (customer)
├── services/superadmin.service.ts          # listBugReports, getBugReport, updateBugReportStatus
├── pages/superadmin/BugReportsPage.tsx     # superadmin review UI
├── layouts/SuperAdminLayout.tsx            # "Bug Reports" sidebar entry
└── routes.tsx                              # /superadmin/bug-reports route

---

Notes

• Submission was already working before the review UI existed; the change added the listing / detail / status endpoints and the superadmin page. Existing reports show up immediately.
• Attachment links are short-lived presigned URLs (10 minutes) generated on demand in getBugReport refresh the detail view to get new links.
• Reports from users whose org/user records were later deleted still display, using the stored reporterEmail and orgId as fallbacks.