bytelyst/learning_ai_notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
5ce97f8615
learning_ai_notes/docs/SEED_BOOTSTRAP_STRATEGY.md

7.2 KiB
Raw Blame History

NoteLett Seed And Bootstrap Strategy

Date: May 5, 2026 Owner: NoteLett backend and release operators Common platform: ../learning_ai/learning_ai_common_plat

Purpose

This document defines the deterministic seed and bootstrap strategy for production data that must exist before users depend on NoteLett workflows. It covers built-in prompt templates, intake rules, the per-user default workspace flow, and release feature-flag defaults.

Bootstrap Command

Run the backend seed bootstrap after Cosmos containers are available and before production smoke checks:

zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm run seed:bootstrap'

The command executes backend/src/scripts/bootstrap-seed.ts, initializes the shared datastore provider, registers/optionally ensures Cosmos containers through the common-platform @bytelyst/cosmos path, and upserts deterministic NoteLett built-ins.

For production, provide the same backend environment used by the deployed service:

NODE_ENV=production \
DB_PROVIDER=cosmos \
COSMOS_ENDPOINT=... \
COSMOS_KEY=... \
COSMOS_DATABASE=notelett-prod \
JWT_SECRET=... \
FIELD_ENCRYPTION_ENABLED=true \
FIELD_ENCRYPTION_KEY_PROVIDER=azure-key-vault \
pnpm run seed:bootstrap

COSMOS_AUTO_INIT=true is optional. Use it only when the operator intends the command to create missing Cosmos containers; otherwise run it after infrastructure provisioning has already created them.

Built-In Prompt Templates

Source: backend/src/modules/note-prompts/seed.ts Collection: note_prompts Partition key: /userId Sentinel owner: userId = "__builtin__"

Prompt templates are generated from getBuiltinTemplates() with:

  • productId = PRODUCT_ID
  • id = "builtin-" + slug
  • isBuiltin = true
  • stable slug/category/input/output fields

pnpm run seed:bootstrap calls upsertBuiltinTemplate() for every built-in template. The upsert is safe to run repeatedly: existing ids are replaced with the current source definition and new templates are inserted when added. User-created templates are not touched.

Runtime behavior:

  • GET /api/note-prompts?includeBuiltin=true returns persisted built-ins plus user templates.
  • POST /api/note-prompts/run can resolve built-ins by templateId from the __builtin__ partition.
  • Built-ins cannot be patched or deleted through the user API.

Built-In Intake Rules

Source: backend/src/modules/intake/seed-rules.ts Collection: note_intake_rules Partition key: /userId Sentinel owner: userId = "__builtin__" Sentinel workspace: workspaceId = "__all__"

Intake rules are generated from getBuiltinIntakeRules() with deterministic ids such as builtin-intake-youtube, builtin-intake-tweet, and builtin-intake-generic-5. The bootstrap command persists these rules through upsertBuiltinIntakeRule().

Runtime behavior:

  • Intake matching reads user rules and persisted built-ins, then merges source-defined built-ins that are not yet persisted.
  • User rules can override behavior with lower priority values or explicit templateOverride in the intake request.
  • Built-in rules cannot be patched or deleted through the user API.

The request-time merge is a safety net for development and partial deploys. Production should still run pnpm run seed:bootstrap so operators can inspect built-in rule rows in Cosmos and validate them during release smoke.

Default Workspace Bootstrap

Endpoint: POST /api/workspaces/onboarding-seed Feature flag: onboarding.seed_enabled Collections: workspaces, notes, note_agent_actions

The default workspace is intentionally per-user and is not created by the global bootstrap command. A signed-in writer calls the onboarding endpoint when they have no workspaces. The endpoint:

  • rejects if onboarding.seed_enabled is false
  • rejects when the user already has any workspace
  • creates one "Getting started" workspace
  • creates three sample notes
  • creates one sample proposed agent action
  • emits workspace.onboarding_seeded

This keeps global production deploys from creating user-owned documents without an authenticated user context.

Feature Flags

Source: backend/src/lib/feature-flags.ts Common platform owner: platform-service / @bytelyst/backend-flags

The backend keeps local defaults for safe startup when FEATURE_FLAGS_ENABLED=false or the platform flag service is unavailable. Production release values should be managed in platform-service and reviewed before deploy.

Initial production recommendation:

Flag Initial value Reason
notes.enabled true Core product flow
workspaces.enabled true Core product flow
relationships.enabled true Core product flow
tasks.enabled true Core product flow
artifacts.enabled true Core product flow
mcp.enabled true Agent integration
search.hybrid_enabled true Release search behavior
copilot.enabled true Existing copilot endpoint gate
chat.rag_enabled true Existing workspace chat gate
onboarding.seed_enabled true New-user workspace bootstrap
notelett_duplicate_check_enabled true Smart suggestion support
notelett_suggest_links_enabled true Smart suggestion support
notelett_intake_enabled true Release intake flow
notelett_smart_actions_enabled false until smoke passes LLM-dependent workflow
notelett_auto_summarize_enabled false Background LLM cost/risk
notelett_auto_embed_enabled false Background embedding cost/risk
notelett_auto_link_enabled false Background mutation risk
notelett_copilot_llm_enabled false until LLM smoke passes LLM-dependent workflow
notelett_voice_capture_enabled false Mobile capture gate
notelett_scheduled_actions_enabled false until scheduler smoke passes Background LLM/webhook risk
notelett_webhooks_enabled false until webhook smoke passes External callback risk
notelett_collaborative_sharing_enabled false until sharing smoke passes Cross-user access risk
notelett_push_notifications_enabled false Mobile notification gate

Release Order

  1. Deploy or provision Cosmos containers from backend/src/lib/cosmos-init.ts.
  2. Run pnpm run seed:bootstrap with production backend env.
  3. Confirm the seed log reports the expected counts for prompt templates, intake rules, and feature flags.
  4. Run platform flag smoke from docs/PLATFORM_SMOKE_CHECKS.md.
  5. Set production feature-flag values in platform-service.
  6. Run pnpm run smoke:local or the environment-specific backend smoke.
  7. Sign in as a test user and call onboarding seed only for that test account.

Verification

For code changes to seed/bootstrap behavior, run:

zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/backend run typecheck'
zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/backend exec vitest run src/modules/note-prompts/note-prompts.test.ts src/modules/intake/routes.test.ts src/modules/workspaces/routes.integration.test.ts'
zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; DB_PROVIDER=memory pnpm run seed:bootstrap'

Record the seed output in the release notes. A healthy memory-mode bootstrap reports the current built-in prompt count, six intake rules, and the registered feature-flag count.