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

5.5 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

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
  • 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 baseline intentionally records that production config still needs fail-closed hardening; 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 baseline note: after common-platform workspace alignment, pnpm install --frozen-lockfile passes. Typecheck/build/test/lint still have known baseline failures tracked in docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md P0.5.

Docs