learning_ai_notes/docs/PRD.md

Product Requirements Document: NoteLett

Version: 2.0 Date: March 10, 2026 Author: Product Team Status: Draft

1. Product Vision

NoteLett is a knowledge product for humans and AI agents to capture, structure, retrieve, and operationalize notes in a shared system of record.

This is not just a notes UI with an AI chat panel bolted on. It is a product-specific knowledge application that fits the existing ByteLyst ecosystem:

• Human users capture notes, tasks, ideas, research, and artifacts quickly.
• AI agents can read, create, update, enrich, summarize, classify, and connect knowledge through governed APIs and MCP tools.
• Shared platform capabilities come from learning_ai_common_plat.
• Product-specific knowledge behavior lives in this repo and its own backend/.

The goal is to create the canonical notes and knowledge layer for the ByteLyst workspace without violating the architectural boundaries already established across the other product repos.

1.1 Vision Statement

"A product-specific knowledge workspace where humans and AI agents collaborate on structured notes, with shared platform services underneath and agent tooling built in from day one."

1.2 Positioning

The product should sit between a traditional notes app and a pure developer platform:

• It must feel fast and approachable for human note-taking.
• It must expose structured, reliable primitives for agents.
• It must reuse the ByteLyst common platform instead of reinventing auth, billing, flags, telemetry, or admin capabilities.
• It must use the shared design system rather than inventing one-off tokens and UI patterns.

2. Why This Product Exists

2.1 Current Gap

Across the workspace, multiple products need a durable place for:

• research notes,
• project context,
• AI-generated artifacts,
• agent instructions,
• structured memory,
• workflow-linked documents,
• searchable operational knowledge.

Today, this type of information is fragmented across markdown docs, product-specific stores, chat logs, and ad hoc notes. That creates the following issues:

• Notes are too unstructured for reliable agent execution.
• Context is spread across repos and products.
• There is no product-specific knowledge backend for notes.
• Humans and agents do not share a consistent audit trail.
• Knowledge capture and retrieval patterns are inconsistent across products.

2.2 Product Opportunity

ByteLyst already has the ecosystem ingredients:

• shared auth, flags, billing, telemetry, blob, monitoring, and extraction capabilities in learning_ai_common_plat,
• proven web stacks in Next.js 16,
• proven product backend pattern in Fastify 5 + TypeScript,
• established cross-product design token infrastructure,
• an emerging agent workflow culture through Windsurf workflows, MCP, and structured docs.

This product should unify those ingredients into a notes system designed specifically for your workspace, not a generic “AI notes startup” architecture.

3. Product Principles

3.1 Principles

• Product-specific logic stays product-specific

  • Notes domain logic belongs in this repo and its own backend/.
  • Shared platform concerns belong in learning_ai_common_plat.

• Human-first UX, agent-first data model

  • The UI should feel clean and simple.
  • The underlying note objects should be structured, typed, auditable, and machine-friendly.

• MCP is additive, not an excuse for architectural drift

  • MCP should be a first-class integration surface.
  • REST APIs and internal services should remain explicit and testable.

• No design-system forks

  • Visual language must come from the shared ByteLyst design token system.
  • No hardcoded colors or isolated styling conventions.

• Single source of truth for knowledge

  • Notes, links, references, tasks, summaries, and agent actions should converge into a coherent model.

• Auditability by default

  • Every agent action should be attributable.
  • Human approvals and overrides must be explicit for sensitive flows.

4. Target Users

4.1 Human Users

Knowledge Worker

Needs:

• fast capture,
• lightweight editing,
• search and retrieval,
• AI-assisted organization,
• project and workspace views.

Builder / Developer

Needs:

• structured APIs,
• MCP tool support,
• workflow integration,
• import/export,
• predictable schemas,
• automation-friendly note primitives.

Team Lead / Operator

Needs:

• approval workflows,
• visibility into agent activity,
• audit history,
• shared team knowledge,
• operational dashboards.

4.2 AI Agent Users

Research Agent

Needs:

• note creation,
• citation attachment,
• structured summaries,
• source linking,
• deduplication.

Workflow Agent

Needs:

• task extraction,
• state transitions,
• action logs,
• human approval hooks,
• webhook/event subscriptions.

