cloud370
3162cbfad0
- Add export API endpoint POST /web/v1/accounts/export - Support two export modes: text (data strings) and object (full account objects) - Automatically set account status to 'exported' during export - Add comprehensive demo script that uploads, exports and verifies functionality - Update API documentation with export endpoint details - Add TypeScript types for export functionality 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
91 lines
3.6 KiB
Markdown
91 lines
3.6 KiB
Markdown
# 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` |