bytelyst/learning_ai_notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
47ee228520
learning_ai_notes/docs/archive/AGENT_TASK_ROADMAP.md
saravanakumardb1 4667f85e20 docs(cleanup): move historical roadmaps to docs/archive/ and update AGENTS.md 
Sprint B — closes audit item B7 (doc consolidation).

- docs/AGENT_TASK_ROADMAP.md, docs/ARCHITECTURE_REVIEW_AND_REUSE_ROADMAP.md,
  docs/GAP_ANALYSIS.md were each self-marked as historical snapshots
  but kept polluting the top of docs/. Moved them under docs/archive/
  in the previous commit; this commit:
  - Adds docs/archive/README.md explaining what's archived vs active
  - Repoints cross-doc links in docs/IMPLEMENTATION_TRACKER.md,
    docs/WEB_AI_FAST_ROADMAP.md, and docs/roadmaps/*.md to the new
    archive paths
  - Fixes relative links inside the archived files themselves so
    historical readers can still navigate back to active docs
- AGENTS.md §1.1 refreshed: reflects the May 22 re-verified state
  (382/96/97 tests), links the two new runbooks, and points readers
  away from docs/archive/ as a work source.
2026-05-22 23:23:50 -07:00

285 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# NoteLett — Agent Task Roadmap
> **Historical snapshot.** This March 31, 2026 task roadmap is superseded for production-readiness execution. In particular, the old claim that common-platform backend package sources are missing is stale: those packages now exist under `../learning_ai/learning_ai_common_plat/packages/`. Use [`docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md`](../PRODUCTION_READINESS_HANDOFF_ROADMAP.md) as the active checklist.
**Date:** March 31, 2026
**Product:** NoteLett (`notelett`) — Structured notes for humans + AI agents
**Repo:** `learning_ai_notes`
**Stack:** Fastify 5 backend (port 4016) · Next.js 16 web (port 3000) · Expo mobile
**Platform deps:** 23 `@bytelyst/*` packages (all resolve against `learning_ai_common_plat`)
---
## Current State
| Surface | Routes / Modules | Tests | Build | Platform Pkgs |
|---------|-----------------|-------|-------|---------------|
| **Backend** | 7 modules, ~32 endpoints, 8 MCP tools | 20 files (unit + integration) | ✅ tsc | 13 (5 missing source in common_plat) |
| **Web** | 6 pages, 13 components, 15 lib files | 7 unit + 7 E2E | ✅ next build | 10 (all used) |
| **Mobile** | 5 tabs incl. settings, note detail, auth (+ register + session-aware index), kill-switch gate, broadcast + survey in root layout, feedback on settings, **auth-gated** store hydrates + broadcast/survey polling, offline queue flush (after auth, boot + foreground), **`flushTelemetry` on background**, `app-metadata` for telemetry versions, Vitest RN mocks + component smokes (auth, home, settings), 5 stores | 33 tests (7 files) | ✅ typecheck | Direct `@bytelyst/*` clients (+ optional future RN platform SDK) |
**Historical package resolution note:** The earlier claim that 5 backend `@bytelyst/*` packages were missing from common platform is stale. On May 5, 2026, `backend-config`, `backend-flags`, `backend-telemetry`, `fastify-auth`, and `field-encrypt` exist in `../learning_ai/learning_ai_common_plat/packages/`. Current package/API drift is tracked in `docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md` P0.5/P2/P5.
### Web — AI-fast product roadmap
For **sequenced web features** (command palette, context export, semantic retrieval, copilot, sharing, MCP onboarding), see **[`WEB_AI_FAST_ROADMAP.md`](./WEB_AI_FAST_ROADMAP.md)**.
### Mobile — sequential handoff
For **ordered mobile implementation** (Expo app under `mobile/`), use **[`MOBILE_DELEGATION_ROADMAP.md`](./MOBILE_DELEGATION_ROADMAP.md)** — blocks, file pointers, and acceptance criteria in one place. Update the **Current State** table above when mobile capabilities change materially.
### Mobile — remaining gaps (March 2026 review)
**Shipped:** Session-aware `index`, register, kill-switch UI, broadcast/survey, feedback, offline queue, `app-metadata`, **auth-gated hydrates** (notes/workspaces/inbox + polling only when `isAuthenticated`), **`flushTelemetry()` on background**, settings smoke test, capture → `blob-upload` comment.
**Still open** (see [`MOBILE_DELEGATION_ROADMAP.md`](./MOBILE_DELEGATION_ROADMAP.md) **§ Remaining / deferred**):
1. **Deeper RNTL** — fireEvent / richer assertions (Block H TODO in delegation doc).
2. **Optional** — `@bytelyst/react-native-platform-sdk` alignment with NomGap (**A §A.3**).
3. **Optional** — `@bytelyst/sync` (**Block I**).
---
## Phase 0 — Missing Platform Package Source (HISTORICAL, RESOLVED)
These 5 backend packages are depended on by both NoteLett and NomGap but have no source directory in `learning_ai_common_plat/packages/`. They must be created there before either product's backend can be built from a clean checkout of common_plat.
- [ ] **0.1** Create `@bytelyst/backend-config` in `learning_ai_common_plat/packages/backend-config/`
- Base Zod config schema extended by all product backends
- Imported by: `backend/src/lib/config.ts`
- [ ] **0.2** Create `@bytelyst/backend-flags` in `learning_ai_common_plat/packages/backend-flags/`
- Feature flag registry for backend services
- Imported by: `backend/src/lib/feature-flags.ts`
- [ ] **0.3** Create `@bytelyst/backend-telemetry` in `learning_ai_common_plat/packages/backend-telemetry/`
- Buffered telemetry event tracking for backends
- Imported by: `backend/src/lib/telemetry.ts`
- [ ] **0.4** Create `@bytelyst/fastify-auth` in `learning_ai_common_plat/packages/fastify-auth/`
- JWT auth middleware (RS256 JWKS + HS256 fallback), `extractAuth`, `requireRole`, `createRequestContext`
- Imported by: `backend/src/lib/auth.ts`, `backend/src/lib/request-context.ts`, all route modules
- [ ] **0.5** Create `@bytelyst/field-encrypt` in `learning_ai_common_plat/packages/field-encrypt/`
- Field-level encryption/decryption with AKV/env/memory key providers
- Imported by: `backend/src/lib/field-encrypt.ts`, `backend/src/modules/notes/repository.ts`
**Note:** These tasks require changes in `learning_ai_common_plat`, not in this repo. Coordinate with the common platform agent. NomGap also depends on all 5 of these.
**Verification:**
```bash
cd ../learning_ai_common_plat && pnpm run build
cd ../learning_ai_notes/backend && pnpm install && pnpm run typecheck
```
---
## Phase 0.5 — Fix Broken Imports + Adopt Dashboard Components
- [x] **0.5.1** Replace broken `@bytelyst/ui` ToastProvider with `sonner` — [`7babee7`](https://github.com/saravanakumardb1/learning_ai_notes/commit/7babee7)
- [x] **0.5.2** Adopt `@bytelyst/dashboard-components` (ErrorPage, NotFoundPage, LoadingSpinner) — [`7babee7`](https://github.com/saravanakumardb1/learning_ai_notes/commit/7babee7)
- [x] **0.5.3** Replace raw `extraction-client.ts` with `@bytelyst/extraction` — [`7babee7`](https://github.com/saravanakumardb1/learning_ai_notes/commit/7babee7)
---
## Phase 1 — Critical Web Gaps
These block the web app from being usable by real users.
- [x] **1.1** Add auth pages — login, register, forgot-password — [`839218a`](https://github.com/saravanakumardb1/learning_ai_notes/commit/839218a)
- Create `web/src/app/(auth)/login/page.tsx`, `register/page.tsx`, `forgot-password/page.tsx`
- Wire to existing `@bytelyst/react-auth` config in `web/src/lib/auth.ts`
- Include form validation, error states, loading states
- Files: new pages under `web/src/app/(auth)/`
- [x] **1.2** Add `middleware.ts` for route protection — [`839218a`](https://github.com/saravanakumardb1/learning_ai_notes/commit/839218a)
- Redirect unauthenticated users from `(app)/*` routes to `/login`
- Redirect authenticated users from `/login` to `/dashboard`
- Check kill-switch status (call `checkKillSwitch()` from `web/src/lib/kill-switch.ts`)
- File: `web/src/middleware.ts`
- [x] **1.3** Replace plain textarea with a rich note editor — [`839218a`](https://github.com/saravanakumardb1/learning_ai_notes/commit/839218a)
- Current `NoteEditor.tsx` is a bare `<textarea>` — inadequate for a notes product
- Add markdown support (headings, bold, italic, lists, code blocks) at minimum
- Consider Tiptap, Lexical, or MDXEditor
- File: `web/src/components/NoteEditor.tsx`
- [x] **1.4** Add workspace CRUD from web — [`839218a`](https://github.com/saravanakumardb1/learning_ai_notes/commit/839218a)
- Backend already has `POST /workspaces` and `PATCH /workspaces/:id`
- Add create-workspace modal/form on the workspaces page
- Add edit/delete actions on workspace cards
- Files: `web/src/app/(app)/workspaces/page.tsx`, new modal component
- [x] **1.5** Wire toast notifications — [`839218a`](https://github.com/saravanakumardb1/learning_ai_notes/commit/839218a)
- `ToastProvider` from `@bytelyst/ui` is mounted but zero toasts are triggered
- Replace `window.confirm()` calls with a confirmation dialog component
- Add success/error toasts after note create, update, archive, link, task create, artifact create
- Files: all page files + components that do mutations
**Verification:**
```
cd web && pnpm run typecheck && pnpm test && pnpm run build
```
---
## Phase 2 — Backend Hardening
- [x] **2.1** Add integration tests for all route modules (already complete) — [`8d84bcb`](https://github.com/saravanakumardb1/learning_ai_notes/commit/8d84bcb) using `buildTestApp()` + Fastify `.inject()`
- Current route tests only check handler registration counts
- Need real request/response tests: happy path, validation errors, auth enforcement, 404s
- Modules needing inject tests: notes, workspaces, note-relationships, note-tasks, note-artifacts, note-agent-actions, saved-views
- Files: `backend/src/modules/*/routes.integration.test.ts` (7 new files)
- [x] **2.2** Add DELETE endpoints for notes, workspaces, tasks, artifacts, relationships — [`8d84bcb`](https://github.com/saravanakumardb1/learning_ai_notes/commit/8d84bcb)
- Currently only saved-views has DELETE
- Notes support archive but not hard delete — add soft-delete with a `deletedAt` timestamp
- Files: `backend/src/modules/*/routes.ts` + `repository.ts`
- [x] **2.3** Enforce role-based access on REST routes — [`8d84bcb`](https://github.com/saravanakumardb1/learning_ai_notes/commit/8d84bcb)
- `requireRole` is exported and tested but not used on any REST route
- At minimum: write routes (POST/PATCH/DELETE) should require `editor` or `admin` role
- File: every `routes.ts` file
- [x] **2.4** Enforce workspace member authorization — [`8d84bcb`](https://github.com/saravanakumardb1/learning_ai_notes/commit/8d84bcb)
- `workspace.members` array is stored but never checked
- Note CRUD should verify the requesting user is a member of the target workspace
- Files: `backend/src/modules/notes/routes.ts`, `backend/src/modules/workspaces/repository.ts`
- [x] **2.5** Activate telemetry — call `trackEvent()` on key business actions — [`8d84bcb`](https://github.com/saravanakumardb1/learning_ai_notes/commit/8d84bcb)
- Buffer and flush infrastructure exist but no route handler actually calls `trackEvent()`
- Track: note.created, note.updated, note.archived, note.searched, workspace.created, agentAction.approved, agentAction.rejected
- Files: all `routes.ts` files + `backend/src/lib/telemetry.ts`
- [x] **2.6** Activate feature flags in route logic — [`8d84bcb`](https://github.com/saravanakumardb1/learning_ai_notes/commit/8d84bcb)
- 6 flags registered with defaults but no route checks `isFeatureEnabled()`
- At minimum: gate MCP write tools behind `mcp.enabled`, gate export behind a flag
- Files: `backend/src/lib/feature-flags.ts`, relevant route files
**Verification:**
```
cd backend && pnpm run typecheck && pnpm test
```
---
## Phase 3 — Web UX Polish
- [x] **3.1** Add pagination to all list views — [`a5b0a89`](https://github.com/saravanakumardb1/learning_ai_notes/commit/a5b0a89)
- Backend already returns `total`, `limit`, `offset` — web ignores them and fetches everything
- Add pagination controls to: notes list, workspaces list, search results, review queue, saved views
- Files: all page files under `web/src/app/(app)/`
- [x] **3.2** Fix `getNoteDetail` — use `GET /notes/:id` instead of fetching all notes — [`a5b0a89`](https://github.com/saravanakumardb1/learning_ai_notes/commit/a5b0a89)
- File: `web/src/lib/notes-client.ts` line ~291
- [x] **3.3** Fix `listApprovalQueue` N+1 (already uses `/note-agent-actions/pending`) — [`a5b0a89`](https://github.com/saravanakumardb1/learning_ai_notes/commit/a5b0a89)
- Currently fetches all workspaces, then all actions per workspace
- Add `GET /note-agent-actions/pending` (already exists) usage in web client
- Files: `web/src/lib/review-client.ts`
- [x] **3.4** Add skeleton loading states via @bytelyst/dashboard-components — [`7babee7`](https://github.com/saravanakumardb1/learning_ai_notes/commit/7babee7)
- File: new `Skeleton.tsx` component + integration in each page
- [x] **3.5** Add file upload UI for artifacts — [`a5b0a89`](https://github.com/saravanakumardb1/learning_ai_notes/commit/a5b0a89)
- `blob-client.ts` supports `uploadArtifact()` but no component triggers it
- Add file picker + upload progress to ArtifactPanel
- File: `web/src/components/ArtifactPanel.tsx`
- [x] **3.6** Remove unused dependencies (zustand, zod) — [`a5b0a89`](https://github.com/saravanakumardb1/learning_ai_notes/commit/a5b0a89)
- Remove `zustand` and `zod` from web `package.json` (declared, never imported anywhere in `web/src/`)
- [x] **3.7** Fix SSR crash risk — lazy-init already applied — [`7babee7`](https://github.com/saravanakumardb1/learning_ai_notes/commit/7babee7)
- `extraction-client.ts` and `blob-client.ts` instantiate clients at module scope
- Apply lazy singleton pattern (init on first call, not on import)
- Add `"use client"` to `notes-client.ts` or refactor extraction-client
- Files: `web/src/lib/extraction-client.ts`, `web/src/lib/blob-client.ts`, `web/src/lib/notes-client.ts`
- [x] **3.8** Consolidate duplicate type definitions (already in types.ts) — [`a5b0a89`](https://github.com/saravanakumardb1/learning_ai_notes/commit/a5b0a89)
- `NoteAgentActionDoc`, `NoteDoc`, etc. duplicated across `notes-client.ts`, `review-client.ts`, `extraction-client.ts`
- Move to `web/src/lib/types.ts` and import from there
- Files: `web/src/lib/types.ts` + all client files
**Verification:**
```
cd web && pnpm run typecheck && pnpm test && pnpm run build
```
---
## Phase 4 — New Common Platform Integrations
- [x] **4.1** Add `@bytelyst/feedback-client` — feedback button in settings page — [`02bcb0d`](https://github.com/saravanakumardb1/learning_ai_notes/commit/02bcb0d)
- [x] **4.2** Add `@bytelyst/broadcast-client` — BroadcastBanner in app layout — [`02bcb0d`](https://github.com/saravanakumardb1/learning_ai_notes/commit/02bcb0d)
- [x] **4.3** Add `@bytelyst/survey-client` — SurveyBanner in app layout — [`02bcb0d`](https://github.com/saravanakumardb1/learning_ai_notes/commit/02bcb0d)
- [x] **4.4** Add `@bytelyst/offline-queue` — persistent retry queue, flush on boot — [`02bcb0d`](https://github.com/saravanakumardb1/learning_ai_notes/commit/02bcb0d)
- [x] **4.5** Revamp settings page — profile, password, sign out, feedback form, danger zone — [`02bcb0d`](https://github.com/saravanakumardb1/learning_ai_notes/commit/02bcb0d)
- [x] **4.6** Register NoteLett tools in shared MCP server (10 tools: notes CRUD, workspaces, tasks, artifacts, summarize) — [`6997dff`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/6997dff)
**Verification:**
```
cd backend && pnpm run typecheck && pnpm test
cd web && pnpm run typecheck && pnpm test && pnpm run build
```
---
## Phase 5 — DevOps & CI
- [x] **5.1** Enable GitHub Actions CI workflow with lint steps — [`02bcb0d`](https://github.com/saravanakumardb1/learning_ai_notes/commit/02bcb0d)
- [x] **5.2** Fix docker-compose.yml — add all env vars (PRODUCT_ID, MCP, telemetry, encryption, correct branding) — [`02bcb0d`](https://github.com/saravanakumardb1/learning_ai_notes/commit/02bcb0d)
- [x] **5.3** Fix web/.env.example — correct branding to NoteLett/notelett, add EXTRACTION_SERVICE_URL — [`02bcb0d`](https://github.com/saravanakumardb1/learning_ai_notes/commit/02bcb0d)
**Verification:**
```
docker compose build
docker compose up -d && curl http://localhost:4016/api/bootstrap
```
---
## Phase 6 — Docs Alignment
- [ ] **6.1** Update `docs/ROADMAP.md` phase checklists
- Many Phase 0–3 items remain unchecked despite being implemented (per progress notes in §8)
- File: `docs/ROADMAP.md`
- [ ] **6.2** Update `AGENTS.md` with current test counts and any new endpoints added in this roadmap
- [ ] **6.3** Update `README.md` with current quick-start that reflects real auth and data flow
---
## Task Summary
| Phase | Tasks | Priority | Est. Effort |
|-------|-------|----------|-------------|
| 0 — Missing Platform Packages | 5 | **CRITICAL** | 4–6 hours (in common_plat) |
| 1 — Critical Web Gaps | 5 | HIGH | 6–8 hours |
| 2 — Backend Hardening | 6 | HIGH | 5–7 hours |
| 3 — Web UX Polish | 7 | MEDIUM | 4–5 hours |
| 4 — MCP & AI | 3 | MEDIUM | 2–3 hours |
| 5 — DevOps & CI | 3 | MEDIUM | 1–2 hours |
| 6 — Docs | 3 | LOW | 1 hour |
| **Total** | **32** | | **23–32 hours** |
**Phase 0 must be done first** — it requires changes in `learning_ai_common_plat` and unblocks both NoteLett and NomGap backends.
---
## Verification Commands (run after each phase)
```bash
# Backend
cd backend && pnpm run typecheck && pnpm test && pnpm run build
# Web
cd web && pnpm run typecheck && pnpm test && pnpm run build
# Mobile
cd mobile && pnpm run typecheck && pnpm test
# E2E
cd web && pnpm exec playwright test
```
Reference in New Issue View Git Blame Copy Permalink