513ee5a6a5
Systematic audit of backend (7 modules, 24 tests), web (6 pages, 12 components, 6 tests), and mobile (4 tabs, 0 tests) against PRD. Key findings: - 5 bugs (extraction-client SSR crash, missing standalone output, N+1 queries, registration-only backend tests, tsconfig exclude) - 8 missing features (no web note create, no import/export, no sharing, no summarization, no relationship UI, zero mobile tests) - 5 DevOps gaps (no Dockerfiles, no docker-compose, no CI, no E2E) - 5 code quality issues (duplicate types, mock-data leftovers, N+1) - 2 documentation gaps (roadmap checklists not updated) Includes 7-sprint prioritized implementation plan with estimates.
261 lines
13 KiB
Markdown
261 lines
13 KiB
Markdown
# NoteLett — Gap Analysis
|
||
|
||
**Date:** March 19, 2026
|
||
**Auditor:** Cascade (systematic code review)
|
||
**Scope:** Full repo audit — backend, web, mobile, MCP, tests, DevOps, docs
|
||
|
||
---
|
||
|
||
## Current State Summary
|
||
|
||
| Surface | Status | Typecheck | Tests | Build |
|
||
|---------|--------|-----------|-------|-------|
|
||
| **Backend** | 7 modules + MCP (8 tools) + auth | ✅ pass | ✅ 24 tests (12 files) | ✅ tsc |
|
||
| **Web** | 6 pages + 12 components + 11 lib files | ✅ pass | ✅ 6 tests (5 files) | ✅ next build |
|
||
| **Mobile** | 4 tabs + note detail + auth + 5 stores | ✅ pass | ✅ 0 tests (passWithNoTests) | n/a |
|
||
|
||
**Commits tracked in ROADMAP.md:** 30+ incremental commits with verification notes.
|
||
|
||
---
|
||
|
||
## Gaps by Category
|
||
|
||
### Category A — Bugs (code issues that will cause runtime failures or incorrect behavior)
|
||
|
||
#### A1. `extraction-client.ts` — module-scope API client instantiation (SSR crash risk)
|
||
- **File:** `web/src/lib/extraction-client.ts:25-28`
|
||
- **Issue:** `const extractionApi = createApiClient(...)` is instantiated at module scope. The `getAccessToken()` function reads `localStorage`, which is undefined during SSR. While the `"use client"` directive helps, if this module is ever imported server-side (e.g., via `notes-client.ts` which imports `extractSuggestedTasks`), it will crash.
|
||
- **Severity:** High
|
||
- **Fix:** Apply the same lazy-init singleton pattern used in NomGap and other products.
|
||
|
||
#### A2. `next.config.ts` — missing `output: "standalone"` for Docker builds
|
||
- **File:** `web/next.config.ts:23`
|
||
- **Issue:** No Dockerfile exists yet, but when one is added, the build will fail because `output: "standalone"` is missing. The `outputFileTracingRoot` is already set (anticipating standalone), but `output` itself is not configured.
|
||
- **Severity:** Medium (not blocking today, blocks future Docker deployment)
|
||
- **Fix:** Add `output: "standalone"` to `nextConfig`.
|
||
|
||
#### A3. `notes-client.ts` — `getNoteDetail` fetches ALL notes to find one
|
||
- **File:** `web/src/lib/notes-client.ts:291-301`
|
||
- **Issue:** `getNoteDetail(noteId)` calls `GET /notes` (fetches all notes) and then `.find()` by ID client-side. This is O(n) and will degrade as note count grows. The backend already has `GET /notes/:id` which should be used instead.
|
||
- **Severity:** Medium (performance — works but scales poorly)
|
||
- **Fix:** Call `GET /notes/:id?workspaceId=...` directly. Requires knowing `workspaceId` upfront or adding a backend route that resolves by ID alone.
|
||
|
||
#### A4. `notes-client.ts` — `listWorkspaceSummaries` fetches ALL notes to count per-workspace
|
||
- **File:** `web/src/lib/notes-client.ts:209-217`
|
||
- **Issue:** Every call to `listWorkspaceSummaries()` fetches the entire notes list just to count notes per workspace. This is called frequently (dashboard, review queue, etc.).
|
||
- **Severity:** Medium (performance)
|
||
- **Fix:** Add a backend endpoint for workspace summaries with note counts, or add `noteCount` to the workspace list response.
|
||
|
||
#### A5. Backend route tests are registration-only — no API behavior coverage
|
||
- **Files:** All 7 `routes.test.ts` files under `backend/src/modules/`
|
||
- **Issue:** Every module test only verifies that route handlers are registered (`expect(app.get).toHaveBeenCalledTimes(N)`). No tests exercise actual request/response behavior, validation, error paths, or auth enforcement.
|
||
- **Severity:** High (quality — bugs in route handlers won't be caught)
|
||
- **Fix:** Add integration-style tests using `buildTestApp()` or Fastify `.inject()` to test real request flows.
|
||
|
||
---
|
||
|
||
### Category B — Missing Features (PRD requirements not yet implemented)
|
||
|
||
#### B1. No note delete endpoint
|
||
- **PRD ref:** §8.1 — "archive notes, restore notes"
|
||
- **Current:** Backend has `POST /notes/:id/archive` but no delete or restore. Web has no archive/restore UI.
|
||
- **Fix:** Add `POST /notes/:id/restore` backend route + web UI for archive/restore.
|
||
|
||
#### B2. No note create from web UI
|
||
- **PRD ref:** §8.1 — "create notes"
|
||
- **Current:** Web can edit existing notes and the dashboard links to note detail, but there is no "Create Note" button or flow on the web surface. Mobile has quick capture, but web does not.
|
||
- **Fix:** Add a create-note flow (modal or page) to the web dashboard or workspace view.
|
||
|
||
#### B3. No import/export
|
||
- **PRD ref:** §5.2 — "import/export", §8.5 — "import/export endpoints"
|
||
- **Current:** No import or export functionality exists anywhere.
|
||
- **Fix:** Add backend export endpoint (JSON/Markdown) + web download button. Import can follow in a later phase.
|
||
|
||
#### B4. No webhook/event hooks
|
||
- **PRD ref:** §8.5 — "webhook/event hooks where justified"
|
||
- **Current:** No webhook infrastructure exists.
|
||
- **Fix:** Deferred — implement after core flows are hardened. Low priority for V1.
|
||
|
||
#### B5. No note sharing within workspace
|
||
- **PRD ref:** §5.2 — "note sharing within authorized workspace scope"
|
||
- **Current:** Notes are scoped to userId. No mechanism for workspace-level shared access.
|
||
- **Fix:** Backend needs workspace-level read access rules. Web needs share UI.
|
||
|
||
#### B6. No AI summarization/enrichment beyond task extraction
|
||
- **PRD ref:** §5.2 — "AI summarization and enrichment", §8.1 — "generate summaries, generate structured metadata"
|
||
- **Current:** Only task extraction via `extraction-service` is wired. No note summarization, metadata enrichment, or auto-tagging.
|
||
- **Fix:** Add extraction-service summarization task + web UI trigger.
|
||
|
||
#### B7. Mobile has zero tests
|
||
- **PRD ref:** §9.5 — "core capture/retrieval flows must be smoke-tested"
|
||
- **Current:** `vitest run --passWithNoTests` — literally no test files.
|
||
- **Fix:** Add at least store tests, API client tests, and basic screen render tests.
|
||
|
||
#### B8. No note relationship creation from web UI
|
||
- **PRD ref:** §5.1 — "Relationship: note-to-note"
|
||
- **Current:** Backend supports note-relationships CRUD. Web displays linked notes on note detail (read-only). No UI to create/delete relationships.
|
||
- **Fix:** Add "Link Note" action on note detail page.
|
||
|
||
---
|
||
|
||
### Category C — DevOps & Infrastructure Gaps
|
||
|
||
#### C1. No Dockerfiles
|
||
- **Current:** Neither `backend/Dockerfile` nor `web/Dockerfile` exist.
|
||
- **Fix:** Add multi-stage Dockerfiles following the NomGap/ActionTrail pattern.
|
||
|
||
#### C2. No `docker-compose.yml`
|
||
- **Current:** No compose file for local full-stack development.
|
||
- **Fix:** Add docker-compose.yml with backend + web services.
|
||
|
||
#### C3. No GitHub Actions CI
|
||
- **Current:** `.github/` only contains `copilot-instructions.md`. No CI workflows.
|
||
- **Fix:** Add `.github/workflows/ci.yml` for typecheck + test on push.
|
||
|
||
#### C4. No Playwright E2E tests
|
||
- **Current:** No `playwright.config.ts`, no `e2e/` directory.
|
||
- **Fix:** Add Playwright config + basic navigation and CRUD E2E tests.
|
||
|
||
#### C5. No `scripts/docker-prep.sh`
|
||
- **Current:** No script to pack `@bytelyst/*` tarballs for Docker builds.
|
||
- **Fix:** Add docker-prep.sh following the existing ecosystem pattern.
|
||
|
||
---
|
||
|
||
### Category D — Code Quality & Consistency Gaps
|
||
|
||
#### D1. Duplicate type definitions across web clients
|
||
- **Files:** `notes-client.ts`, `review-client.ts`, `extraction-client.ts`
|
||
- **Issue:** `NoteAgentActionDoc`, `NoteDoc`, etc. are duplicated across multiple client files instead of being shared from `types.ts`.
|
||
- **Fix:** Consolidate backend response types into `web/src/lib/types.ts` and import from there.
|
||
|
||
#### D2. `review-client.ts` — listApprovalQueue fetches all workspaces then all actions per workspace (N+1)
|
||
- **File:** `web/src/lib/review-client.ts:94-104`
|
||
- **Issue:** Calls `listWorkspaceSummaries()` (which itself fetches all notes), then calls `listAgentActionsForWorkspace()` for each workspace. This is an N+1 query pattern that will degrade with scale.
|
||
- **Fix:** Add a backend endpoint that lists all pending agent actions across workspaces for the current user.
|
||
|
||
#### D3. `web/src/lib/mock-data.ts` still exists
|
||
- **File:** `web/src/lib/mock-data.ts`
|
||
- **Issue:** Legacy mock data file from scaffold era. Should be removed or clearly marked as dev-only.
|
||
- **Fix:** Remove if unused, or gate behind `NODE_ENV === "development"`.
|
||
|
||
#### D4. `review-data.ts` — unclear purpose
|
||
- **File:** `web/src/lib/review-data.ts`
|
||
- **Issue:** Appears to be a legacy data file that may be redundant with `review-client.ts`.
|
||
- **Fix:** Audit usage and remove if superseded.
|
||
|
||
#### D5. Backend `tsconfig.json` does not exclude test files
|
||
- **File:** `backend/tsconfig.json`
|
||
- **Issue:** Test files (`.test.ts`) are not excluded from the `tsc` build. This means vitest globals like `describe`, `it`, `expect` will cause errors during `npm run build` or Docker build if vitest isn't in the production dependency chain.
|
||
- **Fix:** Add `"src/**/*.test.ts"` to the `exclude` array.
|
||
|
||
---
|
||
|
||
### Category E — Documentation Gaps
|
||
|
||
#### E1. Roadmap phase checklist items are not checked off despite being implemented
|
||
- **File:** `docs/ROADMAP.md` §4 (Phase 0, Phase 1, Phase 2, Phase 3)
|
||
- **Issue:** Many checklist items under Phases 0–3 remain unchecked (`[ ]`) despite being implemented as evidenced by the progress notes (§8). For example, Phase 0 items like "product name finalized", "productId finalized", "backend port assigned" are all done (locked as NoteLett in commit `e1fde25`).
|
||
- **Fix:** Update roadmap checklist items to reflect actual implementation status.
|
||
|
||
#### E2. No `WINDSURF_CONTEXT.md`
|
||
- **Issue:** Other ByteLyst repos have a `WINDSURF_CONTEXT.md` for agent onboarding. NoteLett does not.
|
||
- **Fix:** Low priority — AGENTS.md covers most of this.
|
||
|
||
---
|
||
|
||
## Prioritized Implementation Plan
|
||
|
||
### Sprint 1 — Bug Fixes & Quality (est. 2-3 hours)
|
||
|
||
| # | Task | Priority | Files |
|
||
|---|------|----------|-------|
|
||
| 1 | Fix extraction-client.ts SSR crash (lazy-init) | High | `web/src/lib/extraction-client.ts` |
|
||
| 2 | Add `output: "standalone"` to next.config.ts | Medium | `web/next.config.ts` |
|
||
| 3 | Exclude test files from backend tsconfig build | Medium | `backend/tsconfig.json` |
|
||
| 4 | Consolidate duplicate types into types.ts | Medium | `web/src/lib/types.ts`, `notes-client.ts`, `review-client.ts` |
|
||
| 5 | Remove or gate mock-data.ts and review-data.ts | Low | `web/src/lib/mock-data.ts`, `web/src/lib/review-data.ts` |
|
||
|
||
### Sprint 2 — Backend Test Depth (est. 3-4 hours)
|
||
|
||
| # | Task | Priority | Files |
|
||
|---|------|----------|-------|
|
||
| 6 | Add integration tests for notes routes (CRUD, search, archive) | High | `backend/src/modules/notes/routes.test.ts` |
|
||
| 7 | Add integration tests for workspaces routes | High | `backend/src/modules/workspaces/routes.test.ts` |
|
||
| 8 | Add integration tests for note-tasks, note-artifacts, note-relationships | High | 3 test files |
|
||
| 9 | Add integration tests for note-agent-actions (review, batch) | High | 1 test file |
|
||
| 10 | Add integration tests for saved-views | Medium | 1 test file |
|
||
|
||
### Sprint 3 — Web Feature Gaps (est. 3-4 hours)
|
||
|
||
| # | Task | Priority | Files |
|
||
|---|------|----------|-------|
|
||
| 11 | Add "Create Note" flow to web (modal or page) | High | New component + dashboard/workspace integration |
|
||
| 12 | Add note archive/restore UI | Medium | Note detail page |
|
||
| 13 | Add "Link Note" relationship creation UI | Medium | Note detail page |
|
||
| 14 | Optimize getNoteDetail to use GET /notes/:id | Medium | `web/src/lib/notes-client.ts` |
|
||
| 15 | Add backend cross-workspace pending actions endpoint | Medium | Backend + `review-client.ts` |
|
||
|
||
### Sprint 4 — DevOps (est. 2-3 hours)
|
||
|
||
| # | Task | Priority | Files |
|
||
|---|------|----------|-------|
|
||
| 16 | Add backend Dockerfile | High | `backend/Dockerfile` |
|
||
| 17 | Add web Dockerfile | High | `web/Dockerfile` |
|
||
| 18 | Add docker-compose.yml | High | `docker-compose.yml` |
|
||
| 19 | Add docker-prep.sh | Medium | `scripts/docker-prep.sh` |
|
||
| 20 | Add GitHub Actions CI workflow | Medium | `.github/workflows/ci.yml` |
|
||
|
||
### Sprint 5 — E2E & Mobile Tests (est. 3-4 hours)
|
||
|
||
| # | Task | Priority | Files |
|
||
|---|------|----------|-------|
|
||
| 21 | Add Playwright config + navigation E2E tests | High | `web/playwright.config.ts`, `web/e2e/` |
|
||
| 22 | Add Playwright CRUD flow E2E tests | Medium | `web/e2e/` |
|
||
| 23 | Add mobile store tests (notes-store, workspace-store, inbox-store) | High | `mobile/src/store/*.test.ts` |
|
||
| 24 | Add mobile API client tests | Medium | `mobile/src/api/*.test.ts` |
|
||
|
||
### Sprint 6 — AI Enrichment & Advanced Features (est. 4-5 hours)
|
||
|
||
| # | Task | Priority | Files |
|
||
|---|------|----------|-------|
|
||
| 25 | Add note summarization via extraction-service | Medium | Backend + web trigger |
|
||
| 26 | Add note export (JSON/Markdown) | Medium | Backend endpoint + web download |
|
||
| 27 | Add workspace-level note count to backend | Low | Backend workspaces module |
|
||
|
||
### Sprint 7 — Docs Alignment (est. 1 hour)
|
||
|
||
| # | Task | Priority | Files |
|
||
|---|------|----------|-------|
|
||
| 28 | Update ROADMAP.md phase checklists to reflect actual status | Medium | `docs/ROADMAP.md` |
|
||
| 29 | Update AGENTS.md with current test counts and any new endpoints | Low | `AGENTS.md` |
|
||
|
||
---
|
||
|
||
## Verification Commands
|
||
|
||
```bash
|
||
# Backend
|
||
cd backend && npm run typecheck && npm test && npm run build
|
||
|
||
# Web
|
||
cd web && npm run typecheck && npm test && npm run build
|
||
|
||
# Mobile
|
||
cd mobile && npm run typecheck && npm test
|
||
```
|
||
|
||
---
|
||
|
||
## Totals
|
||
|
||
| Metric | Current | After Sprint 1-5 (est.) |
|
||
|--------|---------|-------------------------|
|
||
| Backend tests | 24 | ~80+ |
|
||
| Web unit tests | 6 | ~15+ |
|
||
| Web E2E tests | 0 | ~20+ |
|
||
| Mobile tests | 0 | ~15+ |
|
||
| Dockerfiles | 0 | 2 |
|
||
| CI workflows | 0 | 1 |
|
||
| Known bugs | 5 | 0 |
|