bytelyst/learning_ai_notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
2a9f49048d
learning_ai_notes/docs/ROADMAP.md
saravanakumardb1 042cace2f3 docs(notes): record workspace progress
2026-03-10 17:55:14 -07:00

20 KiB
Raw Blame History

ByteLyst Agentic Notes — Master Roadmap

Version: 2.0 Date: March 10, 2026 Status: Draft Companion Docs: docs/PRD.md

1. Purpose

This is the master execution tracker for the notes platform.

Use this document to:

  • track phase status,
  • understand sequencing and dependencies,
  • assign workstreams to coding agents,
  • link out to smaller roadmap documents with focused execution detail.

Detailed implementation plans live under docs/roadmaps/.

Status Legend

  • Scaffolded — package/app/module structure exists and boots.
  • Mock-backed — UI/workflow exists but currently runs on mock or fallback data.
  • Local-only — behavior exists in client/local state without real backend persistence.
  • Integrated — wired to the intended backend/platform dependency.
  • Verified — exercised by build, typecheck, tests, or smoke checks.

2. Confirmed Stack

  • Web

    • Next.js 16
    • React 19
    • TypeScript

  • Backend

    • Fastify 5
    • TypeScript ESM
    • Zod

  • Mobile MVP

    • React Native + Expo

  • Shared Services

    • platform-service
    • extraction-service
    • mcp-server

3. Roadmap Document Index

  • docs/roadmaps/00_MASTER_EXECUTION_PLAN.md
  • docs/roadmaps/01_FOUNDATIONS_AND_DECISIONS.md
  • docs/roadmaps/02_BACKEND_ROADMAP.md
  • docs/roadmaps/03_WEB_ROADMAP.md
  • docs/roadmaps/04_MOBILE_ROADMAP.md
  • docs/roadmaps/05_MCP_AGENT_ROADMAP.md
  • docs/roadmaps/06_PLATFORM_INTEGRATIONS_ROADMAP.md
  • docs/roadmaps/07_QA_RELEASE_DOCS_ROADMAP.md

4. Master Phase Tracker

Phase 0 — Foundations and Decisions

Goals

  • finalize product identity and product manifest inputs
  • choose the single MVP mobile path
  • define repo structure and ownership boundaries
  • define initial domain objects and module boundaries
  • lock reuse strategy against the ByteLyst workspace

Checklist

  • product name finalized
  • productId finalized
  • backend port assigned
  • domain / bundle identifiers assigned
  • token namespace requested
  • mobile path confirmed as React Native MVP
  • repo folder structure finalized
  • initial Cosmos container strategy defined
  • operator vs shared admin boundary defined
  • PRD and roadmap aligned

Owner Docs

  • docs/roadmaps/00_MASTER_EXECUTION_PLAN.md
  • docs/roadmaps/01_FOUNDATIONS_AND_DECISIONS.md

Phase 1 — Core Product Skeleton

Goals

  • stand up web, backend, and mobile skeletons
  • complete auth, app shells, and first persistence layer
  • establish notes/workspaces as end-to-end vertical slices

Checklist

  • web app boots with authenticated shell
  • backend boots with health and first modules
  • mobile app boots with auth and navigation shell
  • notes CRUD works end-to-end
  • workspaces CRUD works end-to-end
  • first telemetry events are flowing

Owner Docs

  • docs/roadmaps/02_BACKEND_ROADMAP.md
  • docs/roadmaps/03_WEB_ROADMAP.md
  • docs/roadmaps/04_MOBILE_ROADMAP.md
  • docs/roadmaps/06_PLATFORM_INTEGRATIONS_ROADMAP.md

Phase 2 — Notes Product MVP

Goals

  • complete human-facing notes product MVP
  • add relationships, tasks, artifacts, and useful mobile parity
  • harden auditability for meaningful write paths

Checklist

  • note CRUD complete
  • workspace switching and permissions work
  • note relationships work
  • tasks can be extracted and linked
  • artifact upload/download works
  • mobile quick capture and retrieval are functional
  • audit log exists for important write paths

Owner Docs

  • docs/roadmaps/02_BACKEND_ROADMAP.md
  • docs/roadmaps/03_WEB_ROADMAP.md
  • docs/roadmaps/04_MOBILE_ROADMAP.md
  • docs/roadmaps/06_PLATFORM_INTEGRATIONS_ROADMAP.md
  • docs/roadmaps/07_QA_RELEASE_DOCS_ROADMAP.md

Phase 3 — Agentic Layer

Goals

  • ship safe MCP tools
  • add approval and audit workflows
  • support AI-assisted and AI-mediated knowledge flows

Checklist

  • core MCP tools work end-to-end
  • agent write paths support approval where required
  • audit and review UX is functional
  • extraction-backed workflows have fallback behavior
  • operator workflows are documented

