---
name: langbot-dev
description: Develop, build, and debug the LangBot core backend and web frontend. Use when working inside the LangBot repository — backend (Python/Quart, src/langbot/pkg), the Vite/React web UI, HTTP API controllers/services, Alembic migrations, or the MCP server. Covers the dev environment (uv, pnpm), repo layout, the API auth model (user token / API key / global key), adding API endpoints, and the rule that API changes must update the MCP server and skills. Triggers on "langbot backend", "langbot dev", "langbot api", "add langbot endpoint", "langbot migration".
---

# LangBot Core Development

This skill covers developing the LangBot core (the main repo), distinct from
plugin development (see `langbot-plugin-dev`) and deployment (`langbot-deploy`).

## Stack

- **Backend**: Python `>=3.11,<4.0`, deps via `uv`. Framework: **Quart** (async
  Flask). Serves the HTTP API + pre-built web UI on `http://127.0.0.1:5300`.
- **Frontend** (`web/`): **Vite + React Router 7 + shadcn/ui + Tailwind**,
  managed by `pnpm`. Dev server on `:3000`. (NOT Next.js — `dev` script is `vite`.)

## Dev environment

```bash
# Backend
pip install uv
uv sync --dev
uv run main.py            # API + UI on http://127.0.0.1:5300

# Frontend (separate terminal)
cd web
cp .env.example .env
pnpm install
pnpm dev                  # http://127.0.0.1:3000 (reads VITE_API_BASE_URL)

# Lint/format hooks (CI runs the same checks)
uv run pre-commit install
```

First run generates `data/config.yaml`; DB defaults to SQLite (PostgreSQL
supported). Migrations run automatically on startup.

## Repo layout (key paths)

```
src/langbot/
├── __main__.py             # entrypoint, CLI flags (--standalone-runtime/-box/--debug)
├── pkg/
│   ├── api/
│   │   ├── http/           # Quart controllers + services
│   │   │   ├── controller/groups/   # route groups (@group.group_class)
│   │   │   └── service/             # business logic (called by controllers AND MCP)
│   │   └── mcp/            # MCP server (server.py = tools, mount.py = ASGI dispatch)
│   ├── core/               # app bootstrap, stages, task manager
│   ├── platform/ provider/ pipeline/ plugin/ box/ skill/ rag/ vector/
│   ├── command/ persistence/ storage/ config/ entity/ telemetry/
│   └── templates/config.yaml        # config template (top-level: api, system, plugin, box, space...)
├── web/                    # Vite SPA
└── docker/                 # compose deployment
```

## HTTP API auth model

Route auth is declared per-route via `AuthType` in
`pkg/api/http/controller/group.py`:

- `NONE` — public.
- `USER_TOKEN` — web UI JWT (`Authorization: Bearer <jwt>`).
- `API_KEY` — `X-API-Key` or `Authorization: Bearer <key>`.
- `USER_TOKEN_OR_API_KEY` — either.

API keys are verified by `apikey_service.verify_api_key()`, which accepts:
1. the **global key** from `config.yaml` `api.global_api_key` (no DB, no login,
   no `lbk_` prefix required), then
2. **web-UI keys** (DB-stored, `lbk_` prefix).

Route groups self-register via `@group.group_class(name, path)` and are
discovered by `importutil.import_modules_in_pkg`.

## Adding an API endpoint

1. Add/extend a controller in `pkg/api/http/controller/groups/` and the matching
   service method in `pkg/api/http/service/`.
2. Pick the right `AuthType`.
3. **If the endpoint should be agent-accessible, add/adjust the matching MCP tool
   in `pkg/api/mcp/server.py` and update the `langbot-mcp-ops` skill.** API and
   MCP surface must stay aligned (see `AGENTS.md`).
4. Update `docs/service-api-openapi.json` if you maintain the OpenAPI overview.

## Database migrations (Alembic)

Single migration set supports SQLite + PostgreSQL. Files in
`src/langbot/pkg/persistence/alembic/versions/`.

```bash
# From project root (needs data/config.yaml)
uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "description"
```

## Standards

- All code comments/docstrings in **English**; user-facing strings need **i18n**
  (`en_US` + `zh_Hans` minimum, `ja_JP` where present).
- Consider toC and toB compatibility + security.
- Commit format: `<type>(<scope>): <subject>` (feat/fix/docs/refactor/...).

## Tests

```bash
uv run pytest tests/unit_tests -q          # unit tests
uv run pytest tests/unit_tests/api -q      # API service tests
uv run python tests/manual/mcp_smoke.py    # MCP server e2e smoke
```

## See also

- `langbot-plugin-dev` — plugin SDK / runtime development.
- `langbot-testing` — WebUI/e2e QA harness (`bin/lbs`).
- `langbot-deploy` — Docker/compose deployment + config.
- `langbot-mcp-ops` — operating the LangBot MCP server.
