From bace77387aceb5cbe9699e5c68df55ba9f3e17ad Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Tue, 10 Mar 2026 07:35:10 -0700 Subject: [PATCH] docs(prd): align notes product with workspace architecture --- docs/PRD.md | 1016 ++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 970 insertions(+), 46 deletions(-) diff --git a/docs/PRD.md b/docs/PRD.md index 6899f38..8047e4f 100644 --- a/docs/PRD.md +++ b/docs/PRD.md @@ -1,58 +1,982 @@ -Product Requirements Document: AI-Agent-First Knowledge Platform +Product Requirements Document: ByteLyst Agentic Notes -Version: 1.0 +Version: 2.0 Date: March 10, 2026 Author: Product Team Status: Draft -1. Executive Summary -This platform is being built from the ground up as an AI-agent-first knowledge platform — a system where AI agents are first-class citizens alongside human users. Every note, workspace, workflow, and API is designed to be created, consumed, and orchestrated by both humans and autonomous agents. +# 1. Product Vision -The current application is a capable note-taking app with workspaces, hashtags, posts, and bolted-on AI features. The rebuild inverts the paradigm: instead of a human app with AI helpers, it becomes a knowledge operating system where agents think, collaborate, and act — and humans supervise, guide, and participate. -Vision Statement +ByteLyst Agentic Notes is a knowledge product for humans and AI agents to capture, structure, retrieve, and operationalize notes in a shared system of record. - "The knowledge layer for the agentic era — where humans and AI agents create, organize, reason over, and act on knowledge together." +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: -Key Differentiators +- 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/`. - Agent-native data model — Every entity (note, task, artifact) is structured for machine readability while remaining human-friendly - MCP-native architecture — Full Model Context Protocol support as the primary integration surface - Knowledge graph, not folders — Semantic relationships replace hierarchical organization - Event-driven agent orchestration — Agents react to knowledge changes in real-time - Multi-tenant agent identity — Agents have identities, permissions, audit trails, and reputation just like human users +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. -2. Problem Statement -Current Limitations -Problem Impact -Notes are unstructured blobs of text Agents can't reliably parse, query, or reason over content -AI is an afterthought (chat sidebar) No deep integration; agents can't autonomously create or manage knowledge -No agent identity system Can't track what an agent did, why, or with what authority -API is human-UI-coupled No clean programmatic interface for agent tooling -Flat organization (workspaces + hashtags) No semantic relationships, no knowledge graph -Single-user mental model No agent-to-agent collaboration or delegation -Hardcoded AI endpoints Can't swap models, providers, or agent frameworks -Backend split across multiple services Fragile, hard to extend, inconsistent APIs -No event/webhook system Agents can't react to changes or trigger workflows -Block-based billing is vague No clear unit economics for agent compute -Market Opportunity +## 1.1 Vision Statement -The AI agent ecosystem is exploding — every major LLM provider ships agent frameworks (OpenAI Agents SDK, Anthropic MCP, Google A2A, LangChain, CrewAI, AutoGen). But agents lack a persistent, shared knowledge layer that isn't just a vector database. This platform fills that gap: a place where agents store their work, share context, collaborate with humans, and build institutional knowledge. -3. Target Users -3.1 Human Users -Persona Description Key Needs -Knowledge Worker Individual using notes, tasks, research Fast capture, AI-assisted organization, search -Team Lead Manages a team with shared workspaces Oversight of agent work, approval workflows, analytics -Developer Builds agent workflows, integrations Clean APIs, MCP tools, webhooks, SDK -Creator Publishes posts, builds content AI-assisted writing, scheduling, distribution -3.2 AI Agent Users -Persona Description Key Needs -Research Agent Gathers, synthesizes, and stores information Read/write notes, semantic search, source linking -Workflow Agent Orchestrates multi-step processes Task management, status updates, human-in-the-loop -Analysis Agent Processes data and produces insights Structured output storage, chart/artifact creation -Assistant Agent Responds to user queries using knowledge base Full-text + semantic search, context retrieval -Integration Agent Syncs data between external systems and the platform Webhooks, CRUD APIs, bulk operations -Monitoring Agent Watches for changes and triggers actions Event subscriptions, real-time notifications -4. Architecture Overview -4.1 High-Level Architecture +"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." -┌─────────────────────────────────────────────────────────────────┐│ CLIENT LAYER ││ ││ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ ││ │ Web UI │ │Mobile PWA│ │ CLI │ │ Agent SDKs │ ││ │ (React) │ │ (React) │ │(Terminal)│ │ (TS/Py/Rust) │ ││ └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬───────┘ ││ └──────────────┴─────────────┴───────────────┘ │└────────────────────────────┬────────────────────────────────────┘ │┌────────────────────────────┼────────────────────────────────────┐│ API GATEWAY LAYER ││ ││ ┌────────────────────────┴────────────────────────────────┐ ││ │ Unified REST + GraphQL API │ ││ │ (Auth, Rate Limiting, Agent Identity) │ ││ └────────────────────────┬────────────────────────────────┘ ││ │ ││ ┌────────────┐ ┌───────┴───────┐ ┌──────────────────┐ ││ │ MCP Server│ │ WebSocket │ │ Webhook Engine │ ││ │ (Tools) │ │ (Real-time) │ │ (Outbound) │ ││ └────────────┘ └───────────────┘ └──────────────────┘ │└────────────────────────────┬────────────────────────────────────┘ │┌────────────────────────────┼────────────────────────────────────┐│ SERVICE LAYER ││ ││ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ ││ │Knowledge │ │ Agent │ │Workflow │ │ AI Inference │ ││ │ Service │ │ Service │ │ Engine │ │ Gateway │ ││ └──────────┘ └──────────┘ └──────────┘ └──────────────────┘ ││ ┌──────────┐ ┌─────── \ No newline at end of file +## 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. \ No newline at end of file