From 014b0983df8b7c2e90e7696cb1b693140701ccfd Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Tue, 5 May 2026 09:15:00 -0700 Subject: [PATCH] docs(readme): refresh production quick start --- README.md | 69 +++++++++++++++++--- docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md | 2 +- 2 files changed, 61 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 0742c2d..61aa261 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,21 @@ Structured notes platform for humans and AI agents — part of the ByteLyst ecos ## Quick Start -```bash -pnpm install +Prerequisites: -# Backend (port 4016) +- 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) @@ -17,6 +28,17 @@ pnpm --filter @notelett/web run dev 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 +``` + ## Architecture | Surface | Stack | Port | @@ -26,12 +48,14 @@ pnpm --filter @notelett/mobile run start | **Mobile** | Expo + React Native | 8081 | | **Platform** | platform-service (shared) | 4003 | | **Extraction** | extraction-service (shared) | 4005 | +| **MCP** | mcp-server (shared) | 4007 | ## Key Features -- **8 backend modules**: notes, workspaces, relationships, tasks, artifacts, agent actions, saved views, note-prompts (Smart Actions) +- **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 @@ -39,23 +63,50 @@ pnpm --filter @notelett/mobile run start ## 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` +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` +- `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 diff --git a/docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md b/docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md index 268b545..14be20d 100644 --- a/docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md +++ b/docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md @@ -108,7 +108,7 @@ Goal: remove roadmap drift so agents do not chase already completed or obsolete - [x] **P1.1** Reconcile `docs/ROADMAP.md` with actual implemented status for product identity, ports, CRUD, tests, Docker, CI, MCP, Smart Actions, intake, Palace, and platform integrations. Commit: `3553b6e`; Verified: `git diff --check`; roadmap now reflects NoteLett identity, port `4016`, implemented CRUD/MCP/review/search/mobile/platform surfaces, and the active May 5 Palace/LLM/lint/smoke blockers instead of March draft checkboxes. - [x] **P1.2** Update `AGENTS.md` with current module list, endpoint list, test counts, route modules, containers, shared packages, and verification commands. Commit: `99efad8`; Verified: `git diff --check`; AGENTS now points at the active production-readiness roadmap, the correct common-platform path, current backend/web/mobile modules, 14 API route modules, expanded endpoint/container lists, current test inventory, lint/E2E commands, and the May 5 baseline failure note. -- [ ] **P1.3** Update `README.md` quick start with required common-platform services, auth expectations, Docker path, local memory mode, and production env requirements. Commit: +- [x] **P1.3** Update `README.md` quick start with required common-platform services, auth expectations, Docker path, local memory mode, and production env requirements. Commit: `pending`; Verified: `git diff --check`; README now documents the local common-platform checkout, platform/extraction/MCP ports, memory-mode command, Docker compose smoke path, auth expectations, production env requirements, and current baseline caveat. - [ ] **P1.4** Mark stale `docs/GAP_ANALYSIS.md`, `docs/AGENT_TASK_ROADMAP.md`, and older reuse roadmaps as historical or reconcile their open items with this roadmap. Commit: - [ ] **P1.5** Add a concise architecture boundary section: product-local NoteLett logic versus common platform responsibilities. Commit: