bytelyst/learning_ai_notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
c6aa775cd3
learning_ai_notes/AGENTS.md
saravanakumardb1 d09259c42e docs: update AGENTS.md + ROADMAP.md with all completed features, register saved_views container 
- AGENTS.md: added saved-views module, lib/platform.ts, batch-review endpoint, saved-views endpoints, blob-client to shared packages, 7 Cosmos containers, keyboard shortcuts + debounce hooks
- ROADMAP.md: 6 new commit entries, all blockers/deferrals marked resolved
- cosmos-init.ts: registered saved_views container with /userId partition

All 3 surfaces verified: backend 18/18, web 6/6, mobile typecheck pass.
2026-03-10 19:45:13 -07:00

13 KiB
Raw Blame History

AGENTS.md — AI Coding Agent Instructions

For: Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Windsurf Cascade, and any AI coding agent. Repo: learning_ai_notes — NoteLett structured notes platform for humans and AI agents. See also: docs/PRD.md for full product spec, docs/ROADMAP.md for implementation plan.

1. Project Identity

Key Value
Product NoteLett
Product ID notelett
Bundle ID (iOS) com.bytelyst.notelett
Bundle ID (Android) com.notelett.app
Domain notelett.app
Repo learning_ai_notes
Ecosystem ByteLyst (shares platform-service with LysnrAI, MindLyst, ChronoMind, JarvisJr, NomGap, PeakPulse)

2. Repo Layout

learning_ai_notes/
├── backend/                          # Fastify 5 + TypeScript ESM backend (port 4016)
│   ├── src/
│   │   ├── lib/
│   │   │   ├── config.ts             # Zod-validated env config
│   │   │   ├── product-config.ts     # Product identity from shared/product.json
│   │   │   ├── auth.ts               # JWT extraction helper
│   │   │   ├── request-context.ts    # getUserId(req), getRequestProductId(req)
│   │   │   ├── cosmos-init.ts        # Cosmos container registration
│   │   │   ├── datastore.ts          # @bytelyst/datastore provider (Cosmos or memory)
│   │   │   └── errors.ts             # Re-export from @bytelyst/errors
│   │   ├── modules/
│   │   │   ├── notes/                # Note CRUD (types, repository, routes, test)
│   │   │   ├── workspaces/           # Workspace CRUD (types, repository, routes, test)
│   │   │   ├── note-relationships/   # Note linking (types, repository, routes, test)
│   │   │   ├── note-tasks/           # Task CRUD (types, repository, routes, test)
│   │   │   ├── note-artifacts/       # Artifact CRUD (types, repository, routes, test)
│   │   │   ├── note-agent-actions/   # Agent action audit trail + batch review (types, repository, routes, test)
│   │   │   └── saved-views/          # Persisted saved views CRUD (types, repository, routes)
│   │   ├── mcp/
│   │   │   ├── note-tool-contracts.ts    # 8 MCP tool Zod schemas + definitions
│   │   │   ├── note-tools.ts             # 8 executable MCP tool implementations
│   │   │   ├── register-note-tools.ts    # Fastify plugin to register MCP tools
│   │   │   └── *.test.ts                 # MCP test files
│   │   └── server.ts                 # Fastify entrypoint (7 route modules + MCP)
│   ├── package.json
│   └── tsconfig.json
│
├── web/                              # Next.js 16 + React 19 web app (App Router)
│   ├── src/
│   │   ├── app/
│   │   │   ├── page.tsx              # Landing page
│   │   │   ├── layout.tsx            # Root layout
│   │   │   └── (app)/               # Authenticated route group
│   │   │       ├── dashboard/        # Dashboard with metrics + recent notes
│   │   │       ├── workspaces/       # Workspace list + filters
│   │   │       ├── search/           # Search with saved queries
│   │   │       ├── reviews/          # Approval queue + agent timeline
│   │   │       └── notes/[noteId]/   # Note detail with editor
│   │   ├── components/               # React UI components
│   │   │   ├── Sidebar.tsx
│   │   │   ├── AppShell.tsx
│   │   │   ├── MetadataPanel.tsx
│   │   │   ├── LinkedNotesPanel.tsx
│   │   │   └── AgentTimeline.tsx
│   │   └── lib/                      # Pure TS clients + config
│   │       ├── product-config.ts     # Product identity + API URLs
│   │       ├── auth.ts               # @bytelyst/react-auth provider
│   │       ├── notes-client.ts       # Notes API client (backend)
│   │       ├── review-client.ts      # Approval queue, timeline, batch review
│   │       ├── saved-views-client.ts # Saved views CRUD client
│   │       ├── platform.ts           # @bytelyst/platform-client
│   │       ├── telemetry.ts          # @bytelyst/telemetry-client
│   │       ├── diagnostics.ts        # @bytelyst/diagnostics-client
│   │       ├── feature-flags.ts      # @bytelyst/feature-flag-client
│   │       ├── kill-switch.ts        # @bytelyst/kill-switch-client
│   │       ├── extraction-client.ts  # Extraction-service task extraction
│   │       ├── blob-client.ts        # @bytelyst/blob-client wrapper
│   │       ├── use-keyboard-shortcuts.ts # Global keyboard shortcuts hook
│   │       ├── use-debounce.ts       # Debounce hook for search
│   │       └── types.ts              # Shared TypeScript interfaces
│   ├── package.json
│   └── tsconfig.json
│
├── mobile/                           # React Native + Expo companion app
│   ├── src/
│   │   ├── app/                      # Expo Router screens
│   │   │   ├── (tabs)/              # 4-tab navigator (home, inbox, capture, settings)
│   │   │   ├── note/[noteId].tsx    # Note detail
│   │   │   └── auth.tsx             # Auth screen
│   │   ├── api/                     # API clients
│   │   │   ├── config.ts            # Product identity + API URLs
│   │   │   ├── auth.ts              # @bytelyst/auth-client
│   │   │   ├── notes.ts             # Notes API client
│   │   │   └── note-agent-actions.ts # Agent actions API client
│   │   ├── lib/                     # Platform SDK wrappers
│   │   │   └── platform.ts         # Telemetry, feature flags, kill switch, blob client
│   │   ├── store/                   # Zustand stores
│   │   │   ├── auth-store.ts
│   │   │   ├── inbox-store.ts
│   │   │   └── mmkv-storage.ts      # MMKV persistent storage
│   │   └── theme/                   # Design tokens
│   ├── app.json                     # Expo config
│   └── package.json
│
├── shared/
│   └── product.json                 # Canonical product identity
│
├── docs/
│   ├── PRD.md                       # Product requirements
│   ├── ROADMAP.md                   # Master execution tracker
│   ├── ARCHITECTURE_REVIEW_AND_REUSE_ROADMAP.md
│   └── roadmaps/                    # Per-workstream roadmaps
│       ├── 00_MASTER_EXECUTION_PLAN.md
│       ├── 01_FOUNDATIONS_AND_DECISIONS.md
│       ├── 02_BACKEND_ROADMAP.md
│       ├── 03_WEB_ROADMAP.md
│       └── 04_MOBILE_ROADMAP.md
│
├── AGENTS.md                        # This file
└── README.md

3. Tech Stack

Layer Technology
Backend Fastify 5, TypeScript ESM, Zod, jose (JWT), @bytelyst/datastore (Cosmos or memory)
Web Next.js 16 (App Router), React 19, TailwindCSS v4, Zustand, Vitest
Mobile React Native (Expo), TypeScript, expo-router, Zustand, MMKV
Shared packages @bytelyst/fastify-core, @bytelyst/config, @bytelyst/cosmos, @bytelyst/errors, @bytelyst/datastore, @bytelyst/api-client, @bytelyst/react-auth, @bytelyst/auth-client, @bytelyst/telemetry-client, @bytelyst/diagnostics-client, @bytelyst/feature-flag-client, @bytelyst/kill-switch-client, @bytelyst/platform-client, @bytelyst/blob-client
Platform platform-service (port 4003) for auth, flags, telemetry, billing, blob
Extraction extraction-service (port 4005) for AI-powered task extraction
Database Azure Cosmos DB via @bytelyst/datastore — productId: "notelett"
Tests Vitest — 18 backend tests (10 files), 6 web tests (5 files)

4. Coding Conventions

