132 lines
4.8 KiB
Markdown
132 lines
4.8 KiB
Markdown
# 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 |