CLAUDE.md

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

Commands

Backend (Go)

go build                    # build backend binary
go run main.go              # run backend (port 14000)
go test ./...               # run all tests
go test ./object/... -run TestFoo  # run a single test

Frontend (React + shadcn/ui, built with Vite)

cd web && yarn install
yarn start                  # dev server on port 13001, proxies /api to localhost:14000
yarn build                  # production build (vite writes build-temp, mv.js swaps it into web/build)
yarn typecheck              # tsc --noEmit
yarn lint                   # eslint

web-old/ holds the previous Ant Design frontend. It is kept for reference only while bugs are chased down against it — it is not built, served or linted, and it does not get new work.

Full production build uses build.sh which cross-compiles for linux/amd64, linux/arm64, linux/riscv64.

Backend serves the frontend as embedded static files (embed.go); during development the frontend proxy is configured to hit localhost:14000.

Architecture

Backend (Go / Beego)

Module: github.com/the-open-agent/openagent

The backend is a standard Beego MVC app. Every entity follows the same three-layer pattern:

1. object/<entity>.go — struct definition (xorm tags for DB), and all DB access functions: GetGlobal<Entities>, Get<Entity>Count, GetPagination<Entities>, Get<Entity>, Add<Entity>, Update<Entity>, Delete<Entity>. The primary key is always (Owner string, Name string). Use util.GetId(owner, name) / util.GetOwnerAndNameFromIdWithError(id) for composite key serialization.
2. controllers/<entity>.go — Beego controller methods wired to routes. Standard set: GetGlobal<Entities>, Get<Entities>, Get<Entity>, Add<Entity>, Update<Entity>, Delete<Entity>. Use c.IsAdmin() / c.IsGlobalAdmin() / c.RequireSignedIn() for auth. Paginated list APIs accept p, pageSize, field, value, sortField, sortOrder query params and use pagination.SetPaginator.
3. routers/router.go — beego.Router calls grouped by entity (all routes for the same entity's CRUD kept together). No alphabetical ordering within a group. New entity routes should be inserted next to their entity's existing routes (not appended to the end of the file).

DB schema is auto-migrated via object/adapter.go → createTable() using engine.Sync2(new(EntityStruct)). Add new entities there.

i18n (backend): i18n/locales/{en,zh}/data.json — keys are namespaced by category (e.g. "comment:...", "general:..."). Use c.T("namespace:key") in controllers.

Frontend (React + shadcn/ui on Tailwind, TypeScript, Vite)

Routing lives in web/src/App.tsx; every file in web/src/pages is its own lazy chunk, loaded by name. To add a new admin page:

1. Create web/src/pages/<Name>Page.tsx (default export).
2. Add a <Route> in App.tsx pointing at page("<Name>Page").
3. Add a menu entry in getNavGroups() (web/src/lib/nav.ts), in the correct group — Basic / Connectors / Admin etc.
4. Add the nav key to web/src/components/common/NavItemTree.tsx so it appears in the site Navbar Items config.

Page pattern: list pages render CrudListPage (web/src/components/crud/) with a ColumnDef[]; edit pages render SimpleEditPage with an EditField[], or compose EditPageShell directly when the layout is custom. Both patterns are illustrated by MessageListPage.tsx / MessageEditPage.tsx.

Backend API layer: web/src/backend/<Entity>Backend.ts — thin fetch() wrappers, one file per entity. Standard exports: getGlobal<Entities>, get<Entity>, update<Entity>, add<Entity>, delete<Entity>.

Per-instance config: the backend sends the Casdoor issuer, client ID and branding in the jsonWebConfig cookie (set with index.html and with every /api/get-account response) and web/src/Conf.ts reads it at boot, so one build serves every instance.

i18n (frontend): web/src/locales/{en,zh}/data.json namespaced by page/domain. Use i18next.t("namespace:key").

Key conventions

• Owner is always "admin" for system-created entities.
• Entity Name is a random string generated with util.GetRandomString(n) or a user-provided slug.
• CreatedTime / UpdatedTime use util.GetCurrentTimeWithMilli() (string format).
• Delete responses use affected != 0 boolean pattern.
• All API responses go through c.ResponseOk(data) or c.ResponseError(msg).
• The conf/app.conf file configures DB (driverName, dataSourceName, dbName) and port (httpport = 14000).