Skip to content

Latest commit

 

History

History
376 lines (261 loc) · 9.29 KB

CLAUDE.md

File metadata and controls

376 lines (261 loc) · 9.29 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

laf is an open-source serverless cloud development platform that provides cloud functions, cloud databases, and cloud storage out of the box. It enables developers to focus on business development without worrying about server management.

The platform consists of:

  • Web IDE: Browser-based development environment for writing cloud functions
  • Cloud Functions: Serverless function execution (Node.js/Python)
  • Cloud Database: MongoDB-based database with access control
  • Cloud Storage: S3-compatible object storage (MinIO)
  • Website Hosting: Static site deployment

Repository Structure

This is a monorepo managed by Lerna. Key workspaces:

Core Services

  • server/ - NestJS-based API server that manages the entire laf platform

    • Handles auth, applications, functions, database, storage, logs, billing, domains, certificates, and metrics
    • Uses MongoDB for system database
    • Runs on port 3000

  • runtimes/nodejs/ - Node.js runtime engine that executes user cloud functions

    • Express-based runtime that executes cloud functions
    • Provides database access proxy
    • Includes TypeScript language server for IDE support
    • Each application instance runs its own runtime pod in Kubernetes

  • web/ - React-based web console UI

    • Built with Vite, React 18, Chakra UI, TailwindCSS
    • Monaco editor integration for code editing
    • Uses React Query for state management and Zustand for local state
    • Runs on port 3001 (dev)

Packages

  • packages/client-sdk/ - Client SDK for accessing laf from frontend applications
  • packages/cloud-sdk/ (@lafjs/cloud) - SDK provided to cloud functions at runtime
  • packages/database-proxy/ - Database access layer with ACL support (MongoDB/MySQL)
  • packages/database-ql/ - Query language abstraction
  • packages/node-modules-utils/ - Utilities for managing npm dependencies
  • packages/eslint-config-laf/ - Shared ESLint configuration

Other

  • cli/ - Command-line tool for laf
  • e2e/ - End-to-end tests using Jest
  • docs/ - VitePress documentation
  • deploy/ - Kubernetes deployment manifests
  • services/runtime-exporter/ - Prometheus exporter for runtime metrics

Development Commands

Root Level (Monorepo)

# Install all dependencies across workspaces
npm install
# Or with lerna
lerna exec npm install --parallel

# Build all packages
npm run build
# Or
lerna run build --parallel

# Lint all packages
npm run lint
# Or
lerna run lint --parallel

# Run lint-staged (pre-commit)
npm run lint-staged

Server Development

cd server/

# Install dependencies
npm install

# Development with watch mode
npm run dev
# Or
npm run watch

# Build
npm run build

# Start production
npm run start:prod

# Run tests
npm test
npm run test:watch
npm run test:cov
npm run test:e2e

# Lint
npm run lint

Local development with Telepresence (connects to Kubernetes cluster):

cd server/

# Install traffic manager
telepresence helm install

# Connect to cluster
telepresence connect -n laf-system

# Intercept traffic (creates .env file)
telepresence intercept laf-server -p 3000:3000 -e $(pwd)/.env

# Start dev server
npm run dev

# Clean up
telepresence leave laf-server

Web Development

cd web/

# Install dependencies (uses pnpm or npm)
npm install
# Or
pnpm install

# Development server
npm run dev

# Build for production
npm run build

# Type check
npm run tsc

# Preview production build
npm run preview

# Lint
npm run lint

Runtime Development

cd runtimes/nodejs/

# Install and build
npm install
npm run build

# Development
npm run dev
npm run watch

# Start
npm start

# Lint
npm run lint

Local development with Telepresence:

cd runtimes/nodejs/

# Connect to cluster
telepresence connect -n laf-system

# Set your test app ID
export appid=your-app-id

# Intercept app traffic
telepresence intercept $appid -p 8000:8000 -e $(pwd)/.env

# Start runtime
npm run build
npm start

# Clean up
telepresence leave $appid

Package Development

# Example: database-proxy
cd packages/database-proxy/

npm install
npm run build
npm run watch  # Watch mode
npm test       # Run tests
npm run lint

E2E Tests

cd e2e/

# Run all tests
npm test

# Or use the shell script
./e2e.sh

CLI Development

cd cli/

npm install
npm run build
npm run watch

# Use locally
node dist/main.js

Architecture Overview

