{"owner":"MHSanaei","repo":"3x-ui","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"files":{"CLAUDE.md":"# CLAUDE.md\n\nOperational guide for AI agents working in this repo. Long-form human docs:\n`CONTRIBUTING.md` (setup, testing philosophy) and `frontend/README.md`.\nRead those before large changes. This file is the short, must-follow version.\nFor a deep navigation map (request lifecycle, cron-job table, symptom → file\nindex, layering rules), read `docs/architecture.md` on demand — do not guess\nfile locations when it can answer in one hop.\n\n## Stack\n- Backend: Go 1.26 (`module github.com/mhsanaei/3x-ui/v3`), Gin, GORM.\n  Runs Xray-core as a managed child process (`internal/xray/process.go`) and\n  imports `github.com/xtls/xray-core` for config types + gRPC stats/handler/router\n  API. MTProto inbounds run a second managed child — the `mtg-multi` binary\n  (a multi-secret mtg fork — NOT a Go dependency; its prebuilt release binary is\n  fetched at image/release build time by `DockerInit.sh` + `release.yml`,\n  panel-side code in `internal/mtproto/`) — outside Xray, one process per inbound\n  serving each\n  client's FakeTLS secret via the fork's `[secrets]` section (plus per-client\n  ad-tags via `[secret-ad-tags]` and per-client data quota / expiry via\n  `[secret-limits]`, mapped from the client's `totalGB`/`expiryTime`). Client,\n  ad-tag and quota/expiry edits are hot-applied through the fork's management API\n  (`PUT /secrets`, bearer-token guarded) so connections survive; the manager\n  falls back to a process restart on older binaries. A client's panel-side\n  traffic reset also calls `POST /secrets/{name}/reset-quota` so a renewed client\n  is not re-blocked by the sidecar's quota counter.\n- Storage: SQLite by default (`/etc/x-ui/x-ui.db` on Linux; the executable dir on\n  Windows), PostgreSQL optional (`XUI_DB_TYPE` / `XUI_DB_DSN`). The CGo SQLite\n  driver (`mattn/go-sqlite3`) needs a C compiler — `CGO_ENABLED=0` builds fail.\n- Frontend: React 19 + Ant Design 6 + Vite 8 + TypeScript in `frontend/`,\n  built into `internal/web/dist/` (gitignored) and embedded via `embed.FS`.\n\n## Repo map\n- `main.go` — entry point + `x-ui` CLI (run, migrate, migrate-db, setting, cert).\n- `internal/config/` — env parsing (XUI_DEBUG, XUI_LOG_LEVEL, XUI_LOG_FOLDER,\n  XUI_BIN_FOLDER, XUI_SKIP_HSTS, XUI_PORT, XUI_DB_*).\n- `internal/database/` + `internal/database/model/` — GORM schema (~24 models;\n  Inbound, Client, Setting, User are the core), inbound Protocol enum,\n  AutoMigrate + hand-written migrations in `db.go`.\n- `internal/xray/` — Xray child-process lifecycle, config generation, gRPC API.\n- `internal/mtproto/` — MTProto inbounds via the bundled `mtg-multi` binary.\n- `internal/sub/` — subscription server (raw / JSON / Clash).\n- `internal/eventbus/` — in-process pub/sub (outbound/node health, xray.crash,\n  cpu.high, memory.high, login.attempt).\n- `internal/logger/`, `internal/util/` (link, crypto, sys, ldap, …),\n  `internal/tunnelmonitor/` — shared infrastructure.\n- `internal/web/` — Gin server (embeds `dist/` + `translation/`).\n  - `controller/` — panel + REST API handlers; OpenAPI at /panel/api/openapi.json.\n  - `service/` — business logic (InboundService, SettingService, XrayService,\n    node sync); subpackages tgbot/, email/, outbound/, panel/, integration/.\n  - `job/` — 17 cron jobs (traffic, fail2ban IP-limit, node heartbeat/sync, LDAP,\n    CPU/memory watchdogs, …); full table in `docs/architecture.md` §5.4.\n  - `middleware/`, `entity/`, `global/`, `session/` (CSRF), `network/`,\n    `runtime/` (master/sub-node over mTLS), `websocket/`.\n  - `locale/` + `translation/` — i18n, 13 embedded locale JSON files.\n- `frontend/` — React + TS source (see `frontend/CLAUDE.md`).\n- `tools/openapigen/` — Go generator that emits frontend types + Zod/JSON schemas\n  into `frontend/src/generated/` from Go structs. The OpenAPI doc itself\n  (`frontend/public/openapi.json`) is assembled from those + `endpoints.ts` by\n  `frontend/scripts/build-openapi.mjs`. (`tools/seedperf/` is a separate seeding\n  /load helper.)\n- `docs/` — separate Next.js/Fumadocs site (pnpm, own CI in `docs-ci.yml`,\n  outside `make verify`). Holds a THIRD independent implementation of\n  link/subscription generation in `docs/lib/xray/` — check it whenever\n  share-link or install-command output changes.\n\n## Hard rules (non-negotiable)\n- Fix size must match bug size. Find the root cause, then make the SMALLEST\n  change that removes it — a one-line guard beats a new subsystem. A small bug\n  does not earn new columns, jobs, abstractions, config knobs or helper layers.\n  If a fix genuinely needs new architecture, say so and get agreement first;\n  never ship it unasked next to the fix.\n- Comments in committed Go/TS: 2 lines MAX per comment block. Make the name\n  carry the meaning first and rename rather than annotate; spend the 2 lines on\n  the *why* a name cannot hold — an invariant, an issue number, a non-obvious\n  constraint. Exempt: `//go:build`, `//go:generate`, and other directives.\n  HTML `<!-- -->` is fine. (A linter cannot enforce this — you must.)\n- New `g.POST`/`g.GET` in `internal/web/controller/` REQUIRES a matching entry\n  in `frontend/src/pages/api-docs/endpoints.ts`, then `make gen` (or\n  `cd frontend && npm run gen`). Hand-maintained but pinned both ways by\n  `TestRouteRegistryContract` (`internal/web/routes_contract_test.go`): a missing\n  OR stale entry fails `make test-go`. Scope: `/panel/api/*` + a few session\n  routes; sub-server routes are exempt.\n- Response examples come from Go struct `example:` tags via `tools/openapigen` —\n  never hand-write them. A new struct must be added to openapigen's `StructAllow`\n  allowlist (`tools/openapigen/main.go`) or it is silently omitted from\n  schemas/examples (and `build-openapi.mjs` then fails on the missing schema).\n- A new or renamed endpoint has a FOURTH step nothing checks: copy\n  `frontend/public/openapi.json` → `docs/public/openapi.json`, then\n  `cd docs && pnpm gen:api` to refresh the MDX under\n  `docs/content/docs/en/reference/api/`. `docs-ci.yml` fires only on `docs/**`.\n- A new English i18n key goes in EVERY locale JSON in `internal/web/translation/`\n  (13 files) AND must be referenced from `frontend/src` or Go in the SAME commit —\n  `frontend/src/test/i18n-dead-keys.test.ts` fails both ways. It is a frontend\n  test, so run `npm test`, not just `make test-go`. At runtime the frontend falls\n  back to en-US; Go (`internal/web/locale/`) returns \"\" for an unknown key.\n- DB / model changes require a migration in `internal/database/db.go`.\n- Every state-changing inbound/client op dispatches through `runtime.Runtime`\n  (`internal/web/runtime/`) — never straight to `internal/xray/api.go`, never from\n  a controller or cron job. A direct call passes every local test and silently\n  breaks every multi-node deployment. Other layering rules: `docs/architecture.md` §8.\n- Conventional commits: `type(area): short imperative summary`, then a body\n  explaining the why. Types in use: `fix`, `feat`, `chore`, `refactor`, `perf`,\n  `docs`, `style`.\n\n## Go conventions\n- Stdlib `testing` only (no testify). Table-driven, `t.Run` subtests,\n  `t.Helper()` on helpers. Assert the exact value / typed error / emitted\n  string, never just `err != nil`. Prefer real deps over mocks: throwaway DB via\n  `database.InitDB(filepath.Join(t.TempDir(), \"x-ui.db\"))` +\n  `t.Cleanup(func() { _ = database.CloseDB() })`; `httptest` for HTTP.\n  `internal/sub`'s `initSubDB(t)` is the template.\n- A test must fail without its fix. Write it, revert the fix, watch it go red,\n  restore. A test that passes either way is worse than no test: it certifies\n  nothing and then gets cited as proof the fix works.\n- Test what can actually break. No test for a getter, a constant, a rename, a\n  pure map lookup, or inputs the function can never receive. One real test that\n  drives the bug through the actual code path beats five that restate the code.\n- Code must pass `golangci-lint run` (gofumpt + goimports formatting): `make lint`.\n- Postgres, xray-gRPC-e2e and scale tests `t.Skip` unless `XUI_TEST_PG_DSN`,\n  `XUI_DB_TYPE`+`XUI_DB_DSN`, `XRAY_E2E_BINARY` or `XUI_SCALE_TEST` is set — a\n  green `go test ./...` does not mean those paths ran.\n\n## Frontend conventions (summary; full version in frontend/CLAUDE.md)\n- Ant Design 6 only — no Tailwind/shadcn. Targeted tweaks, not rewrites.\n- TS strict; `@typescript-eslint/no-explicit-any` is an error. Zod schemas in\n  `src/schemas/` are the source of truth; infer types with `z.infer`, never\n  hand-write. Do not edit `src/generated/`.\n- Node 24 (`.nvmrc`) — `make gen` imports `.ts` directly and needs its type\n  stripping; Node 22 dies with `ERR_UNKNOWN_FILE_EXTENSION`. `npm test` includes\n  a headless-Chromium Storybook project, so run\n  `npx playwright install --with-deps chromium` once or `make verify` fails.\n- Editing `frontend/src` does NOT change what users see until the Vite build is\n  regenerated into `internal/web/dist/`. In `XUI_DEBUG=true`, HTML is served from\n  the frozen embedded FS but JS/CSS off disk — after `npm run build` you MUST\n  restart `go run .` or you get a blank page with 404s.\n- After touching share-link logic (`src/lib/xray/`), run `npm run test` (golden\n  fixtures); regenerate snapshots (`npx vitest run -u`) only for intentional\n  output changes, never to make a red test green.\n\n## Build, test, verify\nA fresh clone has no `internal/web/dist/`, so a bare `go build ./...` dies with\n`pattern all:dist: no matching files found` while ~35 other packages pass — it\nreads as a broken repo, not a missing step. Run `make dist-stub` once; every\n`make` Go target already depends on it, which is why `make test-go` beats\n`go test ./...`. Run `make help` for all targets. The local gate:\n\n    make verify   # gen-check + lint + typecheck + test + build + build-storybook\n\nThat is the *fast* gate, not all of CI. `ci.yml` also runs `make race`,\n`make vulncheck`, a live-Postgres job (where a SKIP counts as a failure) and a\n30s fuzz smoke on `FuzzParseLink`/`FuzzDecodeCertPin` — run those locally when\nyou touch DB/dialect or parser code.\n\nCommon targets: `make gen` (regenerate Zod/OpenAPI), `make lint` (Go + frontend),\n`make test` (Go `-shuffle=on` + frontend), `make race`, `make build`. See `Makefile`.\n\n## Definition of done (before opening a PR)\n1. `make verify` passes — its `gen-check` already runs `make gen` and fails on a\n   dirty `frontend/src/generated` / `frontend/public/openapi.json`.\n2. Diff is focused; refactors are separate from feature work.\n"}}