# Tracker Dashboard — Product Requirements Document

**Version:** 1.0
**Date:** 2026-05-25
**Status:** Draft for implementation
**Related:** [`docs/ROADMAP.md`](./ROADMAP.md) · [`docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md`](./PRODUCTION_READINESS_HANDOFF_ROADMAP.md)

---

## 1. Product Identity

| Field                     | Value                                                                |
| ------------------------- | -------------------------------------------------------------------- |
| **Product name**          | Tracker Dashboard                                                    |
| **Internal codename**     | `tracker-web`                                                        |
| **Canonical `productId`** | `tracker`                                                            |
| **Reserved port**         | `3003` (web) · proxied through `platform-service` `4003` for backend |
| **Public domain**         | `tracker.bytelyst.com` (deployed via Caddy)                          |
| **Token prefix**          | `--tk-*` CSS custom properties                                       |
| **Repo location**         | `learning_ai_common_plat/dashboards/tracker-web`                     |
| **Bundle identifier**     | n/a (web-only for v1; mobile in Phase 6)                             |

---

## 2. Vision

A **product-agnostic feature-request, bug-tracking, and roadmap dashboard** that serves every
ByteLyst product (ChronoMind, NoteLett, FlowMonk, NomGap, JarvisJr, LysnrAI, LocalMemGPT,
MindLyst, InvtTrdg, etc.) from one codebase, switching context via `x-product-id` header.

Item submissions must flow from **four equally first-class sources**:

1. **Public users** (no login) — via the public roadmap page
2. **Internal team / PMs / developers** — via the authenticated dashboard
3. **Coding agents** (Claude Code, Codex, Copilot Workspace, custom) — via the REST agent API
4. **External systems** — CI failures, Slack, email, GitHub/Gitea issues, webhooks

Every item carries the same shape regardless of source, with `source` field distinguishing origin.

---

## 3. Target Users

| Persona                     | Primary needs                                        | Main views                                           |
| --------------------------- | ---------------------------------------------------- | ---------------------------------------------------- |
| **Public user** 🌐          | Submit an idea, vote on others, see what's coming    | `/roadmap`, submission status page                   |
| **Internal contributor** 🏢 | Triage incoming, plan sprints, link work             | `/dashboard`, `/dashboard/items`, `/dashboard/board` |
| **PM / Admin** 🏢           | Set priorities, manage milestones, configure routing | All of internal + `/dashboard/settings`, analytics   |
| **Coding agent** 🤖         | Pull assigned items, claim, work, link PR, close     | `/api/agent/v1/*`                                    |
| **External system**         | Push events into tracker; pull state out             | `/api/webhooks/*`, outbound webhooks                 |

---

## 4. Non-Goals

- **Not a general-purpose project management tool** — focused on item tracking + roadmap, not full Kanban-style work-OS replacement
- **Not a code review tool** — links to PRs but does not replace GitHub/Gitea PR UI
- **Not a chat tool** — comments are async only; no real-time chat
- **Not a time-tracking-billing tool** — tracks hours for estimation accuracy, not invoicing
- **Not a CRM** — does not store customer relationships beyond reporter email

---

## 5. Core Concepts

### 5.1 Item

The atomic unit. Every bug, feature request, task, improvement, or chore is an **item** with:

- **Identity:** `id`, `productId`
- **Classification:** `type` (`bug` · `feature` · `task` · `improvement` · `chore`), `priority`, `labels`
- **State:** `status` (configurable workflow per product, default 5 statuses)
- **Provenance:** `source` (`internal` · `user_submitted` · `auto_detected`), `reportedBy`
- **Assignment:** `assignee` (user or agent ID)
- **Visibility:** `internal` vs `public`
- **Rich content:** `description` (markdown), acceptance criteria checklist, attachments
- **Relationships:** linked items, sub-tasks, milestone, PR links
- **Engagement:** `voteCount`, `commentCount`, watchers
- **Metadata:** `targetRelease`, `affectedVersion`, `fixedInVersion`, custom fields, agent `metadata` map
- **Audit:** `createdAt`, `updatedAt`, full activity log with actor + before/after

