bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
aa36671e95
learning_ai_common_plat/dashboards/tracker-web/docs/PRD.md
root 930f97ff63 docs(tracker): move ROADMAP to docs/ + scaffold NoteLett-style structure 
Reorganises tracker-web docs to match the NoteLett + FlowMonk sibling-repo
convention. Old root ROADMAP.md replaced by full docs/ scaffold:

  docs/
  ├── ROADMAP.md                              (master phase tracker, v3)
  ├── PRD.md                                  (product requirements doc)
  ├── PRODUCTION_READINESS_HANDOFF_ROADMAP.md (adapted from NoteLett)
  ├── IMPLEMENTATION_TRACKER.md               (per-slice tracker w/ commit SHAs)
  └── roadmaps/
      ├── 00_MASTER_EXECUTION_PLAN.md
      └── 01_FOUNDATIONS_AND_DECISIONS.md

Incorporates production-readiness learnings from recent work in sibling
repos (May 22-23, 2026):

From learning_ai_notes:
- UI primitives migration via Primitives.tsx adapter (UI5-UI8 pattern)
- UI drift ratchet CI gate (one-way enforcement, hard-zero categories)
- Docker hardening: NEXT_PUBLIC bake-time, standalone static-chunks fix,
  corp-proxy build args, tarball-based docker-prep.sh
- Cosmos emulator smoke job for partition-key path coverage
- Live shared-service smoke (pnpm smoke:local)
- MEK rotation + secret-management runbooks
- React+React-DOM pnpm.overrides pin
- Backend domain events emission (item.created, status_changed, etc.)
- Workspace-path canonicalization

From learning_ai_flowmonk:
- @axe-core/playwright accessibility tests in CI
- E2E cleanup traps (prevent orphan resource accumulation)
- Playwright deployed-stack support (BASE_URL switch)
- IPv4 healthcheck (127.0.0.1, not localhost)
- Mobile palette centralization (theme/colors.ts)
- Release guards CI workflow
- Runtime replay preview pattern (for webhook event replay)

Adds 5 new bugs to known-issues table (B-019..B-023) for hardcoded
colors, direct ui imports, NEXT_PUBLIC runtime hardcoding, no mobile
layout, no i18n.

New Phase 6 expanded to cover mobile + a11y + i18n + theming.
Phase 4 expanded with cross-product routing + import wizard.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-25 11:28:55 +00:00

152 lines
9.0 KiB
Markdown
Raw Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink