Skip to content

Commit 28b53e1

Browse files
Calcium-IonCalcium-Ion
committed
feat: add project conventions and coding standards documentation for new-api
1 parent cac45d9 commit 28b53e1

File tree

3 files changed

+305
-0
lines changed

3 files changed

+305
-0
lines changed

‎.cursor/rules/project.mdc‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
description: Project conventions and coding standards for new-api
3+
alwaysApply: true
4+
---
5+
6+
# Project Conventions — new-api
7+
8+
## Overview
9+
10+
This is an AI API gateway/proxy built with Go. It aggregates 40+ upstream AI providers (OpenAI, Claude, Gemini, Azure, AWS Bedrock, etc.) behind a unified API, with user management, billing, rate limiting, and an admin dashboard.
11+
12+
## Tech Stack
13+
14+
- **Backend**: Go 1.22+, Gin web framework, GORM v2 ORM
15+
- **Frontend**: React 18, Vite, Semi Design UI (@douyinfe/semi-ui)
16+
- **Databases**: SQLite, MySQL, PostgreSQL (all three must be supported)
17+
- **Cache**: Redis (go-redis) + in-memory cache
18+
- **Auth**: JWT, WebAuthn/Passkeys, OAuth (GitHub, Discord, OIDC, etc.)
19+
- **Frontend package manager**: Bun (preferred over npm/yarn/pnpm)
20+
21+
## Architecture
22+
23+
Layered architecture: Router -> Controller -> Service -> Model
24+
25+
```
26+
router/ — HTTP routing (API, relay, dashboard, web)
27+
controller/ — Request handlers
28+
service/ — Business logic
29+
model/ — Data models and DB access (GORM)
30+
relay/ — AI API relay/proxy with provider adapters
31+
relay/channel/ — Provider-specific adapters (openai/, claude/, gemini/, aws/, etc.)
32+
middleware/ — Auth, rate limiting, CORS, logging, distribution
33+
setting/ — Configuration management (ratio, model, operation, system, performance)
34+
common/ — Shared utilities (JSON, crypto, Redis, env, rate-limit, etc.)
35+
dto/ — Data transfer objects (request/response structs)
36+
constant/ — Constants (API types, channel types, context keys)
37+
types/ — Type definitions (relay formats, file sources, errors)
38+
i18n/ — Backend internationalization (go-i18n, en/zh)
39+
oauth/ — OAuth provider implementations
40+
pkg/ — Internal packages (cachex, ionet)
41+
web/ — React frontend
42+
web/src/i18n/ — Frontend internationalization (i18next, zh/en/fr/ru/ja/vi)
43+
```
44+
45+
## Internationalization (i18n)
46+
47+
### Backend (`i18n/`)
48+
- Library: `nicksnyder/go-i18n/v2`
49+
- Languages: en, zh
50+
51+
### Frontend (`web/src/i18n/`)
52+
- Library: `i18next` + `react-i18next` + `i18next-browser-languagedetector`
53+
- Languages: zh (fallback), en, fr, ru, ja, vi
54+
- Translation files: `web/src/i18n/locales/{lang}.json` — flat JSON, keys are Chinese source strings
55+
- Usage: `useTranslation()` hook, call `t('中文key')` in components
56+
- Semi UI locale synced via `SemiLocaleWrapper`
57+
- CLI tools: `bun run i18n:extract`, `bun run i18n:sync`, `bun run i18n:lint`
58+
59+
## Rules
60+
61+
### Rule 1: JSON Package — Use `common/json.go`
62+
63+
All JSON marshal/unmarshal operations MUST use the wrapper functions in `common/json.go`:
64+
65+
- `common.Marshal(v any) ([]byte, error)`
66+
- `common.Unmarshal(data []byte, v any) error`
67+
- `common.UnmarshalJsonStr(data string, v any) error`
68+
- `common.DecodeJson(reader io.Reader, v any) error`
69+
- `common.GetJsonType(data json.RawMessage) string`
70+
71+
Do NOT directly import or call `encoding/json` in business code. These wrappers exist for consistency and future extensibility (e.g., swapping to a faster JSON library).
72+
73+
Note: `json.RawMessage`, `json.Number`, and other type definitions from `encoding/json` may still be referenced as types, but actual marshal/unmarshal calls must go through `common.*`.
74+
75+
### Rule 2: Database Compatibility — SQLite, MySQL >= 5.7.8, PostgreSQL >= 9.6
76+
77+
All database code MUST be fully compatible with all three databases simultaneously.
78+
79+
**Use GORM abstractions:**
80+
- Prefer GORM methods (`Create`, `Find`, `Where`, `Updates`, etc.) over raw SQL.
81+
- Let GORM handle primary key generation — do not use `AUTO_INCREMENT` or `SERIAL` directly.
82+
83+
**When raw SQL is unavoidable:**
84+
- Column quoting differs: PostgreSQL uses `"column"`, MySQL/SQLite uses `` `column` ``.
85+
- Use `commonGroupCol`, `commonKeyCol` variables from `model/main.go` for reserved-word columns like `group` and `key`.
86+
- Boolean values differ: PostgreSQL uses `true`/`false`, MySQL/SQLite uses `1`/`0`. Use `commonTrueVal`/`commonFalseVal`.
87+
- Use `common.UsingPostgreSQL`, `common.UsingSQLite`, `common.UsingMySQL` flags to branch DB-specific logic.
88+
89+
**Forbidden without cross-DB fallback:**
90+
- MySQL-only functions (e.g., `GROUP_CONCAT` without PostgreSQL `STRING_AGG` equivalent)
91+
- PostgreSQL-only operators (e.g., `@>`, `?`, `JSONB` operators)
92+
- `ALTER COLUMN` in SQLite (unsupported — use column-add workaround)
93+
- Database-specific column types without fallback — use `TEXT` instead of `JSONB` for JSON storage
94+
95+
**Migrations:**
96+
- Ensure all migrations work on all three databases.
97+
- For SQLite, use `ALTER TABLE ... ADD COLUMN` instead of `ALTER COLUMN` (see `model/main.go` for patterns).
98+
99+
### Rule 3: Frontend — Prefer Bun
100+
101+
Use `bun` as the preferred package manager and script runner for the frontend (`web/` directory):
102+
- `bun install` for dependency installation
103+
- `bun run dev` for development server
104+
- `bun run build` for production build
105+
- `bun run i18n:*` for i18n tooling

