socweb/CLAUDE.md

CLAUDE.md

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

Overview

so-c-chat-clone — 企业级 Gemini 风格对话系统，前后端分离。

• 前端 (frontend/): Next.js 16 + React 19 + Tailwind CSS 4 + shadcn/ui，1:1 复刻 Google Gemini UI
• 后端 (backend/): LangChain + LangGraph + Litestar，基于 LangGraph 编排的对话 Agent

Project Structure

├── frontend/          # Next.js 前端（前端代码未经明确指定不允许修改）
├── backend/           # Python 后端（LangChain + LangGraph）
├── gpthd.md           # 后端功能方案（18项功能，开发前必读）
├── EXTERNAL_SERVICES.md  # 外部服务凭据与接入配置
└── claudehd.md        # 后端技术方案（按功能拆解）

Frontend

Commands

cd frontend
npm install && npm run dev     # Dev server (localhost:3000)
npm run build                  # Production build
npm run lint                   # ESLint

Architecture

• Entry: frontend/app/page.tsx → <GeminiChat />
• GeminiChat.tsx owns all state, composes sidebar/topbar/input/message/welcome components
• GeminiInput.tsx has activeTools (Set<string>) and selectedModel ("flash"|"pro") as local state
• simulateAIResponse() is the mock function to be replaced by real backend API
• All mock data (conversations, tickets) lives in GeminiChat.tsx
• Dark theme only, hardcoded palette (#131314 bg, #1e1e1e sidebar, #4285f4→#a855f7 gradient)

Backend

Tech Stack

• Web: Litestar + Uvicorn
• Graph: LangGraph StateGraph + create_react_agent (ReAct)
• LLM: LangChain AzureChatOpenAI (gpt-5.4)
• Tools: LangChain @tool (KB search, Jina web search, Daytona sandbox, Doc Creator, Gongdan tickets)
• DB: PostgreSQL + asyncpg + LangGraph AsyncPostgresSaver
• Cache: Redis (Azure)
• Storage: Azure Blob Storage
• Async: Azure Service Bus

Commands

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt    # Or: pip install -e .
uvicorn app.main:app --port 8000 --reload   # Dev server

Core API

POST /api/chat/stream     # SSE streaming chat (replaces simulateAIResponse)
GET  /api/conversations   # List conversations
POST /api/conversations   # Create conversation
GET  /api/tickets         # Proxy to Gongdan ticket system
GET  /health              # Health check

Development Phases (see gpthd.md for full details)

1. Basic chat graph + PostgreSQL + SSE streaming
2. Tool integration (KB Agent, tickets, ReAct routing)
3. External search (Jina Search/Reader/Rerank) + Redis cache
4. Doc generation + Sandbox + Blob Storage + Service Bus

External Services

All credentials in EXTERNAL_SERVICES.md. Key services:

Service	Purpose
Azure OpenAI (gpt-5.4)	LLM generation
KB Agent (Azure AI Search)	Internal knowledge retrieval
Jina AI (Search/Reader/Rerank)	External web search
Daytona	Sandboxed code execution
Doc Creator Agent	Word/PPT/Excel generation
Gongdan API	Ticket system (read-only)
PostgreSQL (Azure)	Persistence
Redis (Azure)	Caching
Azure Blob Storage	File storage
Azure Service Bus	Async task queue

Constraints

• Frontend code is read-only unless explicitly authorized. Only approved change: extending onSubmit to pass tools[] and model to backend.
• Azure resources must stay within AuthData and Operation resource groups only.
• CI/CD is managed by the user, not by agents.
• Tool invocation policy: User-selected tools are passed to the LangGraph ReAct Agent as available tools. The Agent decides whether to actually use them. If it decides not to, it must explain why in its response.