### 5.2 Comment

Thread of activity attached to an item. Markdown supported. Mentions trigger notifications.
Reactions allowed. Authors can edit within 15 min, admins delete any.

### 5.3 Vote

A signal that someone wants this item shipped. Anonymous (public) or attributed (logged-in).
Server-deduplicated per `(email, productId)` pair. Cap of N per email per product.

### 5.4 Milestone

A named grouping with a target date. Items can belong to one milestone. Release notes auto-generated
from closed items in a milestone.

### 5.5 PR Link

A reference to a GitHub or Gitea pull request. Updated by webhook on PR lifecycle events.
Multiple PRs can be linked to one item. PR status badges shown live on item detail.

### 5.6 Agent

A non-human actor with an API key. Identified by `name` and `role`. Subject to per-key rate limits
and product scope. Can claim items atomically to prevent races.

---

## 6. Success Metrics

| Metric                                                                                                  | Target                                                               |
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Items closed per sprint** (per product)                                                               | > baseline by Phase 3 ship                                           |
| **Time-to-first-response** on public submissions                                                        | < 24 h p95                                                           |
| **Agent-closed item ratio**                                                                             | > 30 % by Phase 5 ship                                               |
| **Spam submissions**                                                                                    | < 1 % of total (after Phase 1.4 Turnstile)                           |
| **Container health**                                                                                    | 100 % healthy for `tracker-web` + `platform-service` after Phase 1.1 |
| **Vitest coverage on `src/lib/`**                                                                       | ≥ 80 %                                                               |
| **WCAG 2.1 AA violations** in CI                                                                        | 0 (after Phase 6.2)                                                  |
| **UI drift counters** (hardcoded colors, legacy classes, direct `@bytelyst/ui` imports outside adapter) | 0 (after Phase 2.1)                                                  |

---

## 7. Constraints

- **Shared infrastructure** — must reuse `platform-service`, `valkey`, Cosmos DB; no new infra stack
- **Single VM deployment** — 4-core, 15 GB RAM shared with ~30 other containers; cannot dominate resources
- **Corp-network builds** — Gitea CI runner cannot reach public CDNs (fonts, Google APIs); use `@fontsource` + bundled assets
- **No external SaaS dependencies** for core flows — Cloudflare Turnstile and PostHog are opt-in; product must function without them
- **JWT secret shared** with `platform-service` — no separate auth subsystem

---

## 8. Open Questions

These need PM / stakeholder decisions before the relevant phase starts.

- **Q-001 (Phase 4.4):** When a CI-failure auto-item lands for `learning_ai_clock`, should it route to `tracker.productId = chronomind`, or to a generic `infrastructure` product? — affects auto-detection rules
- **Q-002 (Phase 5.1):** Agent productivity metrics — do we expose per-agent leaderboards to humans, or only aggregate?
- **Q-003 (Phase 6.1):** Mobile parity — full feature set on phone, or read-mostly with limited create/edit?
- **Q-004 (Phase 3.6):** AI auto-triage — automatic application of LLM suggestions, or always human-confirm?
- **Q-005 (Phase 4.2):** Email-to-tracker — use SendGrid / Postmark inbound, or self-host with Postfix?

---

## 9. Glossary

- **`productId`** — Canonical short string for a product (`chronomind`, `notelett`, `flowmonk`, etc.); used as Cosmos partition key and `x-product-id` header
- **MEK** — Master Encryption Key for field-level encryption of sensitive data (NoteLett pattern)
- **UI drift ratchet** — One-way CI gate that ensures count of legacy patterns (hardcoded colors, direct imports) can only decrease, never increase
- **Primitives adapter** — `src/components/ui/Primitives.tsx` that re-exports `@bytelyst/ui` components, providing a single insertion point for design-token theming
