KiloStar/frontend/CLAUDE.md

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

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)

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)

make db-revision m="description"   # Generate migration
make db-upgrade                    # Apply to HEAD
make db-downgrade                  # Rollback one

Testing (from project root)

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

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:

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