saravanakumardb1 9d392eab39 docs: add AGENTS.md, README.md, and update roadmap with session commit refs

- AGENTS.md: full AI agent onboarding guide following ecosystem conventions
- README.md: quick start, architecture overview, env setup, test commands
- ROADMAP.md: added commit references for identity lock, MCP tools, platform integrations, blob client
- Marked resolved blockers (product identity, blob artifacts)

2026-03-10 19:01:48 -07:00

12 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 (types, repository, routes, test)
│   │   ├── 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 (6 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)
│   │       ├── 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        # SAS-based blob upload/download
│   │       └── 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
│   │   ├── 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`
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 6 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)

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
GET/PATCH	`/api/note-agent-actions/:id`	Agent action 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

12 KiB Raw Blame History

AGENTS.md — AI Coding Agent Instructions

1. Project Identity

2. Repo Layout

3. Tech Stack

4. Coding Conventions

MUST follow

MUST NOT do

5. Key Design Decisions

MCP Tool Architecture

Datastore Abstraction

Agent Action Audit Trail

Cosmos Containers

6. Build & Test Commands

7. Backend API Endpoints

8. MCP Tools

12 KiB

Raw Blame History