learning_ai_notes/README.md

NoteLett

Structured notes platform for humans and AI agents — part of the ByteLyst ecosystem.

Quick Start

pnpm install

# Backend (port 4016)
pnpm --filter @notelett/backend run dev

# Web (port 3000)
pnpm --filter @notelett/web run dev

# Mobile
pnpm --filter @notelett/mobile run start

Architecture

Surface	Stack	Port
Backend	Fastify 5 + TypeScript ESM	4016
Web	Next.js 16 + React 19	3000
Mobile	Expo + React Native	8081
Platform	platform-service (shared)	4003
Extraction	extraction-service (shared)	4005

Key Features

• 8 backend modules: notes, workspaces, relationships, tasks, artifacts, agent actions, saved views, note-prompts (Smart Actions)
• 8 MCP tools: list, get, search, create_draft, update, link_notes, extract_tasks, attach_artifact
• Smart Actions: 20 built-in prompt templates, copilot text transforms, scheduler, webhooks, URL extraction
• Agent audit trail: every write tool records agent action history
• Datastore abstraction: Cosmos DB in production, in-memory for tests
• Platform integrations: auth (JWT), telemetry, diagnostics, feature flags, kill-switch, blob storage
• LLM integration: @bytelyst/llm with retry, timeout, and fallback heuristics

Environment

Copy backend/.env.example to backend/.env and fill in:

• JWT_SECRET — shared secret with platform-service
• COSMOS_ENDPOINT / COSMOS_KEY — Azure Cosmos DB credentials (or use DB_PROVIDER=memory)
• LLM_PROVIDER — mock, openai, or azure (default: mock)
• OPENAI_API_KEY — required if LLM_PROVIDER=openai

Tests

pnpm --filter @notelett/backend run test
pnpm --filter @notelett/web run test
pnpm --filter @notelett/mobile run test
pnpm run verify

Docs

• AGENTS.md — AI agent onboarding guide
• docs/PRD.md — Product requirements
• docs/ROADMAP.md — Master execution tracker