bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
a8538db774
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

9.0 KiB
Raw Blame History

Tracker Dashboard — Product Requirements Document

Version: 1.0 Date: 2026-05-25 Status: Draft for implementation Related: docs/ROADMAP.md · docs/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