Assistant Agent

Needs:

• retrieval APIs,
• semantic and lexical search,
• scoped access,
• clean content blocks,
• metadata-rich note objects.

Integration Agent

Needs:

• stable CRUD APIs,
• bulk sync,
• idempotency,
• webhooks,
• external system mapping.

5. In-Scope Product Surface

5.1 Core Objects

The first release should support a focused set of domain objects:

• Note

  • title,
  • body,
  • rich content blocks,
  • tags,
  • links,
  • status,
  • source metadata,
  • timestamps,
  • createdBy / updatedBy,
  • agent attribution where applicable.

• Workspace

  • collaborative boundary for notes,
  • permissions,
  • views,
  • filters,
  • workflow ownership.

• Artifact

  • files, extracted documents, generated summaries, structured outputs, exports.

• Task / Action Item

  • extracted from notes or manually created,
  • linked back to source notes.

• Relationship

  • note-to-note,
  • note-to-task,
  • note-to-artifact,
  • note-to-external-entity.

• Agent Action Log

  • who acted,
  • why,
  • on which object,
  • before/after state summary,
  • approval state.

5.2 Core End-User Features

Release 1 should include:

• note creation and editing,
• workspace-level organization,
• tags and linked-note relationships,
• rich search,
• AI summarization and enrichment,
• task extraction from notes,
• note sharing within authorized workspace scope,
• import/export,
• agent-readable APIs,
• MCP tools for note operations,
• audit history for agent actions.

5.3 Explicitly Out of Scope for V1

• full multi-tenant enterprise admin suite,
• custom billing models unique to this product,
• separate tracker, billing, or growth microservices,
• bespoke design system,
• GraphQL-first architecture,
• generic “knowledge graph platform” ambitions that delay the useful notes product.

5.4 Delivery Strategy: Build the Whole Product by Reuse First

This product should be developed with a reuse-first strategy across web + mobile so the team can deliver the whole application in one coordinated push rather than rebuilding shared plumbing from scratch.

The guiding rule from the workspace should be:

• write only the code that is unique to the notes product,
• configure and compose the rest from existing ByteLyst assets.

The implementation should assume immediate leverage of:

• shared packages from learning_ai_common_plat,
• shared platform services,
• existing dashboard/UI primitives,
• existing mobile SDKs,
• existing MCP/A2A orchestration patterns,
• existing cross-platform sync, telemetry, diagnostics, auth, feature-flag, and feedback capabilities.

5.5 Platform Scope for Initial Launch

The product should be planned as a multi-surface launch, not a web-only afterthought:

• Web

  • primary authoring and operator experience,
  • fastest path to broad functionality,
  • main notes, workspace, search, agent, and admin surfaces.

• iOS

  • fast capture,
  • offline reading/editing where feasible,
  • notifications, share sheet, quick note capture.

• Android

  • parity for capture, retrieval, notifications, sync, and approvals.

• Optional React Native fallback path

  • if speed-to-MVP matters more than fully native differentiation, the team may choose React Native / Expo for mobile using the existing React Native platform SDK pattern.

The PRD should assume all three delivery paths are available in the workspace today, and the implementation plan can choose the best one based on speed and product differentiation.

To avoid scope drift, Phase 0 must make an explicit decision:

• Option A

  • web + fully native iOS + fully native Android

• Option B

  • web + React Native mobile

The team should not pursue both mobile tracks simultaneously for MVP.

Initial launch parity should also be tiered:

• Tier 1

  • web must carry the full authoring, search, workspace, agent, and operator experience

• Tier 2

  • mobile must prioritize capture, retrieval, notifications, approval actions, and lightweight editing

• Tier 3

  • advanced administration and dense knowledge-management workflows may remain web-primary at first release

6. Architecture Alignment With the Existing Workspace

6.1 Required Repo Pattern

This product should follow the same product-repo pattern already established elsewhere:

• This repo

  • product web app,
  • product backend,
  • product docs,
  • product-specific tests.

• learning_ai_common_plat

  • shared auth,
  • shared billing,
  • shared feature flags,
  • shared telemetry,
  • shared blob support,
  • shared extraction service,
  • shared logger, config, auth, api-client, cosmos, testing, and design-token packages.

