st-react/CLAUDE.md

CLAUDE.md

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

Project Overview

云酒馆 (SillyTavern Cloud) — a full-stack AI role-playing chat platform. Frontend is React + TypeScript + Tailwind + Vite (web-app/). Backend is Go + Gin + GORM (server/). The two are fully separated and communicate via REST API + SSE streaming.

Build & Run Commands

Frontend (web-app/)

npm install
npm run dev        # Dev server at http://localhost:5174
npm run build      # tsc + vite build (type-check then bundle)
npm run preview    # Preview production build

Backend (server/)

go mod tidy
go build -o server .
./server -c config.yaml    # Runs at http://localhost:8888

Type-check only (no emit)

# Frontend
cd web-app && npx tsc --noEmit

# Backend
cd server && go build ./...

Build Verification

After any code edit, always run the build/compile step before reporting success. For Go files: go build ./.... For TypeScript files: npx tsc --noEmit. Never assume edits are correct without verification.

Architecture

Backend (server/)

Layered architecture: routes → API handlers → services → models/DB

api/v1/app/        # App-facing HTTP handlers (auth, character, conversation, ai_config, etc.)
api/v1/system/     # Admin/system handlers
service/app/       # Business logic layer
model/app/         # GORM data models (AppUser, AiCharacter, Conversation, Preset, Worldbook, RegexScript)
router/app/        # Gin route registration
middleware/        # JWT auth, CORS, logging, recovery
initialize/        # DB, Redis, router, plugin setup (called from main.go)
core/              # Zap logging, Viper config loading, server startup

Key models: AppUser, AiCharacter (SillyTavern V2 card format), Conversation, Preset (sampling params), Worldbook (keyword-triggered context), RegexScript (message transforms).

AI providers: OpenAI-compatible + Anthropic. Unified through the AI config service. Conversations use SSE streaming for real-time token delivery.

Frontend (web-app/src/)

MVU (Model-View-Update) pattern via Zustand with persist middleware (localStorage).

store/index.ts     # Single global Zustand store — source of truth for user, currentCharacter,
                   # currentConversation, messages, variables, UI state
api/               # One file per domain: auth, character, conversation, preset, worldbook, regex
                   # All share the axios instance in api/client.ts (injects JWT, handles 401)
pages/             # Route-level components (ChatPage, CharacterManagePage, AdminPage, etc.)
components/        # Reusable UI — ChatArea, CharacterPanel, SettingsPanel, Sidebar, Navbar,
                   # MessageContent (renders markdown + HTML safely via rehype-sanitize)

Routes are defined in App.tsx. Auth guard redirects to /login when isAuthenticated is false.

The variables: Record<string, string> field in the store implements the MVU variable system used for template substitution in AI prompts (e.g., {{user}}, {{char}}).

API Convention

• Base URL: http://localhost:8888 (configured via VITE_API_BASE_URL in .env.development)
• Auth: Authorization: Bearer <jwt> header, injected automatically by api/client.ts
• App routes: /app/auth/..., /app/user/..., /app/character/..., /app/conversation/...
• Admin routes: /system/... (Casbin RBAC enforced)

Go Development

When editing Go files, always check all call sites of modified functions. If a function signature changes (parameters or return values), grep for all usages and update them in the same edit batch.

Run go build ./... from server/ to verify after every edit.

Frontend Development

When editing Vue/TypeScript frontend files, verify all imports are present and no duplicate code remains after edits. Read the file back after editing to confirm structural integrity.

Run npx tsc --noEmit from web-app/ to verify after every edit.

Third-Party Integrations

When integrating third-party SDKs or APIs (payment providers, AI model APIs), read the actual SDK source or docs first before writing code. Do not guess method names, parameter types, or key sizes.

Configuration

Backend config file: server/config.yaml (not committed; copy from config.example.yaml if present). Supports MySQL, PostgreSQL, SQLite, SQL Server, Oracle via GORM. Redis for sessions/caching.

Frontend env files: web-app/.env.development and web-app/.env.production — set VITE_API_BASE_URL.