docs: update CLAUDE.md and AGENTS.md with comprehensive codebase docu… - #3024
Closed
chenny2023 wants to merge 1 commit into
Closed
docs: update CLAUDE.md and AGENTS.md with comprehensive codebase docu…#3024chenny2023 wants to merge 1 commit into
chenny2023 wants to merge 1 commit into
Conversation
…mentation Rewrote both files with current, accurate information including: - Full directory structure with all subdirectories and their purposes - Complete channel provider table (50+ providers) with type IDs - Relay channel.Adaptor interface specification - Task/async channel adapters (suno, kling, jimeng, vidu, doubao, sora, etc.) - Setting sub-packages (ratio_setting, model_setting, operation_setting, etc.) - Frontend stack details (React 18, Vite, Semi Design, Tailwind, VChart, etc.) - All 7 i18n locales (zh-CN, zh-TW, en, fr, ru, ja, vi) - Middleware inventory with purpose descriptions - common/ utilities inventory - Router structure (/api, /v1, /v1beta, /claude/v1, /video routes) - Development workflow (make, bun, docker multi-stage build) - Testing conventions and test file locations - Additional conventions (logging, config, channel affinity, payments) - Go module name and version (github.com/QuantumNous/new-api, Go 1.25.1) https://claude.ai/code/session_01Ljf9pKPNPiGBq646zKBAzM
Contributor
WalkthroughThe PR comprehensively updates documentation files (AGENTS.md and CLAUDE.md) to reflect expanded project scope, including provider count increase from 40+ to 50+, Go version bump to 1.25.1, and Tailwind CSS integration. It adds granular architectural descriptions for routers, controllers, services, middleware, common utilities, and relay/channel structures with explicit interface specifications and registry conventions. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs). Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@AGENTS.md`:
- Around line 348-349: Standardize the spelling to "adapter" in Rule 4: change
"adaptor registry" to "adapter registry" and ensure the interface name/reference
is consistent (e.g., update occurrences of channel.Adaptor to channel.Adapter if
you choose "Adapter") as well as any mentions of streamSupportedChannels to
match that same spelling scheme; update all related text in Rule 4 so "adapter"
is used uniformly.
- Around line 24-59: The markdown has unlabeled fenced code blocks around the
architecture lists (the block containing "router/ — HTTP routing: SetApiRouter,
SetDashboardRouter, SetRelayRouter, SetVideoRouter, SetWebRouter" and the block
showing routes like "/api/* — SetApiRouter" and "/ — SetWebRouter"); update both
fences to include a language label (e.g., change ``` to ```text) so markdownlint
MD040 is satisfied, ensuring all code blocks in AGENTS.md (the ones containing
"router/", "electron/" and the route examples with
"SetApiRouter"/"SetWebRouter") are consistently labeled.
In `@CLAUDE.md`:
- Around line 24-59: The Markdown fenced code blocks in CLAUDE.md lack language
tags (triggering MD040); update each triple-backtick block (e.g., the directory
listing block and the route listing block) to include a language tag such as
"text" so they become ```text ... ```; locate the blocks shown in the diff (the
router/.../electron/... listing and the /api/* ... / ... routing listing) and
add the language tag to each opening fence to satisfy the linter.
- Around line 348-349: Replace the inconsistent spelling "adaptor" with
"adapter" in this section: change the phrase "relay adaptor registry" to "relay
adapter registry" and rename any references to channel.Adaptor to
channel.Adapter (and any textual mentions of "adaptor") so all occurrences
(including the two bullets referencing streamSupportedChannels and the
channel.Adaptor interface) use the single term "adapter" consistently.
Comment on lines
24
to
+59
| ``` | ||
| router/ — HTTP routing (API, relay, dashboard, web) | ||
| controller/ — Request handlers | ||
| service/ — Business logic | ||
| model/ — Data models and DB access (GORM) | ||
| relay/ — AI API relay/proxy with provider adapters | ||
| relay/channel/ — Provider-specific adapters (openai/, claude/, gemini/, aws/, etc.) | ||
| middleware/ — Auth, rate limiting, CORS, logging, distribution | ||
| setting/ — Configuration management (ratio, model, operation, system, performance) | ||
| common/ — Shared utilities (JSON, crypto, Redis, env, rate-limit, etc.) | ||
| dto/ — Data transfer objects (request/response structs) | ||
| constant/ — Constants (API types, channel types, context keys) | ||
| types/ — Type definitions (relay formats, file sources, errors) | ||
| i18n/ — Backend internationalization (go-i18n, en/zh) | ||
| oauth/ — OAuth provider implementations | ||
| pkg/ — Internal packages (cachex, ionet) | ||
| web/ — React frontend | ||
| web/src/i18n/ — Frontend internationalization (i18next, zh/en/fr/ru/ja/vi) | ||
| router/ — HTTP routing: SetApiRouter, SetDashboardRouter, SetRelayRouter, SetVideoRouter, SetWebRouter | ||
| controller/ — Request handlers (50+ files covering all endpoints) | ||
| service/ — Business logic; sub-packages: openaicompat/, passkey/ | ||
| model/ — Data models and DB access (GORM); covers users, channels, tokens, logs, tasks, etc. | ||
| relay/ — AI API relay/proxy core | ||
| relay/channel/ — Provider-specific adaptors (implements channel.Adaptor interface) | ||
| relay/channel/task/ — Async/video task channel adaptors (ali, doubao, gemini, hailuo, jimeng, kling, sora, suno, taskcommon, vertex, vidu) | ||
| relay/common/ — RelayInfo, billing helpers, relay utilities | ||
| relay/common_handler/ — Shared rerank handler | ||
| relay/helper/ — Price/model mapping, stream scanner | ||
| relay/constant/ — Relay mode constants | ||
| relay/reasonmap/ — Reasoning model mappings | ||
| middleware/ — Auth, rate limiting, CORS, logging, gzip, body cleanup, stats | ||
| setting/ — Configuration management sub-packages: | ||
| setting/ratio_setting/ — Model/group price ratios (cache, expose, compact) | ||
| setting/model_setting/ — Per-model settings (Claude, Gemini, Grok, Qwen) | ||
| setting/operation_setting/ — General, quota, token, payment, checkin, affinity, monitor, status codes | ||
| setting/performance_setting/ — Performance/concurrency config | ||
| setting/console_setting/ — Console-specific settings | ||
| setting/system_setting/ — Discord, OIDC, Passkey, legal, fetch settings | ||
| setting/config/ — Global config singleton | ||
| common/ — Shared utilities (see below) | ||
| dto/ — Data transfer objects (OpenAI, Claude, Gemini, Midjourney, audio, video, etc.) | ||
| constant/ — Channel types/IDs, API types, context keys, endpoints, env vars, task types | ||
| types/ — Type definitions: relay formats, file sources/data, errors (NewAPIError), price data | ||
| i18n/ — Backend internationalization (go-i18n v2, en/zh locale files) | ||
| oauth/ — OAuth provider implementations (registered via init()) | ||
| logger/ — Structured logging | ||
| pkg/ | ||
| pkg/cachex/ — Hybrid in-memory/Redis cache with namespacing (codec, hybrid_cache, namespace) | ||
| pkg/ionet/ — Container/hardware introspection for io.net deployment | ||
| web/ — React frontend (see Frontend section) | ||
| docs/ — Documentation: channel/, images/, installation/, openapi/, translation glossaries | ||
| electron/ — Electron desktop app wrapper | ||
| ``` |
Contributor
There was a problem hiding this comment.
Specify fenced-code languages here as well.
Line 24 and Line 142 use unlabeled fenced code blocks; this will fail markdownlint MD040.
📝 Proposed fix
-```
+```text
router/ — HTTP routing: SetApiRouter, SetDashboardRouter, SetRelayRouter, SetVideoRouter, SetWebRouter
...
electron/ — Electron desktop app wrapper- +text
/api/* — SetApiRouter: user auth, OAuth, channel management, admin
...
/ — SetWebRouter: serves embedded React SPA
Also applies to: 142-149
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 24-24: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@AGENTS.md` around lines 24 - 59, The markdown has unlabeled fenced code
blocks around the architecture lists (the block containing "router/ — HTTP
routing: SetApiRouter, SetDashboardRouter, SetRelayRouter, SetVideoRouter,
SetWebRouter" and the block showing routes like "/api/* — SetApiRouter" and "/ —
SetWebRouter"); update both fences to include a language label (e.g., change ```
to ```text) so markdownlint MD040 is satisfied, ensuring all code blocks in
AGENTS.md (the ones containing "router/", "electron/" and the route examples
with "SetApiRouter"/"SetWebRouter") are consistently labeled.
Comment on lines
+348
to
+349
| - If supported, add the channel to `streamSupportedChannels` in the relay adaptor registry. | ||
| - The `channel.Adaptor` interface must be fully implemented — all methods are required. |
Contributor
There was a problem hiding this comment.
Keep adapter spelling consistent in Rule 4.
Line 348 uses “adaptor registry” while nearby text says “adapter”. Standardize one variant.
📝 Proposed fix
-- If supported, add the channel to `streamSupportedChannels` in the relay adaptor registry.
+- If supported, add the channel to `streamSupportedChannels` in the relay adapter registry.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - If supported, add the channel to `streamSupportedChannels` in the relay adaptor registry. | |
| - The `channel.Adaptor` interface must be fully implemented — all methods are required. | |
| - If supported, add the channel to `streamSupportedChannels` in the relay adapter registry. | |
| - The `channel.Adaptor` interface must be fully implemented — all methods are required. |
🧰 Tools
🪛 LanguageTool
[uncategorized] ~348-~348: Do not mix variants of the same word (‘adaptor’ and ‘adapter’) within a single text.
Context: ... streamSupportedChannels in the relay adaptor registry. - The channel.Adaptor inter...
(EN_WORD_COHERENCY)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@AGENTS.md` around lines 348 - 349, Standardize the spelling to "adapter" in
Rule 4: change "adaptor registry" to "adapter registry" and ensure the interface
name/reference is consistent (e.g., update occurrences of channel.Adaptor to
channel.Adapter if you choose "Adapter") as well as any mentions of
streamSupportedChannels to match that same spelling scheme; update all related
text in Rule 4 so "adapter" is used uniformly.
Comment on lines
24
to
+59
| ``` | ||
| router/ — HTTP routing (API, relay, dashboard, web) | ||
| controller/ — Request handlers | ||
| service/ — Business logic | ||
| model/ — Data models and DB access (GORM) | ||
| relay/ — AI API relay/proxy with provider adapters | ||
| relay/channel/ — Provider-specific adapters (openai/, claude/, gemini/, aws/, etc.) | ||
| middleware/ — Auth, rate limiting, CORS, logging, distribution | ||
| setting/ — Configuration management (ratio, model, operation, system, performance) | ||
| common/ — Shared utilities (JSON, crypto, Redis, env, rate-limit, etc.) | ||
| dto/ — Data transfer objects (request/response structs) | ||
| constant/ — Constants (API types, channel types, context keys) | ||
| types/ — Type definitions (relay formats, file sources, errors) | ||
| i18n/ — Backend internationalization (go-i18n, en/zh) | ||
| oauth/ — OAuth provider implementations | ||
| pkg/ — Internal packages (cachex, ionet) | ||
| web/ — React frontend | ||
| web/src/i18n/ — Frontend internationalization (i18next, zh/en/fr/ru/ja/vi) | ||
| router/ — HTTP routing: SetApiRouter, SetDashboardRouter, SetRelayRouter, SetVideoRouter, SetWebRouter | ||
| controller/ — Request handlers (50+ files covering all endpoints) | ||
| service/ — Business logic; sub-packages: openaicompat/, passkey/ | ||
| model/ — Data models and DB access (GORM); covers users, channels, tokens, logs, tasks, etc. | ||
| relay/ — AI API relay/proxy core | ||
| relay/channel/ — Provider-specific adaptors (implements channel.Adaptor interface) | ||
| relay/channel/task/ — Async/video task channel adaptors (ali, doubao, gemini, hailuo, jimeng, kling, sora, suno, taskcommon, vertex, vidu) | ||
| relay/common/ — RelayInfo, billing helpers, relay utilities | ||
| relay/common_handler/ — Shared rerank handler | ||
| relay/helper/ — Price/model mapping, stream scanner | ||
| relay/constant/ — Relay mode constants | ||
| relay/reasonmap/ — Reasoning model mappings | ||
| middleware/ — Auth, rate limiting, CORS, logging, gzip, body cleanup, stats | ||
| setting/ — Configuration management sub-packages: | ||
| setting/ratio_setting/ — Model/group price ratios (cache, expose, compact) | ||
| setting/model_setting/ — Per-model settings (Claude, Gemini, Grok, Qwen) | ||
| setting/operation_setting/ — General, quota, token, payment, checkin, affinity, monitor, status codes | ||
| setting/performance_setting/ — Performance/concurrency config | ||
| setting/console_setting/ — Console-specific settings | ||
| setting/system_setting/ — Discord, OIDC, Passkey, legal, fetch settings | ||
| setting/config/ — Global config singleton | ||
| common/ — Shared utilities (see below) | ||
| dto/ — Data transfer objects (OpenAI, Claude, Gemini, Midjourney, audio, video, etc.) | ||
| constant/ — Channel types/IDs, API types, context keys, endpoints, env vars, task types | ||
| types/ — Type definitions: relay formats, file sources/data, errors (NewAPIError), price data | ||
| i18n/ — Backend internationalization (go-i18n v2, en/zh locale files) | ||
| oauth/ — OAuth provider implementations (registered via init()) | ||
| logger/ — Structured logging | ||
| pkg/ | ||
| pkg/cachex/ — Hybrid in-memory/Redis cache with namespacing (codec, hybrid_cache, namespace) | ||
| pkg/ionet/ — Container/hardware introspection for io.net deployment | ||
| web/ — React frontend (see Frontend section) | ||
| docs/ — Documentation: channel/, images/, installation/, openapi/, translation glossaries | ||
| electron/ — Electron desktop app wrapper | ||
| ``` |
Contributor
There was a problem hiding this comment.
Add fenced-code languages to keep docs lint-clean.
Line 24 and Line 142 open fenced blocks without a language tag, which triggers MD040.
📝 Proposed fix
-```
+```text
router/ — HTTP routing: SetApiRouter, SetDashboardRouter, SetRelayRouter, SetVideoRouter, SetWebRouter
...
electron/ — Electron desktop app wrapper- +text
/api/* — SetApiRouter: user auth, OAuth, channel management, admin
...
/ — SetWebRouter: serves embedded React SPA
Also applies to: 142-149
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 24-24: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CLAUDE.md` around lines 24 - 59, The Markdown fenced code blocks in CLAUDE.md
lack language tags (triggering MD040); update each triple-backtick block (e.g.,
the directory listing block and the route listing block) to include a language
tag such as "text" so they become ```text ... ```; locate the blocks shown in
the diff (the router/.../electron/... listing and the /api/* ... / ... routing
listing) and add the language tag to each opening fence to satisfy the linter.
Comment on lines
+348
to
+349
| - If supported, add the channel to `streamSupportedChannels` in the relay adaptor registry. | ||
| - The `channel.Adaptor` interface must be fully implemented — all methods are required. |
Contributor
There was a problem hiding this comment.
Use one term consistently: “adapter” vs “adaptor”.
Line 348 says “relay adaptor registry” while adjacent text uses “adapter”. Please standardize on one spelling in this section.
📝 Proposed fix
-- If supported, add the channel to `streamSupportedChannels` in the relay adaptor registry.
+- If supported, add the channel to `streamSupportedChannels` in the relay adapter registry.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - If supported, add the channel to `streamSupportedChannels` in the relay adaptor registry. | |
| - The `channel.Adaptor` interface must be fully implemented — all methods are required. | |
| - If supported, add the channel to `streamSupportedChannels` in the relay adapter registry. | |
| - The `channel.Adaptor` interface must be fully implemented — all methods are required. |
🧰 Tools
🪛 LanguageTool
[uncategorized] ~348-~348: Do not mix variants of the same word (‘adaptor’ and ‘adapter’) within a single text.
Context: ... streamSupportedChannels in the relay adaptor registry. - The channel.Adaptor inter...
(EN_WORD_COHERENCY)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CLAUDE.md` around lines 348 - 349, Replace the inconsistent spelling
"adaptor" with "adapter" in this section: change the phrase "relay adaptor
registry" to "relay adapter registry" and rename any references to
channel.Adaptor to channel.Adapter (and any textual mentions of "adaptor") so
all occurrences (including the two bullets referencing streamSupportedChannels
and the channel.Adaptor interface) use the single term "adapter" consistently.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
…mentation
Rewrote both files with current, accurate information including:
https://claude.ai/code/session_01Ljf9pKPNPiGBq646zKBAzM
Summary by CodeRabbit