The product should also follow the common workspace source-of-truth pattern:

• define a product manifest early,
• register product identity consistently,
• use repo/workspace conventions that align with .windsurf/workflows/repos.txt,
• treat WORKSPACE_INVENTORY.md, learning_ai_common_plat_INVENTORY.md, AGENTS.md, and ecosystem architecture docs as architectural source references during implementation.

6.2 Backend Ownership Rule

Product-specific APIs for notes must live in this repo’s backend/ directory.

Examples of product-specific backend modules:

• notes,
• workspaces,
• note-relationships,
• note-tasks,
• note-artifacts,
• note-sharing,
• note-search,
• note-agent-actions.

These must not be added to platform-service unless they are clearly product-agnostic.

6.3 Shared Service Usage

The product should consume the common platform for:

• authentication and identity,
• subscriptions and plans,
• feature flags,
• telemetry,
• blob upload/download,
• audit and monitoring infrastructure where shared,
• extraction workflows where product-appropriate.

The product should also explicitly leverage the following active service surfaces:

• platform-service

  • auth,
  • feature flags,
  • telemetry,
  • diagnostics,
  • jobs,
  • changelog,
  • feedback,
  • status,
  • webhooks,
  • plans/subscriptions,
  • exports,
  • broadcast/surveys where useful.

• extraction-service

  • summarization support,
  • entity extraction,
  • structured metadata enrichment,
  • note-to-task extraction,
  • async enrichment jobs where needed.

• mcp-server

  • MCP tool registry,
  • product tool exposure for notes operations,
  • A2A orchestration,
  • operator workflows,
  • structured agent execution paths with auditability and safety gating.

• ux-lab

  • rapid prototyping for high-density note UI,
  • operator flows,
  • MCP-assisted workflow UX experiments before productionizing.

It should also use the existing shared package conventions:

• @bytelyst/config
• @bytelyst/auth
• @bytelyst/api-client
• @bytelyst/cosmos
• @bytelyst/errors
• @bytelyst/logger
• @bytelyst/testing
• @bytelyst/design-tokens
• @bytelyst/platform-client
• @bytelyst/react-auth
• @bytelyst/telemetry-client
• @bytelyst/diagnostics-client
• @bytelyst/feature-flag-client
• @bytelyst/kill-switch-client
• @bytelyst/blob-client
• @bytelyst/offline-queue
• @bytelyst/sync
• @bytelyst/extraction
• @bytelyst/dashboard-components

6.4 Reuse Matrix for One-Shot Delivery

To maximize speed, the product should map each app concern to an existing ByteLyst capability before any new implementation begins.

Web App

• App shell

  • reuse existing Next.js 16 App Router patterns from ChronoMind, JarvisJr, and the dashboards.

• Auth

  • use @bytelyst/auth, @bytelyst/auth-client, and @bytelyst/react-auth patterns.

• API clients

  • use @bytelyst/api-client and @bytelyst/platform-client.

• Platform UX primitives

  • reuse @bytelyst/dashboard-components where possible for empty states, loading, table/list primitives, filters, and admin/operator surfaces.

• Operator boundary

  • product-specific operator tools may live in the product web app,
  • platform-wide administration should continue to live in shared dashboards such as admin-web rather than being reimplemented locally.

• Telemetry / diagnostics

  • use @bytelyst/telemetry-client and @bytelyst/diagnostics-client from day one.

• Sync / offline queue

  • use @bytelyst/offline-queue and @bytelyst/sync rather than inventing product-local sync infrastructure.

• Extraction / enrichment

  • call @bytelyst/extraction and extraction-service before introducing product-local AI pipelines.

iOS App

• Baseline

  • follow the SwiftUI + product-backend pattern already proven in ChronoMind, PeakPulse, and JarvisJr.

• Platform wiring

  • use @bytelyst/swift-platform-sdk.

• Capabilities to take from the SDK

  • auth,
  • telemetry,
  • feature flags,
  • sync,
  • blob upload,
  • kill switch,
  • diagnostics,
  • feedback,
  • surveys,
  • deep linking where needed.

• UI theming

  • copy the generated Swift theme pattern from existing products and rename to the notes product theme.

Android App

