# ByteLyst NoteLett - Repository Context

> **Purpose**: This file provides quick context for AI coding agents about what this repository contains and how to use it effectively.

## What This Repository Provides

This is the **NoteLett product repository** for the ByteLyst ecosystem. It contains:

- **Agentic note-taking platform** with notes, tasks, relationships, and workspaces
- **Multi-platform support**: Web (Next.js 16), iOS (React Native), Android (React Native)
- **Smart Actions**: AI-powered prompt templates and automation
- **MCP Integration**: Model Context Protocol for external tool integration
- **Cross-product imports**: Transcript and trail report imports from other ByteLyst products

## 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/`

## Key Locations

### Source Code
- **Backend**: `backend/` - Fastify 5 + TypeScript ESM backend (port 4016)
  - `backend/src/modules/` - Feature modules (notes, workspaces, relationships, tasks, etc.)
  - `backend/src/lib/` - Shared backend utilities
- **Web**: `web/` - Next.js 16 + React 19 web app (port 3045)
  - `web/src/app/` - App Router pages
  - `web/src/components/` - React UI components
  - `web/src/lib/` - Pure TS client libraries
- **Mobile**: `mobile/` - React Native + Expo companion app
  - `mobile/src/app/` - Expo Router screens
  - `mobile/src/api/` - API clients
  - `mobile/src/store/` - Zustand stores
- **Shared**: `shared/` - Shared TypeScript utilities and product config

### Configuration
- **Backend Config**: `backend/src/lib/config.ts` - Zod-validated env config
- **Web Config**: `web/src/lib/product-config.ts` - Product identity + API URLs
- **Docker Config**: `docker-compose.yml` - Container orchestration
- **TypeScript Config**: `backend/tsconfig.json`, `web/tsconfig.json`, `mobile/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`
- **AI Agent Instructions**: `AGENTS.md` (complete instructions for all tools)

### Deployment
- **Docker Prep**: `scripts/docker-prep.sh` - Package @bytelyst/* dependencies
- **Deployment Script**: `../learning_ai_devops_tools/deploy-notes.sh`
- **Dockerfiles**: `backend/Dockerfile`, `web/Dockerfile`

## Common Usage Patterns

### Development
```bash
# Install dependencies
pnpm install

# Backend development
pnpm --filter @notelett/backend run dev

# Web development
pnpm --filter @notelett/web run dev

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

# Full verification
pnpm run verify
```

### Testing
```bash
# Backend tests
pnpm --filter @notelett/backend run test

# Web tests
pnpm --filter @notelett/web run test

# Mobile tests
pnpm --filter @notelett/mobile run test
```

### Docker Build
```bash
# Prepare dependencies (REQUIRED before Docker build)
bash scripts/docker-prep.sh

# Build containers
docker-compose build

# Restore after build
bash scripts/docker-prep.sh --restore
```

## Tech Stack

| Layer | Technology |
|-------|-----------|
| **Backend** | Fastify 5, TypeScript ESM, Zod, Azure Cosmos DB |
| **Web** | Next.js 16 (App Router), React 19, TailwindCSS v4, Zustand |
| **Mobile** | React Native (Expo), TypeScript, expo-router, Zustand |
| **Shared packages** | @bytelyst/* from learning_ai_common_plat |
| **Platform** | platform-service (port 4003) for auth, flags, telemetry |
| **Database** | Azure Cosmos DB via @bytelyst/datastore |
| **LLM** | @bytelyst/llm (mock/openai/azure providers) |

## Important Notes

- **Product ID**: `notelett` (used in all Cosmos documents)
- **Package scope**: @notelett/* for workspace packages
- **Shared packages**: Uses @bytelyst/* from learning_ai_common_plat
- **Docker prep**: MUST run `scripts/docker-prep.sh` before Docker builds
- **Deployment**: ALWAYS use `../learning_ai_devops_tools/deploy-notes.sh`

## First Steps for AI Agents

1. **Read REPO_CONTEXT.md** (this file) - Understand the repository structure
2. **Read AGENTS.md** - Complete coding conventions and instructions
3. **Check companion repos** - learning_ai_common_plat and learning_ai_devops_tools
4. **Understand the stack** - Fastify backend, Next.js web, React Native mobile
5. **Follow deployment patterns** - Use docker-prep.sh and deployment scripts