xinghuoapi/CLAUDE.md

CLAUDE.md

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

Fork Identity

This is a customized fork of Wei-Shaw/sub2api, branded as StarFireAPI. Upstream remote: https://github.com/Wei-Shaw/sub2api.git.

Customizations to preserve on every upstream sync

Category	Details
Brand	All user-facing Sub2API → StarFireAPI in frontend/src/ (stores, i18n, views, components, router)
Links	GitHub links → https://anthropic.edu.pl in AppHeader, HomeView, i18n
docker-compose	Image: starfireapi:latest, port 6580:8080, external Redis at 172.18.0.2:6379, project name xinghuoapi, built-in Redis disabled
Update module	Disabled in system_handler.go (always returns no update), app.ts (forces hasUpdate=false), VersionBadge.vue (isReleaseBuild=false, removed GitHub release links)

Full details: skills/sync-upstream/SKILL.md

Build & Test Commands

# Full build (backend + frontend)
make build

# Backend only
cd backend && make build              # Binary → bin/server
cd backend && make test               # go test ./... + golangci-lint
cd backend && make test-unit          # Unit tests only
cd backend && go test ./internal/service/... -run TestXxx  # Single test

# Frontend only
cd frontend && pnpm install --frozen-lockfile
cd frontend && pnpm dev               # Dev server
cd frontend && pnpm build             # Type-check + production build
cd frontend && pnpm test:run          # Vitest
cd frontend && pnpm lint:check        # ESLint (no fix)

# Code generation (Ent ORM + Wire DI)
cd backend && make generate

Architecture

AI API Gateway: receives requests with user API keys → authenticates → selects upstream account (sticky session / load-aware) → forwards to upstream AI service → records usage for billing.

Backend (backend/internal/)

• Entry: cmd/server/main.go — supports setup mode, auto-setup (Docker), normal server
• DI: Google Wire (cmd/server/wire.go)
• Layers: handler → service → repository (enforced by depguard — service must not import repository)
• Key services: GatewayService (request forwarding, account selection, failover), OpenAIGatewayService, GeminiMessagesCompatService, AntigravityGatewayService
• ORM: Ent (ent/schema/ for definitions, ent/ for generated code)
• Middleware stack: Recovery → Logger → CORS → SecurityHeaders → RequestBodyLimit → ClientRequestID → APIKeyAuth
• Run modes: standard (full SaaS with billing) / simple (skip billing checks)

Frontend (frontend/src/)

• Framework: Vue 3 + Pinia + Vue Router + TailwindCSS
• State: stores/app.ts (global), stores/auth.ts (JWT auth)
• i18n: i18n/locales/en.ts, zh.ts — all user-facing strings
• Embedded: production build goes to backend/internal/web/dist/ and is embedded into the Go binary

Gateway Routes

/v1/messages              — Claude API compatible
/v1/responses             — OpenAI API compatible
/v1beta/models/*          — Gemini native API
/antigravity/v1/*         — Antigravity platform

Coding Conventions

• Go: gofmt, golangci-lint (see backend/.golangci.yml), max 3 levels of if nesting
• Frontend: Vue SFC + TypeScript, 2-space indent, ESLint, components PascalCase.vue, composables useXxx.ts
• Commits: Conventional Commits (feat(scope):, fix(scope):, chore(scope):)
• JSON hot-path: prefer gjson over encoding/json for read-only/partial extraction
• Layering: handler/service must NOT import repository/gorm/redis directly

Skills (in skills/)

• sync-upstream — Pulls and merges upstream sub2api, re-applies all StarFireAPI customizations. Trigger: "拉取上游", "同步上游", "sync upstream"
• bug-fix-expert — Multi-agent bug fix workflow with worktree isolation and cross-validation
• code-review-expert — Parallel 5-dimension code review with worktree isolation