Owner Docs

  • docs/roadmaps/05_MCP_AGENT_ROADMAP.md
  • docs/roadmaps/02_BACKEND_ROADMAP.md
  • docs/roadmaps/03_WEB_ROADMAP.md
  • docs/roadmaps/07_QA_RELEASE_DOCS_ROADMAP.md

Phase 4 — Search and Knowledge Acceleration

Goals

  • make search, retrieval, and context navigation genuinely strong
  • support scalable knowledge workflows for humans and agents

Checklist

  • search is fast and useful
  • linked-note navigation is meaningful
  • retrieval is scoped and explainable
  • search telemetry is measurable
  • web UX supports dense knowledge usage

Owner Docs

  • docs/roadmaps/02_BACKEND_ROADMAP.md
  • docs/roadmaps/03_WEB_ROADMAP.md
  • docs/roadmaps/04_MOBILE_ROADMAP.md
  • docs/roadmaps/05_MCP_AGENT_ROADMAP.md
  • docs/roadmaps/06_PLATFORM_INTEGRATIONS_ROADMAP.md

Phase 5 — Production Readiness and Release

Goals

  • ensure builds, tests, release flows, and runbooks are stable
  • prepare the repo for continued multi-agent execution

Checklist

  • build/test/release flows documented
  • core smoke tests pass on all chosen surfaces
  • production-readiness checklist passes
  • deferred list documented
  • roadmap status updated after implementation

Owner Docs

  • docs/roadmaps/07_QA_RELEASE_DOCS_ROADMAP.md
  • all workstream docs

5. Parallelization Rules

Safe Parallel Tracks After Phase 0

  • Agent 1

    • backend core modules

  • Agent 2

    • web shell and notes/workspace routes

  • Agent 3

    • mobile shell and quick capture flows

  • Agent 4

    • MCP tool schemas and read-only tools

  • Agent 5

    • platform integrations, telemetry, diagnostics, extraction wiring

  • Agent 6

    • QA docs, smoke plans, release-readiness docs

High-Collision Areas

  • shared product config files
  • root package/dependency manifests
  • shared route registration
  • top-level navigation/layout files
  • shared token/theme entrypoints
  • shared auth setup

Merge Order

  • foundations
  • backend core modules
  • web shell and CRUD flows
  • mobile shell and core flows
  • MCP core tools
  • integrations and enrichments
  • QA hardening and release docs

6. Suggested First Sprint

  • finalize product identity and mobile path
  • scaffold web/, mobile/, and backend/
  • implement backend notes and workspaces
  • build web authenticated shell and note list/detail pages
  • build mobile shell and quick capture
  • define MCP tool schemas for list/get/search/create-draft
  • wire telemetry, diagnostics, and extraction clients

7. Definition of Done

  • web app supports real end-to-end note workflows
  • mobile app supports meaningful capture/retrieval for MVP
  • backend modules are tested and production-shaped
  • MCP tools exist for core note workflows
  • shared platform integrations are stable
  • roadmap, PRD, and build/test commands are aligned
  • release readiness is documented and repeatable

