chore: add agent context docs
This commit is contained in:
root
parent
5687e5ace1
commit
95fc262006
1
.claude/AGENTS.md
Normal file
1
.claude/AGENTS.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
Refer to ../REPO_CONTEXT.md for repository overview and ../AGENTS.md for complete project instructions.
|
||||||
1
.cline/AGENTS.md
Normal file
1
.cline/AGENTS.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
Refer to ../REPO_CONTEXT.md for repository overview and ../AGENTS.md for complete project instructions.
|
||||||
1
.cursor/AGENTS.md
Normal file
1
.cursor/AGENTS.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
Refer to ../REPO_CONTEXT.md for repository overview and ../AGENTS.md for complete project instructions.
|
||||||
206
.devin/AGENTS.md
Normal file
206
.devin/AGENTS.md
Normal file
@ -0,0 +1,206 @@
|
|||||||
|
# ByteLyst NoteLett - Agent Instructions
|
||||||
|
|
||||||
|
> This file is read automatically by Claude Code. For full project instructions
|
||||||
|
> shared across all AI tools, see [`CONTEXT.md`](CONTEXT.md).
|
||||||
|
|
||||||
|
## Critical Deployment Patterns (Learned from Production Deployment)
|
||||||
|
|
||||||
|
### 1. Docker Build Preparation
|
||||||
|
**Before building Docker images, you MUST run the dependency packing script:**
|
||||||
|
```bash
|
||||||
|
bash scripts/docker-prep.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
This script:
|
||||||
|
- Builds all @bytelyst/* packages from learning_ai_common_plat
|
||||||
|
- Packs them as tarballs in `.docker-deps/`
|
||||||
|
- Rewrites package.json files to reference the tarballs
|
||||||
|
- Injects pnpm.overrides for version consistency
|
||||||
|
|
||||||
|
**After building, ALWAYS restore the package.json files:**
|
||||||
|
```bash
|
||||||
|
bash scripts/docker-prep.sh --restore
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Dockerfile Configuration
|
||||||
|
**Dockerfiles MUST be updated to remove Gitea secrets and use .docker-deps:**
|
||||||
|
|
||||||
|
**Backend Dockerfile changes:**
|
||||||
|
- Remove `--mount=type=secret,id=gitea_npm_token` lines
|
||||||
|
- Remove TOKEN environment setup
|
||||||
|
- Add `COPY .docker-deps/ ../.docker-deps/` before install
|
||||||
|
- Simplified install command: `RUN pnpm install --ignore-scripts --lockfile=false`
|
||||||
|
|
||||||
|
**Web Dockerfile changes:**
|
||||||
|
- Remove `--mount=type=secret,id=gitea_npm_token` lines
|
||||||
|
- Remove GITEA_NPM_TOKEN environment setup
|
||||||
|
- Ensure .docker-deps is copied before install
|
||||||
|
|
||||||
|
### 3. Public API URL Configuration
|
||||||
|
**NEXT_PUBLIC_ environment variables MUST use public URLs, not internal Docker network names:**
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
```yaml
|
||||||
|
NEXT_PUBLIC_NOTES_API_URL: http://localhost:4016/api
|
||||||
|
NEXT_PUBLIC_NOTES_API_URL: http://backend:4011
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct:**
|
||||||
|
```yaml
|
||||||
|
NEXT_PUBLIC_NOTES_API_URL: https://api.bytelyst.com/notelett
|
||||||
|
```
|
||||||
|
|
||||||
|
This is because browsers cannot access internal Docker network names. The web app needs to connect to the public API endpoint.
|
||||||
|
|
||||||
|
### 4. Docker Compose Environment Variable Format
|
||||||
|
**Use YAML mapping syntax, NOT array syntax:**
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
```yaml
|
||||||
|
environment:
|
||||||
|
- NODE_ENV=production
|
||||||
|
- PORT=4016
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct:**
|
||||||
|
```yaml
|
||||||
|
environment:
|
||||||
|
NODE_ENV: production
|
||||||
|
PORT: 4016
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Production vs Development Mode
|
||||||
|
**Production mode (NODE_ENV=production) requires:**
|
||||||
|
- DB_PROVIDER: cosmos (not memory)
|
||||||
|
- FIELD_ENCRYPT_ENABLED: true (not false)
|
||||||
|
- FIELD_ENCRYPT_KEY_PROVIDER: akv or env (not memory)
|
||||||
|
|
||||||
|
**If these are not configured, use development mode:**
|
||||||
|
```yaml
|
||||||
|
NODE_ENV: development
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Container Names for Caddy Routing
|
||||||
|
**Container names MUST match Caddyfile configuration:**
|
||||||
|
- Backend: `notelett-backend`
|
||||||
|
- Web: `notelett-web`
|
||||||
|
|
||||||
|
Add to docker-compose.yml:
|
||||||
|
```yaml
|
||||||
|
services:
|
||||||
|
backend:
|
||||||
|
container_name: notelett-backend
|
||||||
|
web:
|
||||||
|
container_name: notelett-web
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Caddy Network Connectivity
|
||||||
|
**Caddy MUST be connected to the app networks for reverse proxy:**
|
||||||
|
```bash
|
||||||
|
docker network connect learning_ai_notes_default caddy
|
||||||
|
docker network connect learning_ai_common_plat_default caddy
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. DNS Configuration
|
||||||
|
**For new subdomains, add DNS records via GoDaddy API:**
|
||||||
|
```bash
|
||||||
|
# Example for notes.bytelyst.com
|
||||||
|
curl -X PUT "https://api.godaddy.com/v1/domains/bytelyst.com/records/A/notes" \
|
||||||
|
-H "Authorization: sso-key $GODADDY_API_KEY:$GODADDY_API_SECRET" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '[{"data": "187.124.159.82", "name": "notes", "ttl": 600, "type": "A"}]'
|
||||||
|
```
|
||||||
|
|
||||||
|
Use the same IP as other bytelyst.com subdomains (187.124.159.82).
|
||||||
|
|
||||||
|
### 9. Caddy Configuration Pattern
|
||||||
|
**Add subdomain routing to /opt/bytelyst/Caddyfile:**
|
||||||
|
```caddy
|
||||||
|
notes.bytelyst.com {
|
||||||
|
encode gzip
|
||||||
|
reverse_proxy notelett-web:3045
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Then reload Caddy:
|
||||||
|
```bash
|
||||||
|
docker exec caddy caddy reload --config /etc/caddy/Caddyfile
|
||||||
|
```
|
||||||
|
|
||||||
|
### 10. Deployment Script Usage
|
||||||
|
**ALWAYS use the deployment script from learning_ai_devops_tools:**
|
||||||
|
```bash
|
||||||
|
cd ../learning_ai_devops_tools
|
||||||
|
bash deploy-notes.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
Options:
|
||||||
|
- Option 1: Normal deployment (with cache, with health checks)
|
||||||
|
- Option 5: Force + No-cache (skip checks, force rebuild) - use when config changes
|
||||||
|
- Option 6: Force + Skip health checks (skip both) - use when health checks are flaky
|
||||||
|
|
||||||
|
## Deployment Checklist
|
||||||
|
|
||||||
|
Before deploying:
|
||||||
|
1. [ ] Run `bash scripts/docker-prep.sh` to package dependencies
|
||||||
|
2. [ ] Update Dockerfiles to remove Gitea secrets and use .docker-deps
|
||||||
|
3. [ ] Set NEXT_PUBLIC_ variables to use public API URLs
|
||||||
|
4. [ ] Use YAML mapping syntax for environment variables
|
||||||
|
5. [ ] Set correct NODE_ENV (development unless Cosmos/AKV configured)
|
||||||
|
6. [ ] Set container names to match Caddyfile
|
||||||
|
7. [ ] Update Caddyfile with subdomain routing
|
||||||
|
8. [ ] Add DNS records via GoDaddy API
|
||||||
|
9. [ ] Connect Caddy to app networks
|
||||||
|
10. [ ] Run deployment script with appropriate options
|
||||||
|
|
||||||
|
After deploying:
|
||||||
|
1. [ ] Run `bash scripts/docker-prep.sh --restore` to restore package.json
|
||||||
|
2. [ ] Test public URL accessibility
|
||||||
|
3. [ ] Test API endpoint accessibility
|
||||||
|
4. [ ] Verify SSL certificates are working
|
||||||
|
5. [ ] Check container logs for errors
|
||||||
|
6. [ ] Commit and push changes
|
||||||
|
|
||||||
|
## Common Deployment Errors and Solutions
|
||||||
|
|
||||||
|
### Error: "failed to calculate checksum of ref: /.docker-deps: not found"
|
||||||
|
**Solution:** Run `bash scripts/docker-prep.sh` before building
|
||||||
|
|
||||||
|
### Error: "HTTP 400 urn:ietf:params:acme:error:dns - DNS problem: NXDOMAIN"
|
||||||
|
**Solution:** DNS records not propagated yet. Wait 5-30 minutes after adding DNS records, then restart Caddy.
|
||||||
|
|
||||||
|
### Error: "Production DB_PROVIDER must be cosmos"
|
||||||
|
**Solution:** Either configure Cosmos DB credentials or set NODE_ENV to development
|
||||||
|
|
||||||
|
### Error: "services.web.environment.[3]: unexpected type map[string]interface {}"
|
||||||
|
**Solution:** Convert environment variables from array syntax to YAML mapping syntax
|
||||||
|
|
||||||
|
### Error: React hydration errors or backend connection failures
|
||||||
|
**Solution:** Check that NEXT_PUBLIC_ variables use public API URLs, not internal Docker network names
|
||||||
|
|
||||||
|
## Quick Deployment Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Prepare dependencies
|
||||||
|
bash scripts/docker-prep.sh
|
||||||
|
|
||||||
|
# Deploy
|
||||||
|
cd ../learning_ai_devops_tools
|
||||||
|
echo "5" | bash deploy-notes.sh # Force + No-cache
|
||||||
|
|
||||||
|
# Restore after deployment
|
||||||
|
bash scripts/docker-prep.sh --restore
|
||||||
|
|
||||||
|
# Test
|
||||||
|
curl -I https://notes.bytelyst.com
|
||||||
|
curl -s https://api.bytelyst.com/notelett/health
|
||||||
|
```
|
||||||
|
|
||||||
|
## Key Files for Deployment
|
||||||
|
|
||||||
|
- `docker-compose.yml` - Container configuration
|
||||||
|
- `backend/Dockerfile` - Backend container build
|
||||||
|
- `web/Dockerfile` - Web container build
|
||||||
|
- `scripts/docker-prep.sh` - Dependency packaging script
|
||||||
|
- `/opt/bytelyst/Caddyfile` - Reverse proxy configuration
|
||||||
|
- `../learning_ai_devops_tools/deploy-notes.sh` - Deployment script
|
||||||
226
.devin/CONTEXT.md
Normal file
226
.devin/CONTEXT.md
Normal file
@ -0,0 +1,226 @@
|
|||||||
|
# ByteLyst NoteLett - Project Context
|
||||||
|
|
||||||
|
> **Purpose**: This file provides project-specific context for AI coding agents working in this repository.
|
||||||
|
|
||||||
|
## Companion Repositories (Always Available)
|
||||||
|
|
||||||
|
This repository has access to these companion repositories:
|
||||||
|
|
||||||
|
- **learning_ai_common_plat** - Platform packages (@bytelyst/*)
|
||||||
|
- Context: `learning_ai_common_plat/REPO_CONTEXT.md`
|
||||||
|
- Provides: Shared libraries, configuration, auth, cosmos, telemetry, etc.
|
||||||
|
- Location: `../learning_ai_common_plat/`
|
||||||
|
|
||||||
|
- **learning_ai_devops_tools** - Deployment and operational scripts
|
||||||
|
- Context: `learning_ai_devops_tools/REPO_CONTEXT.md`
|
||||||
|
- Provides: Deployment scripts, GitHub tools, operational automation
|
||||||
|
- Location: `../learning_ai_devops_tools/`
|
||||||
|
|
||||||
|
## Project Overview
|
||||||
|
|
||||||
|
**ByteLyst NoteLett** - Agentic note-taking workspace for notes, tasks, relationships, and workspaces with:
|
||||||
|
- AI-powered note organization and linking
|
||||||
|
- Smart Actions with prompt templates
|
||||||
|
- Cross-product transcript and trail report imports
|
||||||
|
- MCP (Model Context Protocol) integration for external tools
|
||||||
|
- Multi-platform support (Web, iOS, Android)
|
||||||
|
|
||||||
|
## Key Locations
|
||||||
|
|
||||||
|
### Source Code
|
||||||
|
- **Backend**: `backend/` - Fastify 5 + TypeScript ESM backend (port 4016)
|
||||||
|
- **Web**: `web/` - Next.js 16 + React 19 web app (port 3045)
|
||||||
|
- **Mobile**: `mobile/` - React Native + Expo companion app
|
||||||
|
- **Shared**: `shared/` - Shared TypeScript utilities
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
- **Backend Config**: `backend/src/lib/config.ts` - Zod-validated env config
|
||||||
|
- **Docker Config**: `docker-compose.yml` - Container orchestration
|
||||||
|
- **TypeScript Config**: `backend/tsconfig.json`, `web/tsconfig.json`
|
||||||
|
|
||||||
|
### Documentation
|
||||||
|
- **Product Docs**: `docs/PRD.md`, `docs/ROADMAP.md`
|
||||||
|
- **Production Readiness**: `docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md`
|
||||||
|
- **UI/UX Migration**: `docs/UI_UX_PLATFORM_CORE_ROADMAP.md`
|
||||||
|
|
||||||
|
## Deployment Patterns
|
||||||
|
|
||||||
|
### Primary Deployment Method
|
||||||
|
- **Script**: `learning_ai_devops_tools/deploy-notes.sh`
|
||||||
|
- **Usage**: Always check this script first before attempting custom deployment
|
||||||
|
- **Pattern**: Interactive menu with options for cache, force, and health checks
|
||||||
|
- **Features**:
|
||||||
|
- Package publication checks
|
||||||
|
- --no-cache support
|
||||||
|
- Health verification
|
||||||
|
- Dirty checks
|
||||||
|
|
||||||
|
### Deployment Requirements
|
||||||
|
- **GITEA_NPM_TOKEN**: Required for @bytelyst/* package installation
|
||||||
|
- **Network**: Access to Gitea registry for package installation
|
||||||
|
- **Build Order**: learning_ai_common_plat → this project
|
||||||
|
|
||||||
|
## MCP Integration
|
||||||
|
|
||||||
|
### MCP Components
|
||||||
|
- **MCP Tool Contracts**: `backend/src/mcp/note-tool-contracts.ts`
|
||||||
|
- **MCP Tools**: `backend/src/mcp/note-tools.ts`
|
||||||
|
- **MCP Registration**: `backend/src/mcp/register-note-tools.ts`
|
||||||
|
|
||||||
|
### MCP Features
|
||||||
|
- **8 MCP Tools**: Note CRUD, search, relationships, artifacts, etc.
|
||||||
|
- **Zod Schemas**: Type-safe tool definitions
|
||||||
|
- **Integration**: Fastify plugin for automatic registration
|
||||||
|
|
||||||
|
### MCP Configuration
|
||||||
|
- **Environment Variables**:
|
||||||
|
- `MCP_SERVER_URL`: MCP server endpoint
|
||||||
|
- `MCP_ENABLED`: Feature flag (default: true)
|
||||||
|
|
||||||
|
## Architecture Patterns
|
||||||
|
|
||||||
|
### Backend Architecture
|
||||||
|
- **Framework**: Fastify 5 with TypeScript ESM
|
||||||
|
- **Database**: Azure Cosmos DB via @bytelyst/datastore
|
||||||
|
- **Platform Integration**: platform-service (port 4003) for auth, flags, telemetry
|
||||||
|
- **Extraction**: extraction-service (port 4005) for AI-powered task extraction
|
||||||
|
- **LLM**: @bytelyst/llm with retry + timeout hardening
|
||||||
|
|
||||||
|
### Frontend Architecture
|
||||||
|
- **Framework**: Next.js 16 (App Router) + React 19
|
||||||
|
- **State Management**: Zustand + localStorage
|
||||||
|
- **UI Components**: @bytelyst/ui + custom components
|
||||||
|
- **Styling**: TailwindCSS v4 + design tokens (--nl-*)
|
||||||
|
|
||||||
|
### Mobile Architecture
|
||||||
|
- **Framework**: React Native + Expo
|
||||||
|
- **State Management**: Zustand + MMKV
|
||||||
|
- **Navigation**: Expo Router
|
||||||
|
- **Theme**: NoteLystTheme from design tokens
|
||||||
|
|
||||||
|
## Common Operations
|
||||||
|
|
||||||
|
### Backend Development
|
||||||
|
```bash
|
||||||
|
cd backend
|
||||||
|
npm run dev # Start backend in dev mode
|
||||||
|
npm run build # Build TypeScript
|
||||||
|
npm run test # Run tests
|
||||||
|
```
|
||||||
|
|
||||||
|
### Web Development
|
||||||
|
```bash
|
||||||
|
cd web
|
||||||
|
npm run dev # Start Next.js dev server
|
||||||
|
npm run build # Production build (uses --webpack flag)
|
||||||
|
npm run test # Run Vitest tests
|
||||||
|
```
|
||||||
|
|
||||||
|
### Mobile Development
|
||||||
|
```bash
|
||||||
|
cd mobile
|
||||||
|
npm start # Start Expo dev server
|
||||||
|
```
|
||||||
|
|
||||||
|
### Docker Development
|
||||||
|
```bash
|
||||||
|
docker compose up # Start all containers
|
||||||
|
docker compose down # Stop all containers
|
||||||
|
```
|
||||||
|
|
||||||
|
## Important Notes
|
||||||
|
|
||||||
|
### Platform Integration
|
||||||
|
- **platform-service**: Used for auth, billing, flags, telemetry, blob storage
|
||||||
|
- **extraction-service**: Used for AI-powered task extraction from notes
|
||||||
|
- **Product ID**: "notelett" (required for all Cosmos documents)
|
||||||
|
|
||||||
|
### Feature Flags
|
||||||
|
- **20 Feature Flags**: Core + Smart Actions features
|
||||||
|
- **Client**: @bytelyst/feature-flag-client
|
||||||
|
- **Backend**: backend/src/lib/feature-flags.ts
|
||||||
|
|
||||||
|
### Design System
|
||||||
|
- **Tokens**: @bytelyst/design-tokens (--nl-* CSS custom properties)
|
||||||
|
- **Components**: @bytelyst/ui (Button, Card, Badge, Toast, etc.)
|
||||||
|
- **Never hardcode colors**: Always use theme tokens
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
### Backend Tests
|
||||||
|
- **Framework**: Vitest
|
||||||
|
- **Coverage**: All modules (notes, workspaces, relationships, tasks, etc.)
|
||||||
|
- **Location**: `backend/src/modules/*/test.ts`
|
||||||
|
|
||||||
|
### Web Tests
|
||||||
|
- **Framework**: Vitest + Playwright
|
||||||
|
- **Coverage**: Components, E2E flows
|
||||||
|
- **Location**: `web/src/*.dom.test.tsx`, `web/e2e/`
|
||||||
|
|
||||||
|
### Mobile Tests
|
||||||
|
- **Framework**: Expo Test (planned)
|
||||||
|
|
||||||
|
## Common Issues and Solutions
|
||||||
|
|
||||||
|
### Platform Integration Issues
|
||||||
|
- **"platform-service unreachable"**: Check PLATFORM_SERVICE_URL
|
||||||
|
- **"Feature flag not found"**: Verify feature flag configuration
|
||||||
|
- **"Telemetry disabled"**: Check TELEMETRY_ENABLED setting
|
||||||
|
|
||||||
|
### Deployment Issues
|
||||||
|
- **"Cannot find module @bytelyst/..."**: Build learning_ai_common_plat packages first
|
||||||
|
- **"Gitea registry unauthorized"**: Check GITEA_NPM_TOKEN
|
||||||
|
- **"Docker build network error"**: Ensure proper network access
|
||||||
|
|
||||||
|
### Development Issues
|
||||||
|
- **Port conflicts**: Backend (4016), Web (3045)
|
||||||
|
- **Environment variables**: Copy backend/.env.example to backend/.env
|
||||||
|
- **TypeScript errors**: Run `npm run build` to see full error messages
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
| Task | Command |
|
||||||
|
|------|---------|
|
||||||
|
| Start development | `cd backend && npm run dev` |
|
||||||
|
| Build backend | `cd backend && npm run build` |
|
||||||
|
| Build web | `cd web && npm run build -- --webpack` |
|
||||||
|
| Deploy | `../learning_ai_devops_tools/deploy-notes.sh` |
|
||||||
|
| Run tests | `cd backend && npm run test` |
|
||||||
|
| Docker compose | `docker compose up -d` |
|
||||||
|
|
||||||
|
## First Steps for Any Task
|
||||||
|
|
||||||
|
1. **Check companion repo contexts**:
|
||||||
|
- Read `learning_ai_common_plat/REPO_CONTEXT.md` for package patterns
|
||||||
|
- Read `learning_ai_devops_tools/REPO_CONTEXT.md` for deployment patterns
|
||||||
|
|
||||||
|
2. **Check deployment scripts**:
|
||||||
|
- Look for `learning_ai_devops_tools/deploy-notes.sh`
|
||||||
|
- Don't build custom deployment solutions
|
||||||
|
|
||||||
|
3. **Check project-specific context**:
|
||||||
|
- Product docs: `docs/PRD.md`, `docs/ROADMAP.md`
|
||||||
|
- Production readiness: `docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md`
|
||||||
|
|
||||||
|
4. **Verify environment setup**:
|
||||||
|
- Check backend/.env is configured
|
||||||
|
- Ensure GITEA_NPM_TOKEN is set for deployment
|
||||||
|
|
||||||
|
## Project-Specific Patterns
|
||||||
|
|
||||||
|
### Note CRUD Pattern
|
||||||
|
1. Types: Define Zod schemas in `types.ts`
|
||||||
|
2. Repository: Use @bytelyst/datastore getCollection()
|
||||||
|
3. Routes: Fastify routes with validation
|
||||||
|
4. All documents include `productId: "notelett"`
|
||||||
|
|
||||||
|
### Smart Actions Pattern
|
||||||
|
1. Prompt Templates: Stored in note-prompts module
|
||||||
|
2. Runner: executePrompt() with retry + timeout
|
||||||
|
3. Scheduler: Cron schedules + webhook triggers
|
||||||
|
4. Integration: Web UI for template management
|
||||||
|
|
||||||
|
### Cross-Product Integration
|
||||||
|
1. Phase 1: Transcript import from LysnrAI
|
||||||
|
2. Phase 3: Trail report import from ActionTrail
|
||||||
|
3. Helpers: backend/src/lib/ecosystem-phase*.ts
|
||||||
1
.windsurf/AGENTS.md
Normal file
1
.windsurf/AGENTS.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
Refer to ../REPO_CONTEXT.md for repository overview and ../AGENTS.md for complete project instructions.
|
||||||
132
REPO_CONTEXT.md
Normal file
132
REPO_CONTEXT.md
Normal file
@ -0,0 +1,132 @@
|
|||||||
|
# ByteLyst NoteLett - Repository Context
|
||||||
|
|
||||||
|
> **Purpose**: This file provides quick context for AI coding agents about what this repository contains and how to use it effectively.
|
||||||
|
|
||||||
|
## What This Repository Provides
|
||||||
|
|
||||||
|
This is the **NoteLett product repository** for the ByteLyst ecosystem. It contains:
|
||||||
|
|
||||||
|
- **Agentic note-taking platform** with notes, tasks, relationships, and workspaces
|
||||||
|
- **Multi-platform support**: Web (Next.js 16), iOS (React Native), Android (React Native)
|
||||||
|
- **Smart Actions**: AI-powered prompt templates and automation
|
||||||
|
- **MCP Integration**: Model Context Protocol for external tool integration
|
||||||
|
- **Cross-product imports**: Transcript and trail report imports from other ByteLyst products
|
||||||
|
|
||||||
|
## Companion Repositories (Always Available)
|
||||||
|
|
||||||
|
This repository has access to these companion repositories:
|
||||||
|
|
||||||
|
- **learning_ai_common_plat** - Platform packages (@bytelyst/*)
|
||||||
|
- Context: `../learning_ai_common_plat/REPO_CONTEXT.md`
|
||||||
|
- Provides: Shared libraries, configuration, auth, cosmos, telemetry, etc.
|
||||||
|
- Location: `../learning_ai_common_plat/`
|
||||||
|
|
||||||
|
- **learning_ai_devops_tools** - Deployment and operational scripts
|
||||||
|
- Context: `../learning_ai_devops_tools/REPO_CONTEXT.md`
|
||||||
|
- Provides: Deployment scripts, GitHub tools, operational automation
|
||||||
|
- Location: `../learning_ai_devops_tools/`
|
||||||
|
|
||||||
|
## Key Locations
|
||||||
|
|
||||||
|
### Source Code
|
||||||
|
- **Backend**: `backend/` - Fastify 5 + TypeScript ESM backend (port 4016)
|
||||||
|
- `backend/src/modules/` - Feature modules (notes, workspaces, relationships, tasks, etc.)
|
||||||
|
- `backend/src/lib/` - Shared backend utilities
|
||||||
|
- **Web**: `web/` - Next.js 16 + React 19 web app (port 3045)
|
||||||
|
- `web/src/app/` - App Router pages
|
||||||
|
- `web/src/components/` - React UI components
|
||||||
|
- `web/src/lib/` - Pure TS client libraries
|
||||||
|
- **Mobile**: `mobile/` - React Native + Expo companion app
|
||||||
|
- `mobile/src/app/` - Expo Router screens
|
||||||
|
- `mobile/src/api/` - API clients
|
||||||
|
- `mobile/src/store/` - Zustand stores
|
||||||
|
- **Shared**: `shared/` - Shared TypeScript utilities and product config
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
- **Backend Config**: `backend/src/lib/config.ts` - Zod-validated env config
|
||||||
|
- **Web Config**: `web/src/lib/product-config.ts` - Product identity + API URLs
|
||||||
|
- **Docker Config**: `docker-compose.yml` - Container orchestration
|
||||||
|
- **TypeScript Config**: `backend/tsconfig.json`, `web/tsconfig.json`, `mobile/tsconfig.json`
|
||||||
|
|
||||||
|
### Documentation
|
||||||
|
- **Product Docs**: `docs/PRD.md`, `docs/ROADMAP.md`
|
||||||
|
- **Production Readiness**: `docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md`
|
||||||
|
- **UI/UX Migration**: `docs/UI_UX_PLATFORM_CORE_ROADMAP.md`
|
||||||
|
- **AI Agent Instructions**: `AGENTS.md` (complete instructions for all tools)
|
||||||
|
|
||||||
|
### Deployment
|
||||||
|
- **Docker Prep**: `scripts/docker-prep.sh` - Package @bytelyst/* dependencies
|
||||||
|
- **Deployment Script**: `../learning_ai_devops_tools/deploy-notes.sh`
|
||||||
|
- **Dockerfiles**: `backend/Dockerfile`, `web/Dockerfile`
|
||||||
|
|
||||||
|
## Common Usage Patterns
|
||||||
|
|
||||||
|
### Development
|
||||||
|
```bash
|
||||||
|
# Install dependencies
|
||||||
|
pnpm install
|
||||||
|
|
||||||
|
# Backend development
|
||||||
|
pnpm --filter @notelett/backend run dev
|
||||||
|
|
||||||
|
# Web development
|
||||||
|
pnpm --filter @notelett/web run dev
|
||||||
|
|
||||||
|
# Mobile development
|
||||||
|
pnpm --filter @notelett/mobile run start
|
||||||
|
|
||||||
|
# Full verification
|
||||||
|
pnpm run verify
|
||||||
|
```
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
```bash
|
||||||
|
# Backend tests
|
||||||
|
pnpm --filter @notelett/backend run test
|
||||||
|
|
||||||
|
# Web tests
|
||||||
|
pnpm --filter @notelett/web run test
|
||||||
|
|
||||||
|
# Mobile tests
|
||||||
|
pnpm --filter @notelett/mobile run test
|
||||||
|
```
|
||||||
|
|
||||||
|
### Docker Build
|
||||||
|
```bash
|
||||||
|
# Prepare dependencies (REQUIRED before Docker build)
|
||||||
|
bash scripts/docker-prep.sh
|
||||||
|
|
||||||
|
# Build containers
|
||||||
|
docker-compose build
|
||||||
|
|
||||||
|
# Restore after build
|
||||||
|
bash scripts/docker-prep.sh --restore
|
||||||
|
```
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
|
||||||
|
| Layer | Technology |
|
||||||
|
|-------|-----------|
|
||||||
|
| **Backend** | Fastify 5, TypeScript ESM, Zod, Azure Cosmos DB |
|
||||||
|
| **Web** | Next.js 16 (App Router), React 19, TailwindCSS v4, Zustand |
|
||||||
|
| **Mobile** | React Native (Expo), TypeScript, expo-router, Zustand |
|
||||||
|
| **Shared packages** | @bytelyst/* from learning_ai_common_plat |
|
||||||
|
| **Platform** | platform-service (port 4003) for auth, flags, telemetry |
|
||||||
|
| **Database** | Azure Cosmos DB via @bytelyst/datastore |
|
||||||
|
| **LLM** | @bytelyst/llm (mock/openai/azure providers) |
|
||||||
|
|
||||||
|
## Important Notes
|
||||||
|
|
||||||
|
- **Product ID**: `notelett` (used in all Cosmos documents)
|
||||||
|
- **Package scope**: @notelett/* for workspace packages
|
||||||
|
- **Shared packages**: Uses @bytelyst/* from learning_ai_common_plat
|
||||||
|
- **Docker prep**: MUST run `scripts/docker-prep.sh` before Docker builds
|
||||||
|
- **Deployment**: ALWAYS use `../learning_ai_devops_tools/deploy-notes.sh`
|
||||||
|
|
||||||
|
## First Steps for AI Agents
|
||||||
|
|
||||||
|
1. **Read REPO_CONTEXT.md** (this file) - Understand the repository structure
|
||||||
|
2. **Read AGENTS.md** - Complete coding conventions and instructions
|
||||||
|
3. **Check companion repos** - learning_ai_common_plat and learning_ai_devops_tools
|
||||||
|
4. **Understand the stack** - Fastify backend, Next.js web, React Native mobile
|
||||||
|
5. **Follow deployment patterns** - Use docker-prep.sh and deployment scripts
|
||||||
@ -10,8 +10,15 @@ export default defineConfig({
|
|||||||
// without Docker still get green locally.
|
// without Docker still get green locally.
|
||||||
exclude: ['**/node_modules/**', 'src/**/*.cosmos.test.ts'],
|
exclude: ['**/node_modules/**', 'src/**/*.cosmos.test.ts'],
|
||||||
passWithNoTests: true,
|
passWithNoTests: true,
|
||||||
|
// Some backend integration-style route tests build Fastify apps and import
|
||||||
|
// shared common-platform packages. On cold CI/dev hosts those first tests can
|
||||||
|
// legitimately spend more than Vitest's 5s default in transform/route setup
|
||||||
|
// before the actual assertion path runs. Keep the limit bounded, but high
|
||||||
|
// enough to avoid false negative launch-gate failures.
|
||||||
|
testTimeout: 15_000,
|
||||||
|
hookTimeout: 15_000,
|
||||||
env: {
|
env: {
|
||||||
ALLOW_ANONYMOUS_DEV: 'true',
|
ALLOW_ANONYMOUS_DEV: 'true',
|
||||||
},
|
}
|
||||||
},
|
},
|
||||||
});
|
});
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user