accounts-manager/CLAUDE.md

CLAUDE.md

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

Development Commands

# 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