learning_ai_notes/docs/PLATFORM_SMOKE_CHECKS.md

NoteLett Platform Smoke Checks

Status: active production-readiness smoke reference Last updated: May 5, 2026

Use these checks to prove NoteLett is running against the shared ByteLyst platform services, not only compiling against @bytelyst/* packages. The common-platform source of truth is ../learning_ai/learning_ai_common_plat; prefer its compose files and scripts when bringing up shared services.

1. Bring Up Shared Services

From ../learning_ai/learning_ai_common_plat:

docker compose up -d platform-service extraction-service mcp-server
docker compose ps platform-service extraction-service mcp-server

Expected local ports:

Service	Port	Purpose
platform-service	4003	Auth, telemetry, diagnostics, flags, kill switch, blob, billing
extraction-service	4005	Extraction, task extraction, URL/content processing, transcription
mcp-server	4007	Shared MCP tool registry and tool execution
notelett-backend	4016	Product backend
notelett-web	3000	Product web app

2. Environment

Use these defaults for local smoke runs:

export PLATFORM_URL="${PLATFORM_URL:-http://localhost:4003}"
export PLATFORM_API_URL="${PLATFORM_API_URL:-http://localhost:4003/api}"
export EXTRACTION_URL="${EXTRACTION_URL:-http://localhost:4005}"
export MCP_ORIGIN="${MCP_ORIGIN:-http://localhost:4007}"
export MCP_URL="${MCP_URL:-http://localhost:4007/api}"
export NOTELETT_URL="${NOTELETT_URL:-http://localhost:4016}"
export NOTELETT_API_URL="${NOTELETT_API_URL:-http://localhost:4016/api}"
export PRODUCT_ID=notelett

Authenticated platform, blob, and MCP calls require a platform bearer token:

export TOKEN="<platform-service JWT for a NoteLett viewer/admin test user>"

When using common-platform compose locally, generate test tokens with the same mechanism used by ../learning_ai/learning_ai_common_plat/scripts/prototype-self-test.sh: execute inside platform-service and call the built createAccessToken() helper with productId: "notelett".

3. Unauthenticated Health

These should pass before authenticated smoke checks:

curl -sf "$PLATFORM_URL/health"
curl -sf "$EXTRACTION_URL/health"
curl -sf "$MCP_ORIGIN/health"
curl -sf "$NOTELETT_URL/health"
curl -sf "$NOTELETT_API_URL/bootstrap"

Expected:

• all health endpoints return 2xx
• GET /api/bootstrap returns productId: "notelett" and backend port 4016
• if extraction sidecar is not enabled, service health can still pass while sidecar-specific checks below report degraded/unavailable

4. Platform-Service Checks

Telemetry:

curl -sf "$PLATFORM_API_URL/telemetry/config?productId=$PRODUCT_ID" \
  -H "Authorization: Bearer $TOKEN"

curl -sf "$PLATFORM_API_URL/telemetry/events" \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"productId":"notelett","eventName":"notelett.smoke","timestamp":"2026-05-05T00:00:00.000Z","properties":{"source":"platform-smoke"}}'

Diagnostics:

curl -sf "$PLATFORM_API_URL/diagnostics/config?productId=$PRODUCT_ID" \
  -H "Authorization: Bearer $TOKEN"

curl -sf "$PLATFORM_API_URL/diagnostics/sessions?productId=$PRODUCT_ID&limit=1" \
  -H "Authorization: Bearer $TOKEN"

Feature flags and kill switch:

curl -sf "$PLATFORM_API_URL/flags?productId=$PRODUCT_ID" \
  -H "Authorization: Bearer $TOKEN"

curl -sf "$PLATFORM_API_URL/flags/evaluate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"productId":"notelett","flagKey":"notelett.enabled","context":{"userId":"smoke-user"}}'

Blob:

curl -sf "$PLATFORM_API_URL/blob/containers" \
  -H "Authorization: Bearer $TOKEN"

curl -sf "$PLATFORM_API_URL/blob/sas" \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"container":"attachments","blobName":"notelett/smoke/hello.txt","permissions":"rw","expiresInMinutes":10}'

For an end-to-end local blob upload/delete cycle, prefer the common-platform pattern in scripts/prototype-self-test.sh and substitute productId: "notelett" plus a notelett/smoke/ blob prefix.

5. Extraction-Service Checks

curl -sf "$EXTRACTION_URL/api/extract/models"
curl -sf "$EXTRACTION_URL/api/extract/sidecar-health"
curl -sf "$EXTRACTION_URL/api/extract/cache-stats"

For a minimal extraction task:

curl -sf "$EXTRACTION_URL/api/extract" \
  -H "content-type: application/json" \
  -d '{"productId":"notelett","taskType":"task_extraction","text":"Ship the production smoke checks and update the roadmap.","options":{"maxTasks":5}}'

Expected:

• models/cache endpoints return 2xx
• sidecar health may be degraded in local dev if the Python sidecar is intentionally disabled; record that explicitly rather than treating it as an unknown
• extraction responses should include structured output or a stable error body

6. MCP-Server Checks

curl -sf "$MCP_URL/tools" \
  -H "Authorization: Bearer $TOKEN"

Confirm NoteLett tools are present in the returned registry, especially:

• notes.notes.list
• notes.notes.get
• notes.notes.search
• notes.notes.create_draft
• notes.notes.update
• notes.relationships.link
• notes.tasks.extract
• notes.artifacts.attach

Call a read-only tool:

curl -sf "$MCP_URL/tools/call" \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"name":"notes.notes.search","arguments":{"workspaceId":"<workspace-id>","query":"smoke","limit":5}}'

Expected:

• MCP server returns 2xx and wraps tool output in MCP content
• auth, role, product scope, request ID, and product backend errors are visible in logs
• write tools should be tested with dry-run/idempotency in P2.3/P3.5 before release

7. NoteLett Backend Checks

Start backend in memory mode for local product smoke:

DB_PROVIDER=memory \
JWT_SECRET="${JWT_SECRET:-dev-secret-do-not-use-in-prod}" \
PLATFORM_SERVICE_URL="$PLATFORM_URL" \
EXTRACTION_SERVICE_URL="$EXTRACTION_URL" \
MCP_SERVER_URL="${MCP_URL%/api}" \
pnpm --filter @notelett/backend run dev

Then check:

curl -sf "$NOTELETT_URL/health"
curl -sf "$NOTELETT_API_URL/bootstrap"
curl -sf "$NOTELETT_API_URL/diagnostics/config"
curl -sf "$NOTELETT_API_URL/diagnostics/flags"
curl -sf "$NOTELETT_API_URL/diagnostics/telemetry"

Expected:

• bootstrap identifies NoteLett
• diagnostics report productId: "notelett" and the configured shared service URLs
• production should not expose unauthenticated diagnostics without the P3.3 decision applied

8. Recording Results

For every smoke run, record:

• date/time and git commit
• which services were running locally or remotely
• exact commands run
• pass/fail for health, bootstrap, telemetry, diagnostics, flags, kill switch, blob, extraction, MCP, and product backend
• any intentional local-dev degradation, such as extraction sidecar unavailable

Production-readiness completion requires these checks to be automated or repeated through the final P10 gate.