# 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