Skip to content

Latest commit

 

History

History
83 lines (64 loc) · 3.9 KB

AGENTS.md

File metadata and controls

83 lines (64 loc) · 3.9 KB

AGENTS.md

Project Overview

trace.moe-api is the core backend HTTP API server and data processing service for trace.moe (anime scene search engine).

Core Tech Stack

  • Runtime: Node.js >= 24 (runs .ts files directly via native TypeScript support)
  • Framework: Express 5
  • Databases: PostgreSQL (postgres), Milvus Vector DB (@zilliz/milvus2-sdk-node)
  • Image & Media Processing: sharp, aniep
  • Code Formatting & Quality: Prettier, oxfmt

Directory Structure

├── server.ts                    # Main API server entry point
├── env.ts                       # Environment variable parsing & validation
├── sql.ts                       # PostgreSQL client connection instance
├── dependency-check.ts          # Service health check script (PostgreSQL, Milvus)
├── swagger.yaml                 # OpenAPI 3.0 API specification
├── compose.yml                  # Docker Compose configuration (PostgreSQL, Milvus)
├── src/                         # Core API endpoints & business logic
│   ├── app.ts                   # Express application setup & middleware
│   ├── search.ts                # Main scene search handler (/search)
│   ├── image.ts                 # Image proxy & crop handler (/image)
│   ├── video.ts                 # Video preview proxy handler (/video)
│   ├── get-me.ts                # User quota & profile handler (/me)
│   ├── get-stats.ts             # System metrics handler (/stats)
│   ├── get-status.ts            # System status handler (/status)
│   ├── tasks.ts                 # Task queue status handler (/tasks)
│   ├── lib/                     # Server utility modules (detect-scene, color-layout, safe-fetch, etc.)
│   ├── user/                    # User authentication & key management handlers
│   ├── webhook/                 # Webhook integration handlers
│   └── worker/                  # Background worker routines
├── script/                      # Database & media processing scripts
│   ├── check-similarity.ts      # Scene similarity validation script
│   ├── check-subtitles.ts       # Subtitle search validation script
│   ├── bulk-load-milvus.ts      # Milvus vector bulk loading script
│   ├── anilist.ts               # AniList media sync script
│   └── cleanup.ts               # Temporary file cleanup script
├── sql/                         # Database initialization schemas
│   └── 1.init.sql               # Initial PostgreSQL tables & indexes
├── .env.example                 # Environment configuration template
└── package.json                 # Project dependencies & npm scripts

Command Reference

Action Command Notes
Start Server npm run start Starts API server (node server.ts)
Lint / Format Check npm run lint Checks code formatting using Prettier
Format Code npm run format Auto-formats all project files using Prettier
Run TS File Direct node <filepath>.ts Executes any .ts script directly with Node 24

Coding & Operational Guidelines

1. Direct TypeScript Execution

  • This project always runs TypeScript files directly with Node.js >= 24 (e.g. node script.ts) without using tsc, ts-node, or --strip-types.

2. PostgreSQL Docker Execution

  • When PostgreSQL is running in a Docker container, use psql via:
    docker exec -i tracemoe-api-postgres-1 psql -U postgres -d postgres -c "..."

3. Verification Workflow

Before submitting changes, ensure lint and formatting checks pass:

npm run lint