# 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