# 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
```bash
cd backend
npm run dev          # Start backend in dev mode
npm run build        # Build TypeScript
npm run test         # Run tests
```

### Web Development
```bash
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
```bash
cd mobile
npm start            # Start Expo dev server
```

### Docker Development
```bash
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