‎AGENTS.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# AGENTS.md — Project Conventions for new-api
2+
3+
## Overview
4+
5+
This is an AI API gateway/proxy built with Go. It aggregates 40+ upstream AI providers (OpenAI, Claude, Gemini, Azure, AWS Bedrock, etc.) behind a unified API, with user management, billing, rate limiting, and an admin dashboard.
6+
7+
## Tech Stack
8+
9+
- **Backend**: Go 1.22+, Gin web framework, GORM v2 ORM
10+
- **Frontend**: React 18, Vite, Semi Design UI (@douyinfe/semi-ui)
11+
- **Databases**: SQLite, MySQL, PostgreSQL (all three must be supported)
12+
- **Cache**: Redis (go-redis) + in-memory cache
13+
- **Auth**: JWT, WebAuthn/Passkeys, OAuth (GitHub, Discord, OIDC, etc.)
14+
- **Frontend package manager**: Bun (preferred over npm/yarn/pnpm)
15+
16+
## Architecture
17+
18+
Layered architecture: Router -> Controller -> Service -> Model
19+
20+
```
21+
router/ — HTTP routing (API, relay, dashboard, web)
22+
controller/ — Request handlers
23+
service/ — Business logic
24+
model/ — Data models and DB access (GORM)
25+
relay/ — AI API relay/proxy with provider adapters
26+
relay/channel/ — Provider-specific adapters (openai/, claude/, gemini/, aws/, etc.)
27+
middleware/ — Auth, rate limiting, CORS, logging, distribution
28+
setting/ — Configuration management (ratio, model, operation, system, performance)
29+
common/ — Shared utilities (JSON, crypto, Redis, env, rate-limit, etc.)
30+
dto/ — Data transfer objects (request/response structs)
31+
constant/ — Constants (API types, channel types, context keys)
32+
types/ — Type definitions (relay formats, file sources, errors)
33+
i18n/ — Backend internationalization (go-i18n, en/zh)
34+
oauth/ — OAuth provider implementations
35+
pkg/ — Internal packages (cachex, ionet)
36+
web/ — React frontend
37+
web/src/i18n/ — Frontend internationalization (i18next, zh/en/fr/ru/ja/vi)
38+
```
39+
40+
## Internationalization (i18n)
41+
42+
### Backend (`i18n/`)
43+
- Library: `nicksnyder/go-i18n/v2`
44+
- Languages: en, zh
45+
46+
### Frontend (`web/src/i18n/`)
47+
- Library: `i18next` + `react-i18next` + `i18next-browser-languagedetector`
48+
- Languages: zh (fallback), en, fr, ru, ja, vi
49+
- Translation files: `web/src/i18n/locales/{lang}.json` — flat JSON, keys are Chinese source strings
50+
- Usage: `useTranslation()` hook, call `t('中文key')` in components
51+
- Semi UI locale synced via `SemiLocaleWrapper`
52+
- CLI tools: `bun run i18n:extract`, `bun run i18n:sync`, `bun run i18n:lint`
53+
54+
## Rules
55+
56+
### Rule 1: JSON Package — Use `common/json.go`
57+
58+
All JSON marshal/unmarshal operations MUST use the wrapper functions in `common/json.go`:
59+
60+
- `common.Marshal(v any) ([]byte, error)`
61+
- `common.Unmarshal(data []byte, v any) error`
62+
- `common.UnmarshalJsonStr(data string, v any) error`
63+
- `common.DecodeJson(reader io.Reader, v any) error`
64+
- `common.GetJsonType(data json.RawMessage) string`
65+
66+
Do NOT directly import or call `encoding/json` in business code. These wrappers exist for consistency and future extensibility (e.g., swapping to a faster JSON library).
67+
68+
Note: `json.RawMessage`, `json.Number`, and other type definitions from `encoding/json` may still be referenced as types, but actual marshal/unmarshal calls must go through `common.*`.
69+
70+
### Rule 2: Database Compatibility — SQLite, MySQL >= 5.7.8, PostgreSQL >= 9.6
71+
72+
All database code MUST be fully compatible with all three databases simultaneously.
73+
74+
**Use GORM abstractions:**
75+
- Prefer GORM methods (`Create`, `Find`, `Where`, `Updates`, etc.) over raw SQL.
76+
- Let GORM handle primary key generation — do not use `AUTO_INCREMENT` or `SERIAL` directly.
77+
78+
**When raw SQL is unavoidable:**
79+
- Column quoting differs: PostgreSQL uses `"column"`, MySQL/SQLite uses `` `column` ``.
80+
- Use `commonGroupCol`, `commonKeyCol` variables from `model/main.go` for reserved-word columns like `group` and `key`.
81+
- Boolean values differ: PostgreSQL uses `true`/`false`, MySQL/SQLite uses `1`/`0`. Use `commonTrueVal`/`commonFalseVal`.
82+
- Use `common.UsingPostgreSQL`, `common.UsingSQLite`, `common.UsingMySQL` flags to branch DB-specific logic.
83+
84+
**Forbidden without cross-DB fallback:**
85+
- MySQL-only functions (e.g., `GROUP_CONCAT` without PostgreSQL `STRING_AGG` equivalent)
86+
- PostgreSQL-only operators (e.g., `@>`, `?`, `JSONB` operators)
87+
- `ALTER COLUMN` in SQLite (unsupported — use column-add workaround)
88+
- Database-specific column types without fallback — use `TEXT` instead of `JSONB` for JSON storage
89+
90+
**Migrations:**
91+
- Ensure all migrations work on all three databases.
92+
- For SQLite, use `ALTER TABLE ... ADD COLUMN` instead of `ALTER COLUMN` (see `model/main.go` for patterns).
93+
94+
### Rule 3: Frontend — Prefer Bun
95+
96+
Use `bun` as the preferred package manager and script runner for the frontend (`web/` directory):
97+
- `bun install` for dependency installation
98+
- `bun run dev` for development server
99+
- `bun run build` for production build
100+
- `bun run i18n:*` for i18n tooling

