bytelyst/learning_ai_notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
0563bcdc26
learning_ai_notes/README.md

143 lines
7.1 KiB
Markdown
Raw Blame History

# NoteLett
Structured notes platform for humans and AI agents — part of the ByteLyst ecosystem.
## Quick Start
Prerequisites:
- pnpm 10.6.5
- sibling common-platform checkout at `../learning_ai/learning_ai_common_plat`
- optional local ByteLyst services from common platform:
- `platform-service` on port 4003 for auth, flags, telemetry, diagnostics, billing, and blob
- `extraction-service` on port 4005 for URL/task extraction
- `mcp-server` on port 4007 for agent tooling
```bash
# Install against the local common-platform workspace packages.
GITEA_NPM_TOKEN=dummy pnpm install --frozen-lockfile
# Backend in local memory mode (port 4016)
DB_PROVIDER=memory JWT_SECRET=dev-secret-do-not-use-in-prod \
pnpm --filter @notelett/backend run dev
# Web (port 3000)
pnpm --filter @notelett/web run dev
# Mobile
pnpm --filter @notelett/mobile run start
```
Auth is expected to come from `platform-service`. Local development can use the repo's dev/test helpers and memory datastore, but production must use real platform auth, Cosmos, and encryption configuration.
Docker path:
```bash
docker compose build
docker compose up -d
curl -sf http://localhost:4016/health
curl -sf http://localhost:4016/api/bootstrap
```
Local production-readiness smoke:
```bash
pnpm run smoke:local
# Use an already-running backend or skip shared service checks when isolating product behavior.
SMOKE_START_BACKEND=0 pnpm run smoke:local -- --no-start
pnpm run smoke:local -- --skip-platform
# Docker compose build/start/health smoke
pnpm run smoke:compose
```
## 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 |
| **MCP** | mcp-server (shared) | 4007 |
## Architecture Boundaries
NoteLett keeps product-local domain behavior in this repo: note/workspace CRUD, relationships, tasks, artifacts, agent action audit trails, saved views, prompt templates/runners, intake rules/jobs, note sharing/collaboration, version history, Palace memory/KG UX, and all NoteLett-specific web/mobile workflows.
Common-platform responsibilities come from `../learning_ai/learning_ai_common_plat`: auth/session primitives, API clients, datastore/Cosmos abstractions, shared error/config/logging conventions, telemetry, diagnostics, feature flags, kill switch, blob access, extraction-service clients, design tokens, shared UI primitives where appropriate, MCP server integration, webhook dispatch, encryption helpers, and cross-repo automation scripts.
Do not move NoteLett-specific notes logic into common platform unless another product has a concrete reuse need. Do not create repo-local substitutes for platform concerns already covered by `@bytelyst/*` packages or platform services.
## Key Features
- **Backend modules**: notes, workspaces, relationships, tasks, artifacts, agent actions, saved views, Smart Actions, intake, collaborators, shares, versions, Palace, and ecosystem import routes
- **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
- **Intake and Palace**: URL/text intake jobs, intake rules, MemPalace memory/search/KG/wake-up routes
- **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 `web/.env.example` to `web/.env.local` as needed.
Local memory mode:
- `NODE_ENV=development`
- `DB_PROVIDER=memory`
- `JWT_SECRET=dev-secret-do-not-use-in-prod`
- `LLM_PROVIDER=mock`
- shared service URLs can point at local common-platform ports or remain disabled for isolated backend tests
Production requirements:
- `NODE_ENV=production`
- strong `JWT_SECRET` shared with platform-service or the production auth verification mechanism
- `DB_PROVIDER=cosmos`
- `COSMOS_ENDPOINT`, `COSMOS_KEY`, and `COSMOS_DATABASE`
- `FIELD_ENCRYPT_ENABLED=true` with `FIELD_ENCRYPT_KEY_PROVIDER=akv` or a managed key provider and required key material
- `PLATFORM_SERVICE_URL`, `EXTRACTION_SERVICE_URL`, and `MCP_SERVER_URL`
- `NEXT_PUBLIC_MCP_SERVER_URL=http://localhost:4007/api` for local web settings/agent guidance
- `TELEMETRY_ENABLED=true` and `FEATURE_FLAGS_ENABLED=true` when platform services are available
- `LLM_PROVIDER` plus provider credentials (`OPENAI_API_KEY` or Azure OpenAI settings) for non-mock AI behavior
The May 5 production-readiness baseline intentionally records that production config still needs fail-closed hardening; see `docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md`.
## Tests
```bash
pnpm --filter @notelett/backend run typecheck
pnpm --filter @notelett/backend run test
pnpm --filter @notelett/backend run lint
pnpm --filter @notelett/web run typecheck
pnpm --filter @notelett/web run test
pnpm --filter @notelett/web run lint
pnpm --filter @notelett/web run test:e2e
pnpm --filter @notelett/mobile run typecheck
pnpm --filter @notelett/mobile run test
pnpm --filter @notelett/mobile run lint
pnpm run verify
```
Current baseline note: after common-platform workspace alignment, `pnpm install --frozen-lockfile` passes. Typecheck/build/test/lint still have known baseline failures tracked in `docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md` P0.5.
## 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
- [`docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md`](docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md) — Active production-readiness checklist
- [`docs/PLATFORM_SMOKE_CHECKS.md`](docs/PLATFORM_SMOKE_CHECKS.md) — Shared platform and NoteLett smoke commands
- [`docs/MOBILE_PRODUCTION_BUILD_AND_SMOKE.md`](docs/MOBILE_PRODUCTION_BUILD_AND_SMOKE.md) — Expo build notes and iOS/Android smoke checklist
- [`docs/RELEASE_CHECKLIST.md`](docs/RELEASE_CHECKLIST.md) — Release notes template, deploy checklist, rollback, migrations, and monitoring placeholders
- [`docs/COSMOS_DATA_OPERATIONS.md`](docs/COSMOS_DATA_OPERATIONS.md) — Cosmos containers, indexes, retention, and backup/restore approach
- [`docs/SEED_BOOTSTRAP_STRATEGY.md`](docs/SEED_BOOTSTRAP_STRATEGY.md) — Built-in prompt, intake rule, onboarding workspace, and feature-flag bootstrap strategy
- [`docs/DATA_MIGRATION_AND_BACKFILL_PLAN.md`](docs/DATA_MIGRATION_AND_BACKFILL_PLAN.md) — Encrypted-field, schema-change, and backfill migration plan
- [`docs/TELEMETRY_AND_DIAGNOSTICS_TAXONOMY.md`](docs/TELEMETRY_AND_DIAGNOSTICS_TAXONOMY.md) — Event taxonomy and diagnostic breadcrumb contract
- [`docs/OPERATOR_RUNBOOK.md`](docs/OPERATOR_RUNBOOK.md) — Incident triage and recovery steps for dependencies, scheduler/webhooks, blob, LLM/extraction, reviews, and MCP
Reference in New Issue View Git Blame Copy Permalink