# 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)

```yaml
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