• Baseline

  • follow the Jetpack Compose + product-backend pattern already used in ChronoMind and MindLyst.

• Platform wiring

  • use @bytelyst/kotlin-platform-sdk.

• Capabilities to take from the SDK

  • auth,
  • telemetry,
  • feature flags,
  • sync,
  • blob upload,
  • kill switch,
  • diagnostics,
  • feedback,
  • broadcast/survey support,
  • deep linking.

React Native Alternative Path

• If the team decides the fastest route to mobile is shared JS rather than separate native apps, use the existing NomGap-style baseline:
  • React Native / Expo,
  • @bytelyst/react-native-platform-sdk,
  • @bytelyst/api-client,
  • @bytelyst/platform-client,
  • @bytelyst/offline-queue,
  • generated React Native design tokens.

This should be treated as a valid acceleration path, not a second-class option.

6.5 Preferred Technical Stack

To remain aligned with the workspace, the preferred stack is:

• Web

  • Next.js 16,
  • React 19,
  • App Router,
  • TypeScript strict mode.

• Backend

  • Fastify 5,
  • TypeScript ESM,
  • Zod validation,
  • module pattern: types.ts → repository.ts → routes.ts.

• Data

  • Azure Cosmos DB using the shared package patterns,
  • every document includes a product identity field once finalized for this product.

• Testing

  • Vitest for backend and pure TS modules,
  • product-specific verification commands documented in this repo.

6.6 Product Bootstrap Pattern

The fastest path to implementation should mirror the platform acceleration guidance already documented in the workspace:

• define a product manifest early,
• scaffold repo surfaces from existing product patterns,
• generate or template repetitive module structure where possible,
• use shared auth/dashboard/sync/mobile SDK primitives before writing custom infrastructure,
• reserve new code for notes-specific domain logic, editor UX, retrieval logic, and agent workflows.

This product should aim for an “8-hour MVP mindset” even if the full production build takes longer:

• platform capabilities are configured,
• product-specific capabilities are implemented.

The bootstrap phase should also define:

• canonical product name,
• canonical productId,
• domain/bundle identifiers,
• backend port,
• initial container list,
• token namespace,
• selected mobile implementation path.

7. Design System Requirements

7.1 Design System Source of Truth

This product must use the shared ByteLyst design token system from learning_ai_common_plat/packages/design-tokens/.

That means:

• no hardcoded hex colors,
• no isolated token system in this repo,
• no ad hoc component palette disconnected from the rest of the workspace.

7.2 Web Styling Direction

The web app should follow the same general direction already used in the workspace:

• CSS custom properties generated from shared tokens,
• product-specific token namespace once this product’s token set is defined,
• component styling that references shared token variables rather than raw color literals,
• consistent spacing, radius, typography, and semantic color usage.

7.3 Component Philosophy

UI should prioritize:

• dense but readable knowledge views,
• excellent keyboard navigation,
• calm visual hierarchy,
• agent activity visibility without clutter,
• consistent cards, filters, sidebars, editors, and metadata panels.

Key UI areas:

• workspace shell,
• note list,
• note editor,
• linked context panel,
• agent activity timeline,
• search results,
• import/export surfaces,
• approval queue for sensitive agent actions.

7.4 Cross-Platform Design Reuse

The implementation should explicitly leverage current design-system onboarding guidance:

• Web

  • import generated CSS tokens,
  • use CSS custom properties,
  • mirror the established dashboard and product web token patterns.

• iOS

  • copy the generated Swift theme file pattern used by existing products,
  • expose a product-specific theme wrapper for note UI components.

• Android

  • use the generated Kotlin token pattern already proven in the workspace.

• React Native

  • use generated React Native tokens if the RN path is chosen.

Validation should be part of the development workflow:

• run token validation scripts before commit,
• treat hardcoded colors as a design-system violation,
• define the new product token namespace in the shared token source as part of Phase 0.

8. Functional Requirements

8.1 Notes

Users and authorized agents can:

• create notes,
• update notes,
• archive notes,
• restore notes,
• tag notes,
• link notes,
• attach artifacts,
• generate summaries,
• generate structured metadata,
• extract tasks from note content.

8.2 Search and Retrieval

The product must support:

