Saravana Achu Mac
6be7ee470f
Systematic review identified 28 tasks across 6 phases covering auth UI, backend hardening, web UX polish, MCP wiring, and DevOps. Made-with: Cursor
240 lines
9.8 KiB
Markdown
240 lines
9.8 KiB
Markdown
# NoteLett — Agent Task Roadmap
|
||
|
||
**Date:** March 29, 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 (all used) |
|
||
| **Web** | 6 pages, 13 components, 15 lib files | 7 unit + 7 E2E | ✅ next build | 10 (all used) |
|
||
| **Mobile** | 4 tabs, note detail, auth, 5 stores | 23 tests (4 files) | ✅ typecheck | — |
|
||
|
||
All `@bytelyst/*` dependencies exist in `learning_ai_common_plat` and resolve correctly.
|
||
|
||
---
|
||
|
||
## Phase 1 — Critical Web Gaps
|
||
|
||
These block the web app from being usable by real users.
|
||
|
||
- [ ] **1.1** Add auth pages — login, register, forgot-password
|
||
- 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)/`
|
||
|
||
- [ ] **1.2** Add `middleware.ts` for route protection
|
||
- 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`
|
||
|
||
- [ ] **1.3** Replace plain textarea with a rich note editor
|
||
- 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`
|
||
|
||
- [ ] **1.4** Add workspace CRUD from web
|
||
- 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
|
||
|
||
- [ ] **1.5** Wire toast notifications
|
||
- `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
|
||
|
||
- [ ] **2.1** Add integration tests for all route modules 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)
|
||
|
||
- [ ] **2.2** Add DELETE endpoints for notes, workspaces, tasks, artifacts, relationships
|
||
- 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`
|
||
|
||
- [ ] **2.3** Enforce role-based access on REST routes
|
||
- `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
|
||
|
||
- [ ] **2.4** Enforce workspace member authorization
|
||
- `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`
|
||
|
||
- [ ] **2.5** Activate telemetry — call `trackEvent()` on key business actions
|
||
- 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`
|
||
|
||
- [ ] **2.6** Activate feature flags in route logic
|
||
- 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
|
||
|
||
- [ ] **3.1** Add pagination to all list views
|
||
- 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)/`
|
||
|
||
- [ ] **3.2** Fix `getNoteDetail` — use `GET /notes/:id` instead of fetching all notes
|
||
- File: `web/src/lib/notes-client.ts` line ~291
|
||
|
||
- [ ] **3.3** Fix `listApprovalQueue` N+1 — add backend cross-workspace pending-actions endpoint
|
||
- 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`
|
||
|
||
- [ ] **3.4** Add skeleton loading states per section (not just global spinner)
|
||
- File: new `Skeleton.tsx` component + integration in each page
|
||
|
||
- [ ] **3.5** Add file upload UI for artifacts
|
||
- `blob-client.ts` supports `uploadArtifact()` but no component triggers it
|
||
- Add file picker + upload progress to ArtifactPanel
|
||
- File: `web/src/components/ArtifactPanel.tsx`
|
||
|
||
- [ ] **3.6** Remove dead code
|
||
- Delete `web/src/lib/mock-data.ts` (228 lines, zero imports)
|
||
- Delete `web/src/lib/review-data.ts` (46 lines, zero imports)
|
||
- Remove `zustand` and `zod` from web `package.json` (declared, never imported)
|
||
|
||
- [ ] **3.7** Fix SSR crash risk — lazy-init module-scope API clients
|
||
- `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`
|
||
|
||
- [ ] **3.8** Consolidate duplicate type definitions
|
||
- `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 — MCP & AI Enrichment
|
||
|
||
- [ ] **4.1** Wire MCP tool registration to shared `mcp-server`
|
||
- `MCP_SERVER_URL=http://localhost:4007` is configured but no outbound call exists
|
||
- Backend exposes tools via `register-note-tools.ts` — need HTTP client to register them with the shared MCP server at startup
|
||
- File: `backend/src/server.ts` or new `backend/src/lib/mcp-registration.ts`
|
||
|
||
- [ ] **4.2** Add note summarization to web UI
|
||
- Backend `POST /notes/:id/summarize` already works via extraction-service
|
||
- Add "Summarize" button to note detail page that calls the endpoint and shows the result
|
||
- Files: `web/src/app/(app)/notes/[noteId]/page.tsx`, `web/src/lib/notes-client.ts`
|
||
|
||
- [ ] **4.3** Add note export UI
|
||
- Backend `GET /notes/export` already supports JSON and Markdown formats
|
||
- Add "Export" button to dashboard or workspace pages
|
||
- Files: `web/src/app/(app)/dashboard/page.tsx` or workspaces page
|
||
|
||
**Verification:**
|
||
```
|
||
cd backend && pnpm run typecheck && pnpm test
|
||
cd web && pnpm run typecheck && pnpm test && pnpm run build
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 5 — DevOps & CI
|
||
|
||
- [ ] **5.1** Enable CI workflow
|
||
- `.github/workflows/ci.yml.disabled` exists and is fully written
|
||
- Review, update if needed, rename to `ci.yml`
|
||
- File: `.github/workflows/ci.yml`
|
||
|
||
- [ ] **5.2** Fix Docker Compose platform-service reference
|
||
- `docker-compose.yml` references `localhost:4003` and `localhost:4005` but doesn't define those services
|
||
- Either add `platform-service` and `extraction-service` as services, or document that they must be run separately
|
||
- File: `docker-compose.yml`
|
||
|
||
- [ ] **5.3** Add `.env.example` missing variables
|
||
- `NEXT_PUBLIC_EXTRACTION_SERVICE_URL` and `NEXT_PUBLIC_PLATFORM_SERVICE_ORIGIN` are used in code but missing from `.env.example`
|
||
- File: `web/.env.example`
|
||
|
||
**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 |
|
||
|-------|-------|----------|-------------|
|
||
| 1 — Critical Web Gaps | 5 | HIGH | 6–8 hours |
|
||
| 2 — Backend Hardening | 6 | HIGH | 5–7 hours |
|
||
| 3 — Web UX Polish | 8 | MEDIUM | 4–6 hours |
|
||
| 4 — MCP & AI | 3 | MEDIUM | 2–3 hours |
|
||
| 5 — DevOps & CI | 3 | MEDIUM | 1–2 hours |
|
||
| 6 — Docs | 3 | LOW | 1 hour |
|
||
| **Total** | **28** | | **19–27 hours** |
|
||
|
||
---
|
||
|
||
## 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
|
||
```
|