226 lines
7.6 KiB
Markdown
226 lines
7.6 KiB
Markdown
# 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 |