# CLAUDE.md

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

## Development Commands

```bash
# Development
npm run dev          # Start development server with tsx watch
npm run build        # Compile TypeScript to JavaScript
npm start           # Run the production build

# Database Operations
npm run db:create    # Create database if it doesn't exist
npm run db:generate  # Generate Drizzle migration files
npm run db:migrate   # Run database migrations
npm run db:studio    # Open Drizzle Studio (database management UI)
npm run db:setup     # One-command database setup (create + migrate)
```

## Architecture Overview

This is a lightweight account management platform built with TypeScript, Fastify, and PostgreSQL. The system uses a **single table design** with the `accounts` table storing all account data.

### Core Design Principles
- **Single Table Architecture**: All account data stored in one `accounts` table with proper indexing
- **Dual API Design**: Separate optimized APIs for automation scripts (`/s/v1/`) and web management (`/web/v1/`)
- **Concurrent Safety**: Account locking mechanism prevents simultaneous access to the same account
- **Background Jobs**: Automatic cleanup of stale locks via scheduled tasks

### Key Components

**Database Layer** (`src/db/`):
- `schema.ts`: Single accounts table with unique constraints on platform+customId
- `index.ts`: PostgreSQL connection using Drizzle ORM

**Core Business Logic** (`src/core/AccountService.ts`):
- Account acquisition with automatic locking
- Status management and batch operations  
- Statistics generation and stale lock cleanup
- All database operations are transactional where needed

**API Routes**:
- `src/api/v1/script/actions.ts`: Lightweight script API for automation
- `src/api/v1/web/accounts.ts`: Full-featured web management API
- `src/api/v1/web/stats.ts`: Statistics and analytics endpoints

**Background Jobs** (`src/jobs/staleLockCleanup.ts`):
- Automatic cleanup of accounts locked longer than `LOCK_TIMEOUT_MINUTES`

### Database Schema

The `accounts` table structure:
- `id`: Primary key (serial)
- `ownerId`: Account owner identifier
- `platform`: Platform name (e.g., "twitter", "facebook")
- `customId`: Custom identifier for the account
- `data`: JSON data storage for account information
- `status`: Current status ("available", "locked", "failed", etc.)
- `notes`: Optional notes field
- `lockedAt`: Timestamp when account was locked
- Unique constraint: `platform + customId`
- Indexes on: `ownerId + status`, `platform + ownerId`

### API Patterns

**Script API** (`/s/v1/{ownerId}/`): GET-based, optimized for automation
- `GET /acquire?platform=X&count=N` - Get and lock accounts
- `GET /update/{accountId}/{status}?notes=X` - Update account status
- `POST /upload` - Bulk upload/update accounts

**Web API** (`/web/v1/`): POST-based with rich payloads
- `POST /accounts/list` - Complex filtering, pagination, sorting
- `POST /accounts/delete-batch` - Bulk delete operations
- `POST /accounts/update-batch` - Bulk update operations

### Environment Configuration

Required environment variables (see `.env.example`):
- `DATABASE_URL`: PostgreSQL connection string
- `PORT`: Server port (default: 3000)
- `NODE_ENV`: Environment mode
- `LOCK_TIMEOUT_MINUTES`: Lock timeout duration (default: 5 minutes)

### Development Notes

- The application uses Fastify with full CORS enabled
- Graceful shutdown handling for SIGTERM/SIGINT
- Structured logging with different levels for dev/prod
- Health check endpoint at `/health`
- All API responses use standardized format from `lib/apiResponse.ts`