‎CLAUDE.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# CLAUDE.md — Project Conventions for new-api
2+
3+
## Overview
4+
5+
This is an AI API gateway/proxy built with Go. It aggregates 40+ upstream AI providers (OpenAI, Claude, Gemini, Azure, AWS Bedrock, etc.) behind a unified API, with user management, billing, rate limiting, and an admin dashboard.
6+
7+
## Tech Stack
8+
9+
- **Backend**: Go 1.22+, Gin web framework, GORM v2 ORM
10+
- **Frontend**: React 18, Vite, Semi Design UI (@douyinfe/semi-ui)
11+
- **Databases**: SQLite, MySQL, PostgreSQL (all three must be supported)
12+
- **Cache**: Redis (go-redis) + in-memory cache
13+
- **Auth**: JWT, WebAuthn/Passkeys, OAuth (GitHub, Discord, OIDC, etc.)
14+
- **Frontend package manager**: Bun (preferred over npm/yarn/pnpm)
15+
16+
## Architecture
17+
18+
Layered architecture: Router -> Controller -> Service -> Model
19+
20+
```
21+
router/ — HTTP routing (API, relay, dashboard, web)
22+
controller/ — Request handlers
23+
service/ — Business logic
24+
model/ — Data models and DB access (GORM)
25+
relay/ — AI API relay/proxy with provider adapters
26+
relay/channel/ — Provider-specific adapters (openai/, claude/, gemini/, aws/, etc.)
27+
middleware/ — Auth, rate limiting, CORS, logging, distribution
28+
setting/ — Configuration management (ratio, model, operation, system, performance)
29+
common/ — Shared utilities (JSON, crypto, Redis, env, rate-limit, etc.)
30+
dto/ — Data transfer objects (request/response structs)
31+
constant/ — Constants (API types, channel types, context keys)
32+
types/ — Type definitions (relay formats, file sources, errors)
33+
i18n/ — Backend internationalization (go-i18n, en/zh)
34+
oauth/ — OAuth provider implementations
35+
pkg/ — Internal packages (cachex, ionet)
36+
web/ — React frontend
37+
web/src/i18n/ — Frontend internationalization (i18next, zh/en/fr/ru/ja/vi)
38+
```
39+
40+
## Internationalization (i18n)
41+
42+
### Backend (`i18n/`)
43+
- Library: `nicksnyder/go-i18n/v2`
44+
- Languages: en, zh
45+
46+
### Frontend (`web/src/i18n/`)
47+
- Library: `i18next` + `react-i18next` + `i18next-browser-languagedetector`
48+
- Languages: zh (fallback), en, fr, ru, ja, vi
49+
- Translation files: `web/src/i18n/locales/{lang}.json` — flat JSON, keys are Chinese source strings
50+
- Usage: `useTranslation()` hook, call `t('中文key')` in components
51+
- Semi UI locale synced via `SemiLocaleWrapper`
52+
- CLI tools: `bun run i18n:extract`, `bun run i18n:sync`, `bun run i18n:lint`
53+
54+
## Rules
55+
56+
### Rule 1: JSON Package — Use `common/json.go`
57+
58+
All JSON marshal/unmarshal operations MUST use the wrapper functions in `common/json.go`:
59+
60+
- `common.Marshal(v any) ([]byte, error)`
61+
- `common.Unmarshal(data []byte, v any) error`
62+
- `common.UnmarshalJsonStr(data string, v any) error`
63+
- `common.DecodeJson(reader io.Reader, v any) error`
64+
- `common.GetJsonType(data json.RawMessage) string`
65+
66+
Do NOT directly import or call `encoding/json` in business code. These wrappers exist for consistency and future extensibility (e.g., swapping to a faster JSON library).
67+
68+
Note: `json.RawMessage`, `json.Number`, and other type definitions from `encoding/json` may still be referenced as types, but actual marshal/unmarshal calls must go through `common.*`.
69+
70+
### Rule 2: Database Compatibility — SQLite, MySQL >= 5.7.8, PostgreSQL >= 9.6
71+
72+
All database code MUST be fully compatible with all three databases simultaneously.
73+
74+
**Use GORM abstractions:**
75+
- Prefer GORM methods (`Create`, `Find`, `Where`, `Updates`, etc.) over raw SQL.
76+
- Let GORM handle primary key generation — do not use `AUTO_INCREMENT` or `SERIAL` directly.
77+
78+
**When raw SQL is unavoidable:**
79+
- Column quoting differs: PostgreSQL uses `"column"`, MySQL/SQLite uses `` `column` ``.
80+
- Use `commonGroupCol`, `commonKeyCol` variables from `model/main.go` for reserved-word columns like `group` and `key`.
81+
- Boolean values differ: PostgreSQL uses `true`/`false`, MySQL/SQLite uses `1`/`0`. Use `commonTrueVal`/`commonFalseVal`.
82+
- Use `common.UsingPostgreSQL`, `common.UsingSQLite`, `common.UsingMySQL` flags to branch DB-specific logic.
83+
84+
**Forbidden without cross-DB fallback:**
85+
- MySQL-only functions (e.g., `GROUP_CONCAT` without PostgreSQL `STRING_AGG` equivalent)
86+
- PostgreSQL-only operators (e.g., `@>`, `?`, `JSONB` operators)
87+
- `ALTER COLUMN` in SQLite (unsupported — use column-add workaround)
88+
- Database-specific column types without fallback — use `TEXT` instead of `JSONB` for JSON storage
89+
90+
**Migrations:**
91+
- Ensure all migrations work on all three databases.
92+
- For SQLite, use `ALTER TABLE ... ADD COLUMN` instead of `ALTER COLUMN` (see `model/main.go` for patterns).
93+
94+
### Rule 3: Frontend — Prefer Bun
95+
96+
Use `bun` as the preferred package manager and script runner for the frontend (`web/` directory):
97+
- `bun install` for dependency installation
98+
- `bun run dev` for development server
99+
- `bun run build` for production build
100+
- `bun run i18n:*` for i18n tooling

0 commit comments

Comments
 (0)