• lexical search,
• metadata filtering,
• tag filtering,
• workspace-scoped retrieval,
• relationship-aware navigation,
• optional semantic enrichment via shared extraction capabilities.

V1 does not need a fully generalized graph database. It needs pragmatic retrieval that is accurate, explainable, and fast.

8.3 Agent Actions

Agents must be able to:

• read notes in authorized scopes,
• propose edits,
• create structured notes,
• add summaries,
• extract tasks,
• attach citations,
• trigger workflows.

Sensitive agent behaviors must support approval states such as:

• draft,
• proposed,
• approved,
• rejected,
• applied.

8.4 Auditability

Every significant agent write operation must record:

• actor identity,
• source tool or workflow,
• timestamp,
• target object,
• operation type,
• approval status,
• request or workflow correlation ID where available.

8.5 Integrations

The product should expose:

• product REST APIs,
• MCP tools,
• webhook/event hooks where justified,
• import/export endpoints,
• clean service clients for internal web consumption.

8.6 MCP and A2A Integration Requirements

Because mcp-server is already an active workspace capability, this product should ship with an MCP strategy from the start.

Required MCP Tool Families

• note read/query tools,
• note create/update/propose-edit tools,
• workspace-scoped search tools,
• task extraction and enrichment tools,
• approval and audit tools,
• import/export tools where safe.

Guardrails

• tools must bind explicitly to product identity and workspace scope,
• mutating tools must preserve service validation and auditability,
• sensitive tools should support approval states and dry-run behavior where practical,
• MCP must orchestrate existing services rather than bypassing product/backend invariants.

A2A Opportunities

The product should be designed so agent pipelines can:

• ingest notes from external sources,
• enrich notes with extraction tasks,
• propose actions,
• hand off to approval queues,
• emit structured artifacts back into the notes system.

This should reuse the existing mcp-server orchestration model rather than inventing a separate agent control plane.

9. Non-Functional Requirements

9.1 Consistency With Workspace Rules

The implementation should follow the same standards used elsewhere:

• no console.log in production service code,
• no any in TypeScript,
• Zod validation for REST inputs,
• structured logging,
• ESM import correctness,
• shared config and auth patterns,
• request tracing with x-request-id where applicable.

9.2 Performance

The product should optimize for:

• sub-second common read flows,
• fast capture and save,
• responsive search for practical workspace sizes,
• low-friction agent CRUD operations.

9.3 Reliability

The product should gracefully handle:

• extraction service unavailability,
• partial enrichment failures,
• duplicate agent requests,
• stale approvals,
• temporary Cosmos or platform dependency issues.

Best-effort AI enrichment must never corrupt the core note record.

9.4 Security

The product must:

• rely on shared auth patterns,
• scope access by workspace and object permissions,
• keep secrets out of repo code,
• preserve auditability for agent actions,
• separate human and agent identities clearly.

9.5 Build and Verification Expectations

The PRD should set explicit verification expectations so implementation stays aligned with the rest of the workspace:

• Web

  • typecheck,
  • test,
  • production build,
  • token validation for UI changes.

• Backend

  • build,
  • test,
  • typecheck,
  • health endpoint verification.

• Mobile

  • chosen mobile surface must compile cleanly,
  • shared SDK integration must be verified,
  • core capture/retrieval flows must be smoke-tested before release.

These commands should be formalized in this repo once the stack choice and folder structure are finalized.

10. API and Data Model Direction

10.1 API Philosophy

The primary service interface should be REST plus MCP.

This is intentionally aligned with the rest of the ByteLyst workspace and avoids introducing GraphQL as a parallel architecture unless a concrete need emerges later.

10.2 Data Modeling Guidance

Each persisted object should:

• use stable IDs,
• include ownership and workspace scoping fields,
• include timestamps,
• include createdBy / updatedBy,
• support agent attribution when applicable,
• include the finalized product identity field for Cosmos documents.

10.3 Suggested V1 Containers / Collections

Illustrative product-specific containers could include:

• notes,
• workspaces,
• note_relationships,
• note_tasks,
• note_artifacts,
• agent_action_log.

Final container names should be chosen during technical design, but the split should stay pragmatic and product-focused.

Every persisted product document must include the finalized product identity field once the product ID is established.

11. Release Plan