MUST follow

  • Every Cosmos document MUST include a productId: "notelett" field
  • Backend modules follow types.ts → repository.ts → routes.ts pattern
  • All repositories use @bytelyst/datastore getCollection() — never direct Cosmos SDK calls
  • Web engine logic in web/src/lib/ — pure TS, no React imports
  • Web components in web/src/components/ — React UI only
  • Mobile API clients in mobile/src/api/ — pure TS
  • Theme tokens use --nl-* CSS custom properties (web) or NoteLettTheme (native)
  • Commit messages: type(scope): description — types: feat, fix, docs, refactor, test, chore

MUST NOT do

  • Never use console.log in production code — use req.log or app.log in Fastify
  • Never use any type — use Zod inference or explicit types
  • Never hardcode colors — use theme tokens
  • Never hardcode API URLs — use env vars or config
  • Never hardcode product ID — use PRODUCT_ID from product-config.ts
  • Never modify tests to make them pass — fix the actual code
  • Never delete existing comments or documentation unless explicitly asked
  • Never add emojis to code unless explicitly asked

5. Key Design Decisions

MCP Tool Architecture

  • 8 MCP tools: list, get, search, create_draft, update, link_notes, extract_tasks, attach_artifact
  • Every write tool records an agent action audit trail
  • All tools enforce product scope and user authentication
  • Dry-run, idempotency key, and correlation ID support on all write tools

Datastore Abstraction

  • @bytelyst/datastore provides CosmosDatastoreProvider and MemoryDatastoreProvider
  • DB_PROVIDER env var controls which provider is used (default: cosmos, test: memory)
  • All 7 repositories use getCollection() — no direct Cosmos SDK calls

Agent Action Audit Trail

  • Every MCP tool write operation creates a NoteAgentActionDoc record
  • Actions track: actorId, actorType, toolName, actionType, state, reason, before/after summaries
  • Supports approval workflows: draft → proposed → approved/rejected → applied

Cosmos Containers

  • notes (partition: /workspaceId)
  • workspaces (partition: /userId)
  • note_relationships (partition: /workspaceId)
  • note_tasks (partition: /workspaceId)
  • note_artifacts (partition: /workspaceId)
  • note_agent_actions (partition: /workspaceId)
  • saved_views (partition: /userId)

6. Build & Test Commands

# ── Backend ────────────────────────────────────────
cd backend && npm run dev              # Dev server (port 4016)
cd backend && npm run typecheck        # tsc --noEmit
cd backend && npm test                 # 18 Vitest tests

# ── Web ────────────────────────────────────────────
cd web && npm run dev -- --webpack     # Dev server (port 3000)
cd web && npm run build -- --webpack   # Production build
cd web && npm run typecheck            # tsc --noEmit
cd web && npm test                     # 6 Vitest tests

# ── Mobile ─────────────────────────────────────────
cd mobile && npm start                 # Expo dev server
cd mobile && npm run typecheck         # tsc --noEmit

7. Backend API Endpoints

Method Path Description
GET/POST /api/notes List / create notes
GET/PATCH /api/notes/:id Note CRUD
GET/POST /api/workspaces List / create workspaces
GET/PATCH /api/workspaces/:id Workspace CRUD
GET/POST /api/note-relationships List / create relationships
GET/POST /api/note-tasks List / create tasks
GET/PATCH /api/note-tasks/:id Task CRUD
GET/POST /api/note-artifacts List / create artifacts
PATCH /api/note-artifacts/:id Update artifact
GET/POST /api/note-agent-actions List / create agent actions
PATCH /api/note-agent-actions/:id Update agent action state
POST /api/note-agent-actions/batch-review Batch approve/reject (up to 50)
GET/POST /api/saved-views List / create saved views
GET/PATCH/DELETE /api/saved-views/:id Saved view CRUD
GET /health Health check

8. MCP Tools

Tool Name Description Role
notes.notes.list List notes in a workspace viewer
notes.notes.get Get a single note viewer
notes.notes.search Search notes with lexical query viewer
notes.notes.create_draft Create a note draft admin
notes.notes.update Update note title/body/status/tags admin
notes.relationships.link Create typed relationship between notes admin
notes.tasks.extract Extract tasks from note body admin
notes.artifacts.attach Attach artifact to a note admin