lamassu-server/CLAUDE.md

CLAUDE.md

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

Project Overview

This is a Bitcoin ATM server implementation built as a monorepo with three main packages:

1. packages/server - Node.js backend with Express, GraphQL, PostgreSQL
2. packages/admin-ui - React frontend with Material-UI
3. packages/typesafe-db - TypeScript database layer using Kysely

Common Commands

Development Setup

• pnpm install - Install dependencies (Node.js 22+ required)
• bash packages/server/tools/cert-gen.sh - Generate SSL certificates
• node packages/server/bin/lamassu-migrate - Run database migrations
• node packages/server/bin/lamassu-register admin@example.com superuser - Create admin user

Development

• pnpm run dev - Start development servers (both admin UI and server)
• pnpm run build - Build all packages using Turbo
• pnpm run test - Run tests

TypeScript/Database

• cd packages/typesafe-db && npm run generate-types - Generate database types
• cd packages/typesafe-db && npm run build - Build TypeScript database layer

Individual Package Commands

• Server: npm run dev in packages/server (runs both server and admin-server with --watch)
• Admin UI: npm run dev in packages/admin-ui (Vite dev server)

Architecture

Monorepo Structure: Uses Turbo for build orchestration and PNPM workspaces.

packages/server

• bin/ - CLI tools and executables (lamassu-migrate, lamassu-register, etc.)
• lib/ - Core business logic
  • blockchain/ - Cryptocurrency handling (bitcoin, ethereum, etc.)
  • cash-in/, cash-out/ - Transaction processing
  • compliance/ - KYC/AML and sanctions checking
  • new-admin/ - GraphQL API and admin server
  • plugins/ - Exchange, wallet, and service integrations
  • routes/ - Express API endpoints
• migrations/ - Database schema migrations
• Express server with GraphQL API, PostgreSQL database

packages/admin-ui

• React app built with Vite
• src/pages/ - Main application screens
• src/components/ - Reusable UI components
• Material-UI design system
• Apollo Client for GraphQL

packages/typesafe-db

• Kysely for type-safe SQL queries
• Auto-generates TypeScript types from PostgreSQL schema
• Shared database layer across packages

Key Configuration

Environment Setup

• PostgreSQL database required
• Environment variables configured in packages/server/.env
• SSL certificates generated via cert-gen.sh

Build System

• turbo.json - Defines build pipeline and caching
• pnpm-workspace.yaml - Workspace package definitions
• eslint.config.mjs - ESLint configuration with React, TypeScript, Vitest rules
• Husky pre-commit hooks with lint-staged for code quality

Database

• PostgreSQL with extensive migration system
• Critical data: transactions, customers, machines, compliance records
• Use typesafe-db package for database operations

Development Guidelines

Code Quality

• TypeScript for database operations via typesafe-db package
• Follow existing patterns in GraphQL resolvers and Express routes
• Test database changes with migrations before deployment
• ESLint + Prettier enforced via pre-commit hooks