# 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](https://github.com/Wei-Shaw/sub2api.git), 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

```bash
# 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