Request Flow

  1. User accesses web console (web/) to manage applications and write functions
  2. Web console communicates with API server (server/) via REST APIs
  3. API server manages Kubernetes resources to create application instances
  4. Each application gets its own runtime pod (runtimes/nodejs/)
  5. Runtime pods execute user-defined cloud functions
  6. Cloud functions use cloud-sdk to access database (via database-proxy) and storage

Key Architecture Patterns

Serverless Isolation: Each laf application runs in its own Kubernetes pod with isolated resources, database credentials, and storage buckets.

Database Access Control: The database-proxy package provides MongoDB/MySQL access with ACL rules. Cloud functions don't connect directly to databases; they use the proxy with permission validation.

Function Execution: Cloud functions are TypeScript/JavaScript code stored in MongoDB. The runtime loads function code dynamically and executes it in isolated contexts with injected globals (cloud, fetch, etc.).

WebIDE Integration: Monaco editor in web console connects to TypeScript language server running in the runtime pod via WebSocket for IntelliSense and type checking.

Technology Stack

Backend:

  • NestJS 9 (server)
  • Express 4 (runtime)
  • MongoDB 5 (database)
  • Kubernetes client-node
  • Passport JWT (authentication)

Frontend:

  • React 18
  • Chakra UI + TailwindCSS
  • Monaco Editor
  • React Query (TanStack Query)
  • Zustand + Immer (state management)
  • i18next (internationalization)
  • Vite 4

Infrastructure:

  • Kubernetes (orchestration)
  • MinIO (object storage)
  • Telepresence (local development)

Important Conventions

Code Organization

  • Server uses NestJS modules - each feature has its own module in server/src/
  • Runtime handlers are in runtimes/nodejs/src/handler/
  • Web pages follow feature-based organization in web/src/pages/
  • Shared types and utilities should go in appropriate packages

TypeScript

  • All packages use TypeScript
  • Server uses TypeScript 4.9
  • Web and newer packages use TypeScript 5.0
  • Build target varies by package (check individual tsconfig.json)

Testing

  • Server uses Jest with NestJS testing utilities
  • E2E tests use Jest with custom sequencer for test ordering
  • Package tests use Mocha
  • Test files use *.spec.ts (server) or *test.js (packages)

Linting

  • Shared ESLint config in packages/eslint-config-laf/
  • Husky pre-commit hooks run lint-staged
  • Run npm run lint to fix issues automatically

Building

  • Most packages require npm run build before use
  • Lerna can build all packages in parallel
  • Runtime requires build before starting
  • Web uses Vite for hot module replacement in dev

Working with the Codebase

Adding a New API Endpoint

  1. Create or modify a controller in server/src/{module}/
  2. Add DTOs with class-validator decorators
  3. Add Swagger decorators for API documentation
  4. Update module's service and inject dependencies
  5. Add authentication guards if needed (@UseGuards(JwtAuthGuard))
  6. Test endpoint manually or add e2e tests in e2e/

Adding a New Cloud Function API

  1. Add handler in runtimes/nodejs/src/handler/
  2. Export from cloud-sdk (packages/cloud-sdk/src/)
  3. Update TypeScript definitions for IDE autocomplete
  4. Rebuild cloud-sdk and runtime

Modifying Database Access Rules

  1. Edit policies in packages/database-proxy/src/
  2. Database proxy validates all database operations against ACL rules
  3. Rules are defined per-application in the application's configuration

Adding Web UI Features

  1. Create components in web/src/components/ or web/src/pages/
  2. Use Chakra UI components for consistency
  3. Add API calls using axios and React Query
  4. Use Zustand stores for global state (web/src/pages/{page}/store.ts)
  5. Add i18n strings in web/public/locales/

Deployment

The project deploys to Kubernetes. See deploy/README.md for deployment instructions.

Prerequisites for Development

  • Node.js 18+ (runtime requires >=18.0.0)
  • Kubernetes cluster (for local development with Telepresence)
  • Telepresence CLI (for local development that connects to cluster)
  • MongoDB (for system database)
  • MinIO or S3-compatible storage

Common Issues

Telepresence intercept fails: Ensure you're connected to the cluster and the target pod exists in the namespace.

Runtime crashes on start: Check that all environment variables in .env are set correctly (created by telepresence intercept).

Web build fails with memory error: Use --max_old_space_size=32768 flag (already in package.json build script).

Type errors in web/: Run npm run tsc first to check types, Monaco editor requires proper TypeScript setup.

Lerna command not found: Install lerna globally or use npx: npx lerna <command>.