# CLAUDE.md

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

## Project Overview

KiloStar is a distributed multi-agent system. Python/FastAPI backend with Ray actor orchestration, React 19 frontend, PostgreSQL storage. Supports two deployment modes: standalone (pure asyncio) and distributed (full Ray cluster).

## Commands

### Backend
```bash
uv sync                                    # Install Python deps
uv run python main.py                      # Start distributed mode
KILOSTAR_MODE=standalone uv run python main.py  # Start standalone mode
```

### Frontend (this directory)
```bash
npm install          # Install deps
npm run dev          # Dev server (Vite)
npm run build        # Production build
npm run lint         # ESLint
npx tsc --noEmit    # Type-check without emitting
```

### Database Migrations (from project root)
```bash
make db-revision m="description"   # Generate migration
make db-upgrade                    # Apply to HEAD
make db-downgrade                  # Rollback one
```

### Testing (from project root)
```bash
uv run pytest tests -q              # Full suite
uv run pytest tests/unit -q         # Unit only
uv run pytest tests/integration -q  # Integration (needs DB)
```

### Docker
```bash
docker-compose up -d    # Full stack (frontend build + backend)
```

## Architecture

### Dual-Mode Actor System

All core components are Ray actors in distributed mode, plain Python instances in standalone mode. Code uses a unified call pattern:

```python
from kilostar.utils.ray_hook import ray_actor_hook

# Returns a namespace object with actor handles
actors = ray_actor_hook("postgres_database")
await actors.postgres_database.some_method.remote(arg)
```

`StandaloneProxy` (in `kilostar/utils/standalone_proxy.py`) wraps instances to expose the same `.method.remote()` interface via asyncio. The `@actor_class` decorator marks classes that can be Ray actors or standalone instances depending on mode.

Mode is set via `KILOSTAR_MODE` env var. Entry point `main.py` branches into `start_standalone()` or `start_distributed()`.

### Backend Layout (`kilostar/`)

- `api/` — FastAPI routers (auth, chat, agent, workflow, system, resource, platform)
- `core/individual/` — 4 node types: RegulatoryNode (user-facing QA), ConsciousnessNode (planning), ControlNode (routing), GrowthNode (capability expansion)
- `core/global_state_machine/` — Provider registry, model config state
- `core/global_workflow_manager/` — Workflow queue & recovery
- `core/postgres_database/` — DAO layer: `model/` (SQLAlchemy models), `module/` (CRUD methods), `postgres.py` (facade)
- `worker_cluster/` — Task queue & worker dispatch
- `adapter/` — LLM model adapters (pydantic-ai AgentFactory)
- `plugin/tool_plugin/` — MCP-style tool plugins
- `utils/` — ray_hook, standalone_proxy, config_loader, access (JWT), i18n

### Frontend Layout (`frontend/src/`)

- `store/` — Zustand stores (useAppStore, useChatStore, etc.)
- `components/` — Chat, Agent, Plugin, Settings, Layout
- `api/client.ts` — Axios instance with auth interceptor
- `i18n/` — Chinese + English translations

### Key Patterns

- **Database facade**: `postgres.py` delegates to per-entity modules (`module/chat_history.py`, `module/persona_template.py`, etc.). Always add new DB methods to both the module AND the facade.
- **pydantic-ai agents**: Regulatory/Consciousness nodes use pydantic-ai with structured output (tool calls). Streaming chat uses direct httpx calls to OpenAI-compatible API instead.
- **SSE streaming**: Chat stream endpoint uses `StreamingResponse(media_type="text/event-stream")` with `data: {json}\n\n` format.
- **Config**: Multi-YAML in `config/` directory, loaded via `config_loader.py` at startup.
- **Alembic migrations**: `alembic/versions/` — naming convention: `YYYY_MM_DD_HHMM-NNNN_description.py`

### Environment Variables

- `KILOSTAR_MODE` — `standalone` or omit for distributed
- `KILOSTAR_SECRET_KEY` — JWT signing key
- `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` — DB connection
- `KILOSTAR_ENV` — `dev` or `prod`