8. Progress Notes

  • 2026-03-10 — Web workstream materially advanced:
    • learning_ai_notes/web/ was scaffolded from scratch
    • authenticated shell and core route surfaces now exist
    • dashboard, workspaces, note detail, search, settings, and error states now mix backend-backed data with a smaller set of still-derived operator/saved-view summaries
    • the web roadmap is now tracking real implementation state instead of draft-only planning
  • 2026-03-10 — Backend workstream materially advanced:
    • learning_ai_notes/backend/ was scaffolded from scratch
    • Fastify 5 + TypeScript ESM service bootstrap now exists with shared @bytelyst/* package wiring
    • /health and readiness-capable service bootstrap were added via @bytelyst/fastify-core
    • notes, workspaces, note-relationships, note-tasks, note-artifacts, and note-agent-actions modules now exist with schemas, repositories, routes, and starter tests
    • explicit /notes/search support now exists in the backend
    • product bootstrap identity currently uses provisional values pending final product naming and manifest alignment
  • 2026-03-10 — Web/backend verification materially advanced:
    • web/ dependencies are now installed
    • web npm run typecheck passes
    • web npm run build passes after fixing the auth BaseUser shape and guarding demo session init from server-side localStorage
    • backend/ dependencies are now installed
    • backend npm run typecheck passes after normalizing Fastify type boundaries for file: workspace deps
    • backend npm test passes after fixing hoisted Vitest mock patterns and stale route registration count assertions, though the current route tests are still mostly registration-focused rather than deep API-behavior coverage
  • 2026-03-10 — Web operator/search density materially advanced:
    • saved views are now represented across dashboard, workspaces, and search
    • search results now expose a denser operational layout with status, owner, and workspace metadata
    • operator workflow summary surfaces now exist on dashboard and reviews
    • workspace cards now expose ownership context for denser navigation
    • web/ verification passed again after wiring the richer saved-view/search/operator workflow slice (npm run typecheck, npm test, npm run build)
  • 2026-03-10 — MCP design work materially advanced:
    • product-side MCP core tool contracts now exist under backend/src/mcp/
    • namespace, role gating, read-only vs mutating classification, workspace scoping, and dry-run/idempotency/correlation expectations are now encoded for the first core tool set
  • 2026-03-10 — MCP execution and registration materially advanced:
    • product-side executable note MCP tools now exist for list/get/search/create-draft
    • the mutating create-draft path now records a note-agent-actions audit/proposal document
    • product-side MCP note tools now export through a registration adapter compatible with the shared mcp-server tool model
    • backend typecheck passes and backend tests pass with MCP execution coverage included
  • 2026-03-10 — Mobile workstream materially advanced:
    • learning_ai_notes/mobile/ was scaffolded from scratch
    • Expo + TypeScript root config and Expo Router entrypoints now exist
    • auth shell, tab navigation, home/recent notes, search, quick capture, inbox, and note detail surfaces now exist
    • shared mobile wiring now exists for auth, platform client, offline queue, token-based theme usage, and first-pass Zustand stores
    • mobile currently uses provisional product config values, but quick capture and note retrieval/edit flows are now wired to the product backend for the core note/workspace slice
  • 2026-03-10 — Mobile utility materially advanced:
    • home/search/capture are workspace-aware, and home exposes a retrieval summary surface
    • capture exposes offline queue readiness details for the scaffold
    • note detail supports lightweight backend-backed editing, artifact summary, and first-pass loading polish
    • inbox supports simple approval/reject flows plus a lightweight activity feed
  • 2026-03-10 — Real note/workspace vertical slice materially advanced (5995b6c):
    • mobile quick capture now persists notes to the product backend instead of saving local-only drafts
    • mobile note editing continues to flow through backend note update endpoints for persisted notes
    • web dashboard, workspaces, search, and reviews now derive their operator/saved-view side panels from live note/workspace/review data instead of static mock fixtures
    • web note detail now hydrates linked notes from the backend note-relationships endpoint with graceful fallback when relationship data is unavailable
    • verification passed for this slice with:
      • web npm run typecheck
      • web npm test
      • mobile npm run typecheck
  • 2026-03-10 — Mobile approval/activity integration materially advanced (8f14698):
    • mobile inbox approvals now hydrate from backend note-agent-actions instead of seeded local Zustand data
    • mobile approve/reject actions now persist proposal state back through the backend review route
    • mobile activity feed now derives from real backend agent-action history across workspaces
    • verification passed for this slice with:
      • mobile npm run typecheck
  • 2026-03-10 — Mobile note detail truthfulness improved (2a93b5b):
    • the mobile note detail screen now reflects persisted note status, workspace, and last-updated state instead of scaffold-era hardcoded metadata
    • placeholder note-body copy was removed in favor of truthful empty-state messaging for real backend-backed notes
    • verification passed for this slice with:
      • mobile npm run typecheck
  • 2026-03-10 — Mobile capture workspace selection materially advanced (8e57799):
    • the mobile capture screen now exposes live workspace selection instead of relying on hidden active-workspace state
    • backend-backed note creation now reflects the workspace chosen directly from the capture surface
    • verification passed for this slice with:
      • mobile npm run typecheck
  • 2026-03-10 — Mobile all-workspace view materially advanced (7d23793):
    • the mobile home surface now supports returning to an explicit all-workspaces view instead of forcing the first hydrated workspace
    • mobile capture now requires an explicit workspace selection before save when no workspace is active
    • verification passed for this slice with:
      • mobile npm run typecheck
  • 2026-03-10 — Mobile review actions hardened (7a80094):
    • mobile approve/reject actions now disable while the backend update is in flight and expose per-item pending labels
    • the mobile review surface no longer leaves approve/reject open to duplicate taps during async state changes
    • verification passed for this slice with:
      • mobile npm run typecheck
  • 2026-03-10 — Active surface copy truthfulness improved (5458090):
    • active landing, workspace, note-detail, and 404 surfaces now describe the backend-backed product state instead of stale scaffold/placeholder wording
    • mobile note save now awaits the persisted update before exiting edit mode
    • verification passed for this slice with:
      • web npm run typecheck
      • mobile npm run typecheck
  • 2026-03-10 — Web review decisions materially advanced (1bb220b):
    • the web review surface now approves and rejects proposals through the backend note-agent-actions review route
    • proposal comparison cards now expose real approve/reject actions instead of read-only before/after scaffolding
    • the approval queue and timeline now update in-session after a review decision is applied
    • verification passed for this slice with:
      • web npm run typecheck
      • web npm test
  • 2026-03-10 — Web note editing materially advanced (cdc03e3):
    • the web note detail surface now saves title/body edits through the backend PATCH /notes/:id route
    • the note detail page now refreshes the live note state after save instead of leaving edits local-only in the form
    • the editor now exposes an explicit save action and saving state instead of passive editable fields
    • verification passed for this slice with:
      • web npm run typecheck
      • web npm test
  • 2026-03-10 — Web artifact creation materially advanced (ef82747):
    • the web note detail surface now creates artifact records through the backend note-artifacts route
    • artifact creation is no longer display-only; users can add artifact metadata directly from the note detail surface
    • newly created artifacts refresh into the live note detail state after creation
    • verification passed for this slice with:
      • web npm run typecheck
      • web npm test
  • 2026-03-10 — Web task creation materially advanced (c99390e):
    • the web note detail surface now creates manual note tasks through the backend note-tasks route
    • task review is no longer labeled as mock extraction; the task panel now supports backend-backed task creation
    • newly created tasks refresh into the live note detail state after creation
    • verification passed for this slice with:
      • web npm run typecheck
      • web npm test
  • 2026-03-10 — Web search integration materially advanced (4748ed3):
    • the web search page now queries the backend note search path instead of filtering a preloaded full note list client-side
    • the search surface now reflects backend lexical matching for title/body search while preserving saved search summaries
    • verification passed for this slice with:
      • web npm run typecheck
      • web npm test
  • 2026-03-10 — Workspace filtering materially advanced (ab15950):
    • the workspaces page filter input now actively filters workspace cards by workspace fields and note content instead of rendering as passive UI
    • verification passed for this slice with:
      • web npm run typecheck
      • web npm test
  • 2026-03-10 — Dashboard entrypoints materially advanced (9f2670c):
    • recent note activity cards on the dashboard now link directly into the backend-backed note detail surface instead of rendering as read-only summary cards
    • verification passed for this slice with:
      • web npm run typecheck
      • web npm test
  • 2026-03-10 — Dashboard saved views materially advanced (99484a5):
    • dashboard saved-view cards now navigate into real destinations instead of rendering as passive summary cards
    • the search surface now accepts seeded q query params so dashboard shortcuts can open directly into backend-backed filtered results
    • verification passed for this slice with:
      • web npm run typecheck
      • web npm test
  • 2026-03-10 — Sidebar navigation cleanup materially advanced (4376519):
    • the web sidebar no longer points primary navigation at a single hardcoded note record
    • verification passed for this slice with:
      • web npm run typecheck
      • web npm test
  • 2026-03-10 — Review queue selection materially advanced (5ce9401):
    • the web review surface now lets you choose which queued proposal is featured for review instead of forcing the first queue entry
    • verification passed for this slice with:
      • web npm run typecheck
      • web npm test
  • 2026-03-10 — Dashboard workflow entrypoints materially advanced (6222fda):
    • dashboard operator workflow cards now route into the corresponding operational surfaces instead of rendering as passive status summaries
    • verification passed for this slice with:
      • web npm run typecheck
      • web npm test
  • 2026-03-10 — Review workflow entrypoints materially advanced (99bc7a9):
    • review-page operator workflow cards now route into the corresponding operational surface instead of rendering as passive summary cards
    • verification passed for this slice with:
      • web npm run typecheck
      • web npm test
  • 2026-03-10 — Saved search entrypoints materially advanced (88c11c2):
    • saved search cards on the search page now navigate into real seeded query states instead of rendering as passive summaries
    • verification passed for this slice with:
      • web npm run typecheck
      • web npm test
  • 2026-03-10 — Workspace saved-view entrypoints materially advanced (22df6d9):
    • workspace saved-view cards now navigate into real filter presets instead of rendering as passive summaries
    • verification passed for this slice with:
      • web npm run typecheck
      • web npm test
  • 2026-03-10 — Mobile verification materially advanced:
    • mobile dependencies now install successfully with corrected sibling @bytelyst/* package paths
    • npm run typecheck, npm run lint, and npm test now pass in learning_ai_notes/mobile/
    • token-backed placeholder and border colors replaced the remaining raw hardcoded mobile color fallbacks

9. Current Known Blockers / Deferrals

  • Blocker
    • Product identity and backend contract details are still not finalized in the planning docs, so the web app currently uses provisional config values and still derives some operator/saved-view summaries client-side.
  • Blocker
    • @bytelyst/react-native-platform-sdk is part of the intended mobile architecture, but the current workspace package does not appear ready for direct runtime consumption in this app yet.
  • Deferred
    • Complete real end-to-end CRUD wiring across every web/mobile surface
    • Blob-backed artifacts and upload/download flows
    • Fully integrated approval/review/audit UX across every surface
    • Persisted saved views, keyboard shortcut expansion, and deeper performance hardening