# NoteLett

Structured notes platform for humans and AI agents — part of the ByteLyst ecosystem.

## Quick Start

```bash
pnpm install

# Backend (port 4016)
pnpm --filter @notelett/backend run dev

# Web (port 3000)
pnpm --filter @notelett/web run dev

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

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

## Key Features

- **8 backend modules**: notes, workspaces, relationships, tasks, artifacts, agent actions, saved views, note-prompts (Smart Actions)
- **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
- **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 fill in:
- `JWT_SECRET` — shared secret with platform-service
- `COSMOS_ENDPOINT` / `COSMOS_KEY` — Azure Cosmos DB credentials (or use `DB_PROVIDER=memory`)
- `LLM_PROVIDER` — `mock`, `openai`, or `azure` (default: `mock`)
- `OPENAI_API_KEY` — required if `LLM_PROVIDER=openai`

## Tests

```bash
pnpm --filter @notelett/backend run test
pnpm --filter @notelett/web run test
pnpm --filter @notelett/mobile run test
pnpm run verify
```

## Docs

- [`AGENTS.md`](AGENTS.md) — AI agent onboarding guide
- [`docs/PRD.md`](docs/PRD.md) — Product requirements
- [`docs/ROADMAP.md`](docs/ROADMAP.md) — Master execution tracker