11.1 Phase 0: Foundations

• define product identity,
• establish repo structure,
• create web scaffold,
• create backend scaffold,
• choose mobile delivery path: SwiftUI + Compose or React Native,
• wire shared packages,
• wire platform-service, extraction-service, and MCP integration points,
• define initial token usage strategy,
• define note schemas and API boundaries,
• define product manifest / bootstrap inputs,
• define reuse matrix for web and mobile.

Phase 0 exit criteria:

• product identity is finalized,
• mobile path is finalized,
• build/test commands are documented,
• shared package/service dependencies are selected,
• operator/admin boundary is defined,
• token namespace is reserved.

11.2 Phase 1: Core Notes MVP

• workspace shell,
• note CRUD,
• tagging,
• linked notes,
• search,
• backend persistence,
• auth integration,
• audit foundation,
• telemetry and diagnostics wiring,
• sync/offline queue integration,
• first-pass mobile capture and retrieval flows.

Phase 1 exit criteria:

• web authoring flow works end-to-end,
• backend CRUD and search are functional,
• audit trail exists for agent writes,
• mobile capture/retrieval flows are functional on the chosen mobile stack.

11.3 Phase 2: Agentic Layer

• MCP tools,
• note enrichment,
• task extraction,
• agent action logs,
• approval workflow for sensitive actions,
• webhook/event hooks where needed,
• A2A orchestration flows,
• structured operator/debug workflows through shared platform tooling.

Phase 2 exit criteria:

• core MCP tools are usable,
• extraction-backed enrichment works with fallback behavior,
• approval workflow is functional for selected sensitive actions,
• operator workflows are auditable.

11.4 Phase 3: Operational Maturity

• import/export,
• stronger analytics,
• better workspace administration,
• advanced retrieval,
• performance tuning,
• production readiness checks,
• cross-platform polish,
• token validation and design system hardening,
• release workflow integration for web + mobile.

Phase 3 exit criteria:

• release checks are documented and repeatable,
• production-readiness checks pass,
• cross-platform UX is coherent,
• design-system validation passes without hardcoded token violations.

11.5 Recommended Reference Implementations

To accelerate delivery, the team should borrow patterns from the strongest existing product implementations:

• Web product shell

  • ChronoMind and JarvisJr

• High-density data/dashboard patterns

  • admin-web and tracker-web

• SwiftUI app structure

  • PeakPulse, JarvisJr, ChronoMind

• Android structure

  • ChronoMind and MindLyst

• React Native acceleration path

  • NomGap

• Product backend patterns

  • any of the existing Fastify product backends, following types.ts → repository.ts → routes.ts

• Cross-product platform integration

  • existing products already using the shared Swift/Kotlin/RN SDKs

12. Success Metrics

12.1 Product Metrics

• weekly active note creators,
• notes created per active workspace,
• search-to-click success,
• note revisit rate,
• task extraction adoption,
• import success rate.

12.2 Agent Metrics

• agent-created notes per week,
• accepted vs rejected agent proposals,
• time saved on summarization and task extraction,
• retrieval success for agent workflows,
• audit completeness for automated actions.

12.3 Engineering Metrics

• build reliability,
• typecheck and test pass rate,
• API error rate,
• latency by major endpoint,
• extraction fallback rate,
• production incident count.

13. Key Decisions and Guardrails

• This product is a ByteLyst product, not a standalone architecture experiment.
• Product-specific backend logic belongs in this repo.
• Shared platform responsibilities belong in learning_ai_common_plat.
• The design system must come from shared design tokens.
• Web and mobile should be built by reusing existing workspace assets first, not by rebuilding infrastructure.
• The initial API surface should be REST + MCP, not REST + GraphQL + custom everything.
• Agent workflows are core, but human usability and auditability are non-negotiable.
• V1 should be a strong structured notes product first, then expand carefully into deeper knowledge automation.
• platform-service, extraction-service, mcp-server, SDKs, sync, diagnostics, and dashboard primitives should all be considered default inputs to implementation.

14. Open Questions

14.1 Questions That Must Be Resolved Before Implementation Starts

• canonical product identity,
• selected mobile stack,
• backend port,
• initial container strategy,
• token namespace,
• minimum mobile parity definition.