trace.moe-api is the core backend HTTP API server and data processing service for trace.moe (anime scene search engine).
- Runtime: Node.js >= 24 (runs
.tsfiles 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
├── 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
| 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 |
- This project always runs TypeScript files directly with Node.js >= 24 (e.g.
node script.ts) without usingtsc,ts-node, or--strip-types.
- When PostgreSQL is running in a Docker container, use
psqlvia:docker exec -i tracemoe-api-postgres-1 psql -U postgres -d postgres -c "..."
Before submitting changes, ensure lint and formatting checks pass:
npm run lint