fediversion/docs/BUGS_TRACKER_SPEC.md

Elmeg Bug Tracker Spec

Domain: bugs.elmeg.xyz
Style: Zendesk-inspired support portal
Date: 2023-12-23

---

Overview

A lightweight, self-hosted bug/feedback tracker with a clean, user-first interface. Users can submit issues, track status, and browse known issues. Admins can triage, respond, and resolve.

---

User-Facing Features

1. Submit a Report

• Type: Bug, Feature Request, Question, Other
• Title: Short description (required)
• Description: Rich text with markdown support
• Attachments: Screenshot upload (optional)
• Priority: (auto or user-selectable) Low, Medium, High, Critical
• Email: For anonymous users (logged-in users auto-fill)
• Environment: Auto-capture: Browser, OS, page URL

2. My Tickets

• View submitted tickets
• Track status: Open → In Progress → Resolved → Closed
• Add comments/updates to existing tickets
• Receive email notifications on updates

3. Knowledge Base / Known Issues

• Browse open bugs (public visibility toggle per ticket)
• Search functionality
• "Me too" upvote button
• FAQ section

4. Anonymous vs Authenticated

• Logged-in Elmeg users: auto-linked, no email required
• Anonymous: requires email for updates

---

Admin Features

Dashboard

• Ticket queue (filterable by status, type, priority, date)
• Unassigned tickets highlight
• Metrics: open count, avg response time, resolution rate

Ticket Management

• Assign to self or team member
• Internal notes (not visible to user)
• Public reply
• Change status, priority, type
• Merge duplicate tickets
• Mark as known issue (public)

Canned Responses

• Pre-written templates for common issues
• Variable substitution: {user_name}, {ticket_id}

---

Technical Architecture

Stack

• Frontend: Next.js (standalone app, shares Elmeg styling)
• Backend: FastAPI (can share auth with main Elmeg backend)
• Database: PostgreSQL (new schema in same db or separate)
• Storage: S3/local for attachments

Models

Ticket
├── id (uuid)
├── ticket_number (auto-increment display ID: ELM-001)
├── type (bug | feature | question | other)
├── status (open | in_progress | resolved | closed)
├── priority (low | medium | high | critical)
├── title
├── description
├── reporter_email
├── reporter_user_id (nullable, FK to elmeg user)
├── assigned_to (nullable, FK to admin user)
├── is_public (for known issues)
├── upvotes
├── environment (JSON: browser, os, url)
├── created_at
├── updated_at
├── resolved_at

TicketComment
├── id
├── ticket_id (FK)
├── author_id (FK)
├── author_email (for anonymous)
├── content
├── is_internal (admin-only visibility)
├── created_at

TicketAttachment
├── id
├── ticket_id (FK)
├── filename
├── url
├── created_at

CannedResponse
├── id
├── title
├── content
├── created_by

API Endpoints

Public:

• POST /tickets - Create ticket
• GET /tickets/{ticket_number} - View ticket (if public or owned)
• POST /tickets/{id}/comments - Add comment
• POST /tickets/{id}/upvote - Upvote known issue
• GET /known-issues - List public tickets

Authenticated (Elmeg user):

• GET /my-tickets - User's tickets

Admin:

• GET /admin/tickets - All tickets (filtered)
• PATCH /admin/tickets/{id} - Update status, assign, etc.
• POST /admin/tickets/{id}/internal-note - Add internal note
• GET /admin/canned-responses
• POST /admin/canned-responses

---

UI Pages

Route	Purpose
/	Landing: "How can we help?" + Submit form
/submit	Full bug report form
/my-tickets	User's submitted tickets
/ticket/[id]	Ticket detail + comments
/known-issues	Public bug list with search
/admin	Admin dashboard
/admin/ticket/[id]	Admin ticket view

---

Email Notifications

Event	Recipient
Ticket created	User (confirmation)
Admin replies	User
Status changed	User
User comment	Assigned admin

Uses existing AWS SES integration.

---

Deployment

Docker Compose (separate service)

services:
  bugs-frontend:
    build: ./bugs-frontend
    labels:
      - "traefik.http.routers.bugs.rule=Host(`bugs.elmeg.xyz`)"
      
  bugs-backend:
    build: ./bugs-backend
    environment:
      - DATABASE_URL=postgresql://...
      - ELMEG_API_URL=https://elmeg.xyz/api

DNS

Add A record or CNAME for bugs.elmeg.xyz → production server

Auth Integration

• Share JWT validation with main Elmeg backend
• Or standalone with optional Elmeg SSO

---

MVP Scope (Phase 1)

• Submit ticket form
• My tickets list
• Ticket detail with comments
• Admin ticket queue
• Email on ticket creation
• Basic styling matching Elmeg

Phase 2

• Known issues page
• Upvoting
• Canned responses
• Internal notes
• Attachment uploads
• Search

Phase 3

• Metrics dashboard
• Merge tickets
• Tags/labels
• Webhook integrations (Discord, Slack)

---

Estimated Effort

Phase	Effort
MVP	2-3 days
Phase 2	2 days
Phase 3	2 days

---

Next Steps

1. Create /srv/containers/elmeg-bugs directory structure
2. Initialize Next.js + FastAPI project
3. Set up Traefik routing for bugs.elmeg.xyz
4. Implement MVP models + endpoints
5. Deploy