learning_ai_notes/.devin/CONTEXT.md

ByteLyst NoteLett - Project Context

Purpose: This file provides project-specific context for AI coding agents working in this repository.

Companion Repositories (Always Available)

This repository has access to these companion repositories:

• learning_ai_common_plat - Platform packages (@bytelyst/*)

  • Context: learning_ai_common_plat/REPO_CONTEXT.md
  • Provides: Shared libraries, configuration, auth, cosmos, telemetry, etc.
  • Location: ../learning_ai_common_plat/

• learning_ai_devops_tools - Deployment and operational scripts

  • Context: learning_ai_devops_tools/REPO_CONTEXT.md
  • Provides: Deployment scripts, GitHub tools, operational automation
  • Location: ../learning_ai_devops_tools/

Project Overview

ByteLyst NoteLett - Agentic note-taking workspace for notes, tasks, relationships, and workspaces with:

• AI-powered note organization and linking
• Smart Actions with prompt templates
• Cross-product transcript and trail report imports
• MCP (Model Context Protocol) integration for external tools
• Multi-platform support (Web, iOS, Android)

Key Locations

Source Code

• Backend: backend/ - Fastify 5 + TypeScript ESM backend (port 4016)
• Web: web/ - Next.js 16 + React 19 web app (port 3045)
• Mobile: mobile/ - React Native + Expo companion app
• Shared: shared/ - Shared TypeScript utilities

Configuration

• Backend Config: backend/src/lib/config.ts - Zod-validated env config
• Docker Config: docker-compose.yml - Container orchestration
• TypeScript Config: backend/tsconfig.json, web/tsconfig.json

Documentation

• Product Docs: docs/PRD.md, docs/ROADMAP.md
• Production Readiness: docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md
• UI/UX Migration: docs/UI_UX_PLATFORM_CORE_ROADMAP.md

Deployment Patterns

Primary Deployment Method

• Script: learning_ai_devops_tools/deploy-notes.sh
• Usage: Always check this script first before attempting custom deployment
• Pattern: Interactive menu with options for cache, force, and health checks
• Features:
  • Package publication checks
  • --no-cache support
  • Health verification
  • Dirty checks

Deployment Requirements

• GITEA_NPM_TOKEN: Required for @bytelyst/* package installation
• Network: Access to Gitea registry for package installation
• Build Order: learning_ai_common_plat → this project

MCP Integration

MCP Components

• MCP Tool Contracts: backend/src/mcp/note-tool-contracts.ts
• MCP Tools: backend/src/mcp/note-tools.ts
• MCP Registration: backend/src/mcp/register-note-tools.ts

MCP Features

• 8 MCP Tools: Note CRUD, search, relationships, artifacts, etc.
• Zod Schemas: Type-safe tool definitions
• Integration: Fastify plugin for automatic registration

MCP Configuration

• Environment Variables:
  • MCP_SERVER_URL: MCP server endpoint
  • MCP_ENABLED: Feature flag (default: true)

Architecture Patterns

Backend Architecture

• Framework: Fastify 5 with TypeScript ESM
• Database: Azure Cosmos DB via @bytelyst/datastore
• Platform Integration: platform-service (port 4003) for auth, flags, telemetry
• Extraction: extraction-service (port 4005) for AI-powered task extraction
• LLM: @bytelyst/llm with retry + timeout hardening

Frontend Architecture

• Framework: Next.js 16 (App Router) + React 19
• State Management: Zustand + localStorage
• UI Components: @bytelyst/ui + custom components
• Styling: TailwindCSS v4 + design tokens (--nl-*)

Mobile Architecture

• Framework: React Native + Expo
• State Management: Zustand + MMKV
• Navigation: Expo Router
• Theme: NoteLystTheme from design tokens

Common Operations

Backend Development

cd backend
npm run dev          # Start backend in dev mode
npm run build        # Build TypeScript
npm run test         # Run tests

Web Development

cd web
npm run dev          # Start Next.js dev server
npm run build        # Production build (uses --webpack flag)
npm run test         # Run Vitest tests

Mobile Development

cd mobile
npm start            # Start Expo dev server

Docker Development

docker compose up    # Start all containers
docker compose down  # Stop all containers

Important Notes

Platform Integration

• platform-service: Used for auth, billing, flags, telemetry, blob storage
• extraction-service: Used for AI-powered task extraction from notes
• Product ID: "notelett" (required for all Cosmos documents)

Feature Flags

• 20 Feature Flags: Core + Smart Actions features
• Client: @bytelyst/feature-flag-client
• Backend: backend/src/lib/feature-flags.ts

Design System

• Tokens: @bytelyst/design-tokens (--nl-* CSS custom properties)
• Components: @bytelyst/ui (Button, Card, Badge, Toast, etc.)
• Never hardcode colors: Always use theme tokens

Testing

Backend Tests

• Framework: Vitest
• Coverage: All modules (notes, workspaces, relationships, tasks, etc.)
• Location: backend/src/modules/*/test.ts

Web Tests

• Framework: Vitest + Playwright
• Coverage: Components, E2E flows
• Location: web/src/*.dom.test.tsx, web/e2e/

Mobile Tests

• Framework: Expo Test (planned)

Common Issues and Solutions

Platform Integration Issues

• "platform-service unreachable": Check PLATFORM_SERVICE_URL
• "Feature flag not found": Verify feature flag configuration
• "Telemetry disabled": Check TELEMETRY_ENABLED setting

Deployment Issues

• "Cannot find module @bytelyst/...": Build learning_ai_common_plat packages first
• "Gitea registry unauthorized": Check GITEA_NPM_TOKEN
• "Docker build network error": Ensure proper network access

Development Issues

• Port conflicts: Backend (4016), Web (3045)
• Environment variables: Copy backend/.env.example to backend/.env
• TypeScript errors: Run npm run build to see full error messages

Quick Reference

Task	Command
Start development	cd backend && npm run dev
Build backend	cd backend && npm run build
Build web	cd web && npm run build -- --webpack
Deploy	../learning_ai_devops_tools/deploy-notes.sh
Run tests	cd backend && npm run test
Docker compose	docker compose up -d

First Steps for Any Task

1. Check companion repo contexts:

   • Read learning_ai_common_plat/REPO_CONTEXT.md for package patterns
   • Read learning_ai_devops_tools/REPO_CONTEXT.md for deployment patterns

2. Check deployment scripts:

   • Look for learning_ai_devops_tools/deploy-notes.sh
   • Don't build custom deployment solutions

3. Check project-specific context:

   • Product docs: docs/PRD.md, docs/ROADMAP.md
   • Production readiness: docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md

4. Verify environment setup:

   • Check backend/.env is configured
   • Ensure GITEA_NPM_TOKEN is set for deployment

Project-Specific Patterns

Note CRUD Pattern

1. Types: Define Zod schemas in types.ts
2. Repository: Use @bytelyst/datastore getCollection()
3. Routes: Fastify routes with validation
4. All documents include productId: "notelett"

Smart Actions Pattern

1. Prompt Templates: Stored in note-prompts module
2. Runner: executePrompt() with retry + timeout
3. Scheduler: Cron schedules + webhook triggers
4. Integration: Web UI for template management

Cross-Product Integration

1. Phase 1: Transcript import from LysnrAI
2. Phase 3: Trail report import from ActionTrail
3. Helpers: backend/src/lib/ecosystem-phase*.ts