bytelyst/learning_ai_notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
513ee5a6a5
learning_ai_notes/AGENTS.md
saravanakumardb1 724a6659df docs: update AGENTS.md with api-helpers.ts and corrected test counts 
- Added api-helpers.ts to web lib repo layout
- Backend tests: 18 → 19 (11 files) after saved-views route test
2026-03-10 19:57:40 -07:00

243 lines
13 KiB
Markdown
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`](docs/PRD.md) for full product spec, [`docs/ROADMAP.md`](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
│ │ ├── api-helpers.ts # Shared getAccessToken() + createNotesApiClient()
│ │ ├── 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 — 19 backend tests (11 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
```bash
# ── Backend ────────────────────────────────────────
cd backend && npm run dev # Dev server (port 4016)
cd backend && npm run typecheck # tsc --noEmit
cd backend && npm test # 19 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 |
Reference in New Issue View Git Blame Copy Permalink