86 lines
No EOL
3.2 KiB
Markdown
86 lines
No EOL
3.2 KiB
Markdown
# 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 |