# CLAUDE.md

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

## Architecture

- Repo shape - monorepo-style workspace split across `base_platform/`, `saas_portal/`, `training_center/`, `industry_accelerator/`, `data_center/`, `design-system/`, `llm_service/`, and `shared/`
- `base_platform/` - shared FastAPI core and local infra hub; `app/main.py` wires tenant context, i18n, rate limiting, traffic monitoring, and the main API surface
- `saas_portal/backend/` - plugin-host FastAPI service; startup loads accelerator backends from `industry_accelerator/` via `PluginLoader` and mounts their routers into the portal API
- `saas_portal/frontend/` - main Vue/Vite application; depends on `saas_portal/shared` and aliases the local design system source from `design-system/`
- `saas_portal/shared/` - shared frontend package for reusable utilities/composables used by workspace apps
- `design-system/` - LeShui UI source package exported from `components/index.ts`; consumed through workspace/aliasing rather than as a separate running app
- `training_center/` - standalone product with its own FastAPI backend and Vue frontend; backend owns expert-training domains like tasks, experts, datasets, tools, SFT/DPO tasks, templates, and websocket endpoints
- `industry_accelerator/tax/` - tax-specific accelerator; backend is a standalone FastAPI service, frontend is a Vite library package built from `src/index.ts`
- `data_center/` - content storage module managing scraped external content in three formats: `content_html` (original HTML for preventing duplicate scraping), `content_markdown` (cleaned format for frontend display), `content_text` (plain text for RAG knowledge base and vectorization)
- `llm_service/` - local model hosting layer; `base_models/` stores pretrained model weights, `trained_models/` stores fine-tuned checkpoints with per-job output directories, `servers/` contains OpenAI-compatible FastAPI servers (`embedding_server.py` for sentence-transformers embeddings, `rerank_server.py` for cross-encoder reranking); main LLM inference is served via vLLM or MLX externally
- `shared/common_logging/` - unified logging package consumed by all backend services via `pip install -e`; provides `setup_logging()` (loguru + InterceptHandler bridge for stdlib), `get_logger()`, `LoggingMiddleware` (request_id / context propagation / duration tracking), and decorators (`log_execution`, `log_errors`, `log_performance`)
- `shared/common_metrics/` - unified Prometheus metrics package; call `setup_metrics(app, service_name)` in each service `main.py` to expose `/metrics` endpoint
- `shared/common_langfuse/` - Langfuse tracing integration package for LLM observability
- `apm/` - observability stack managed via Docker Compose; contains Prometheus, Grafana, Tempo, Loki, Promtail, and Langfuse (under `apm/langfuse/`); started/stopped together with `scripts/services-start.sh` and `scripts/services-stop.sh`

## Relationships

- Dependency flow - `base_platform` provides shared platform services; `saas_portal` is the main app shell; accelerators in `industry_accelerator/` extend portal behavior
- Frontend composition - `saas_portal/frontend` is the main consumer of both `saas_portal/shared` and `design-system`
- Extension model - accelerator backends plug into `saas_portal/backend`; accelerator frontends/packages live beside them under `industry_accelerator/`
- Product split - `training_center/` is parallel to the portal stack, not just a submodule of `saas_portal/`
- Content pipeline - `data_center` stores scraped content; `content_html` preserves originals, `content_markdown` feeds frontend display, `content_text` feeds RAG/vectorization for AI retrieval

## Code Conventions

- No comments - write self-explanatory code without comments
- Documentation location - place all new documentation files in `docs/` at project root
- Script location - place all new scripts in `scripts/` at project root
- Language - use English for all code, documentation, and commit messages
- Format and linting - follow the code style guide in `docs/code-style-guide.md`; Python uses Black (line-length 100) and Ruff, frontend uses Prettier (100 chars, single quotes) and ESLint 9.x

## Logging Conventions

- Always use `common_logging` package — never use `import logging` or `from loguru import logger` directly
- Logger initialization: `from common_logging import get_logger` then `logger = get_logger(__name__)` at module level
- Never use `print()` for any diagnostic or operational output — use logger instead
- Never swallow exceptions silently — every `except` block must either log or re-raise (or both)
- Use structured context via `.bind()` instead of f-string interpolation: `logger.bind(tenant_id=tid, task_id=task_id).info("Task created")` not `logger.info(f"Task {task_id} created for tenant {tid}")`
- Log levels: `debug` for expected control flow / diagnostics, `info` for state transitions and key operations, `warning` for recoverable issues, `error` for failures that need attention
- Use `.opt(exception=True)` or `logger.exception()` when logging caught exceptions that need tracebacks
- Decorators usage: `@log_execution(logger)` on service orchestration methods, `@log_performance(logger, threshold_ms=N)` on external calls (HTTP, DB, Neo4j), `@log_errors(logger)` on complex route handlers
- Route handlers: rely on `LoggingMiddleware` for request lifecycle; only add explicit logging for errors and validation failures
- CRUD layer: log on write operations (create/update/delete) with entity ID, skip read-only queries
- Background tasks (Celery): always use `@log_execution(logger)` and log task_id
- Service entry points (`main.py`): must call `setup_logging()`, create module logger, and add `LoggingMiddleware`

## Interaction Conventions

- Always communicate with me in Chinese