bytelyst/learning_ai_notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
backup-main-20260530
learning_ai_notes/REPO_CONTEXT.md
root 95fc262006 chore: add agent context docs
2026-05-27 18:41:32 +00:00

4.8 KiB
Raw Permalink Blame History

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

# 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

# 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

# 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