bytelyst/learning_ai_notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
07d3257753
learning_ai_notes/README.md

7.6 KiB
Raw Blame History

NoteLett

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

Quick Start

Prerequisites:

  • pnpm 10.6.5
  • sibling common-platform checkout at ../learning_ai/learning_ai_common_plat
  • optional local ByteLyst services from common platform:
    • platform-service on port 4003 for auth, flags, telemetry, diagnostics, billing, and blob
    • extraction-service on port 4005 for URL/task extraction
    • mcp-server on port 4007 for agent tooling
# Install against the local common-platform workspace packages.
GITEA_NPM_TOKEN=dummy pnpm install --frozen-lockfile

# Backend in local memory mode (port 4016)
DB_PROVIDER=memory JWT_SECRET=dev-secret-do-not-use-in-prod \
pnpm --filter @notelett/backend run dev

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

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

Auth is expected to come from platform-service. Local development can use the repo's dev/test helpers and memory datastore, but production must use real platform auth, Cosmos, and encryption configuration.

Docker path:

docker compose build
docker compose up -d
curl -sf http://localhost:4016/health
curl -sf http://localhost:4016/api/bootstrap

Local production-readiness smoke:

pnpm run smoke:local

# Use an already-running backend or skip shared service checks when isolating product behavior.
SMOKE_START_BACKEND=0 pnpm run smoke:local -- --no-start
pnpm run smoke:local -- --skip-platform

# Docker compose build/start/health smoke
pnpm run smoke:compose

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
MCP mcp-server (shared) 4007

Architecture Boundaries

NoteLett keeps product-local domain behavior in this repo: note/workspace CRUD, relationships, tasks, artifacts, agent action audit trails, saved views, prompt templates/runners, intake rules/jobs, note sharing/collaboration, version history, Palace memory/KG UX, and all NoteLett-specific web/mobile workflows.

Common-platform responsibilities come from ../learning_ai/learning_ai_common_plat: auth/session primitives, API clients, datastore/Cosmos abstractions, shared error/config/logging conventions, telemetry, diagnostics, feature flags, kill switch, blob access, extraction-service clients, design tokens, shared UI primitives where appropriate, MCP server integration, webhook dispatch, encryption helpers, and cross-repo automation scripts.

Do not move NoteLett-specific notes logic into common platform unless another product has a concrete reuse need. Do not create repo-local substitutes for platform concerns already covered by @bytelyst/* packages or platform services.

Key Features

  • Backend modules: notes, workspaces, relationships, tasks, artifacts, agent actions, saved views, Smart Actions, intake, collaborators, shares, versions, Palace, and ecosystem import routes
  • 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
  • Intake and Palace: URL/text intake jobs, intake rules, MemPalace memory/search/KG/wake-up routes
  • 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 web/.env.example to web/.env.local as needed.

Local memory mode:

  • NODE_ENV=development
  • DB_PROVIDER=memory
  • JWT_SECRET=dev-secret-do-not-use-in-prod
  • LLM_PROVIDER=mock
  • shared service URLs can point at local common-platform ports or remain disabled for isolated backend tests

Production requirements:

  • NODE_ENV=production
  • strong JWT_SECRET shared with platform-service or the production auth verification mechanism
  • DB_PROVIDER=cosmos
  • COSMOS_ENDPOINT, COSMOS_KEY, and COSMOS_DATABASE
  • FIELD_ENCRYPT_ENABLED=true with FIELD_ENCRYPT_KEY_PROVIDER=akv or a managed key provider and required key material
  • PLATFORM_SERVICE_URL, EXTRACTION_SERVICE_URL, and MCP_SERVER_URL
  • NEXT_PUBLIC_MCP_SERVER_URL=http://localhost:4007/api for local web settings/agent guidance
  • TELEMETRY_ENABLED=true and FEATURE_FLAGS_ENABLED=true when platform services are available
  • LLM_PROVIDER plus provider credentials (OPENAI_API_KEY or Azure OpenAI settings) for non-mock AI behavior

The May 5 production-readiness pass hardened production config to fail closed on unsafe defaults; see docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md.

Tests

pnpm --filter @notelett/backend run typecheck
pnpm --filter @notelett/backend run test
pnpm --filter @notelett/backend run lint
pnpm --filter @notelett/web run typecheck
pnpm --filter @notelett/web run test
pnpm --filter @notelett/web run lint
pnpm --filter @notelett/web run test:e2e
pnpm --filter @notelett/mobile run typecheck
pnpm --filter @notelett/mobile run test
pnpm --filter @notelett/mobile run lint
pnpm run verify

Current May 5 production-readiness status:

  • pnpm run verify passes backend/web/mobile typecheck and tests, plus backend/web production builds.
  • backend, web, and mobile lint commands exit 0 with tracked advisory warnings.
  • web Playwright release flows pass.
  • release-guard audits pass common-platform secret scan, hardcoded color/token checks, and active product/API drift checks.
  • Docker compose smoke and live shared-service smoke are explicit environment deferrals on this host because Docker is unavailable and platform-service/extraction-service/mcp-server are not running with Cosmos credentials.

See docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md Phase P10 for exact commands, commit hashes, warnings, and deferral notes.

Docs