Skip to content

Kaiwu · 开物载道 v0.3.0 · Apache-2.0 Open Source

Product & AI build the frontend.Kaiwu keeps delivery controllable.

Product-led frontend, wired and shipped by backend engineers; standalone repos and in-repo gates let any developer or AI tool take over on a shared enterprise core.

Kaiwu solves two core problems in enterprise AI development: Product-led frontend—product teams start directly in kaiwu-web-starter or a generated React repo with built-in persona mocks, adopt into the platform via project adopt, and let backend engineers wire Spring Boot APIs with zero rewrite; and Controllable delivery—every app ships as standalone repos with AGENTS.md, rules, scenarios, and verify gates so swapping engineers or AI models never causes drift.

  • Product-Led · Zero-Rewrite HandoffStart in a standalone mock frontend, adopt into Kaiwu, and ship the exact same React repo
  • Controllable · Portable HandoffScoped repos, rule/scenario gates, and SQL row-scope checks prevent drift across tools
  • Thin Platform · Enterprise GovernanceCross-env config handover, STS storage, unified tasks, and MySQL/DM8; 100% independent apps
WorkbenchOne account across authorized apps, with unified tasks and notifications
DESIGN PHILOSOPHY · WHY KAIWU EXISTS

Why a “Thin Platform + Standalone Business Repositories”?

Teams building multiple internal apps often get stuck between two extremes: heavy monolithic platforms and low-code black boxes on one side, or drifting copied scaffolds and unverified AI code on the other. Kaiwu resolves this tension with three clear boundaries.

01Clear Boundaries · Zero Lock-In

Shared enterprise governance, 100% independent apps

The common trap: Heavy platforms tangle shared modules with business code—upgrading the platform risks breaking apps, and app changes slow down the platform.

The Kaiwu way: Gateway, SSO, project roles, dictionaries, i18n, and tasks live in the shared platform. Each business project is scaffolded or adopted once into its own frontend & backend Git repos and database, ready to evolve and deploy independently.

02Optional AI · Deterministic Output

AI proposes validated blueprints; templates render code

The common trap: Asking an LLM to generate a full project from scratch produces code that runs locally but misses permission checks, migrations, audit logs, and CI contracts.

The Kaiwu way: AI handles product UI, validated blueprints, or single-repo iteration, while structure, the @/kaiwu integration layer, auth wiring, and CI gates are deterministically rendered from versioned templates.

03Focused Context · Executable Gates

Turn engineering conventions into in-repo checks

The common trap: Giant monorepos overflow AI context windows, causing missed edits, while unwritten team conventions decay across developers and models.

The Kaiwu way: Each business repo stays small and ships with AGENTS.md, verify:mock, and verify.sh. Backend annotations, frontend checks, and menus.yml share identical permission codes—linked with rules and scenarios.

PRODUCT-LED FRONTEND · ZERO-PLATFORM MOCK TO RELEASE

The screen your product team reviews is the one you ship

Start directly from the open-source frontend starter with AI and built-in mocks—no platform, container, or database needed—then hand off via Git and generate the companion backend in one workflow, all in the same frontend repository.

Product + AI · Zero-Platform MockBuild persona-tested pages locally

Have AI fetch the frontend starter to build pages or the two-user booking demo, switch roles locally to test flows, and reset in-memory data anytime—no platform, Docker, or JDK required.

Git Handoff · Rules + ManifestsFreeze contracts on product branch & hand off

Commit pages, service types, menu manifests, numbered business rules, and acceptance scenarios in the same repo, then open a handoff merge request instead of relying on screenshots or verbal notes.

Backend + AI · Adopt & WireAdopt once, scaffold backend, ship together

Run one adopt command to register the frontend and generate the Spring Boot backend, re-verify all acceptance scenarios through the gateway, and ship with mock routes stripped from production builds.

Zero-platform built-in mock runtimeReady to demo

Includes dev-server request interception, a role-switcher panel, and clear fallbacks for unimplemented endpoints—needing only a lightweight frontend toolchain while staying out of production bundles.

Headless platform layer & swappable UISwappable UI

Sign-in state, permission checks, dictionary lookups, and API wrappers live in an integrity-verified layer, so you can replace component libraries or themes cleanly without breaking platform wiring.

Rule, scenario & mock cross-checksRepo guardrails

Automated checks verify that business rule IDs match your menus, mock handlers, and executable acceptance tests—catching missing thresholds or permission boundaries before handoff.

Adoption & branch handoff workflowSame repo

Adoption registers the frontend, imports menus and initial roles, and scaffolds the companion backend—preserving approved UI layouts while letting post-release fixes flow smoothly back to product.

Start from starter & adopt → · See the full product handoff workflow →

AGENT-LED ONBOARDING · ONE PROMPT TO START

Give your AI agent the first task

Choose the prompt matching your starting point and paste it into a terminal-capable coding agent (Claude Code, Codex, Cursor, Trae, etc.).

Path 1: Product-first mock frontend (no platform required)Requires Git + Node 22 + pnpm 10 · Clones starter & runs multi-role mock
text
Get the latest stable release of the Kaiwu frontend starter from https://github.com/kaiwuzaidao/kaiwu-web-starter (for example v0.3.0) and follow its AGENTS.md to initialize my project. Build an equipment booking frontend: employees can view free slots for a meeting-room projector, book a slot, or cancel their own booking, and two users booking overlapping slots see a clear conflict message. Run it with built-in mocks and give me the local clickable URL.
1. Clone starter & initAgent fetches the latest stable starter from GitHub and follows AGENTS.md
2. Local multi-role demoSwitch roles in the built-in mock panel, test flows, and record rules & scenarios
3. Hand off & adoptSubmit a handoff MR after review, then adopt the repo to generate the companion backend
Path 2: Start the platform & scaffold both reposRequires Docker Compose v2 · Fetches latest stable release & scaffolds your app
text
Get the latest stable Kaiwu release from https://github.com/kaiwuzaidao/kaiwu and follow AGENTS.md to start it locally. Ask what I want to build, then set up its backend and frontend.
1. Prepare the platformThe agent follows AGENTS.md to check prerequisites and start Kaiwu locally
2. Scaffold both reposIt asks what you want to build, then generates and pulls the backend & frontend Git repos
3. You confirm accessYou approve account authorization and review proposed code and manifest changes

For an existing project, use the feature development prompt →

See the CLI commands the agent runs behind the scenes

Left: product-first mock frontend followed by project adopt; right: platform-first dual-repo generation and sync:

1. Mock first in starter, then adopt

Initialize and review the frontend without a platform; then sign in at the entry repo to preview, adopt, and scaffold the companion backend.

node scripts/kaiwu-init.mjs --code booking --name "Booking"
cd ../booking-web && pnpm install --frozen-lockfile && pnpm dev
# After handoff, adopt from the entry repository:
./kaiwu login --client "project-development"
./kaiwu project adopt ../booking-web
./kaiwu project adopt ../booking-web --apply

2. Create dual repos from the platform

When Kaiwu is already running, scaffold both repos, mount them locally, and preview manifest updates before passing --apply.

./kaiwu login --client "project-development"
./kaiwu project new inventory --name "Inventory"
./kaiwu project status inventory --wait
./kaiwu project pull inventory
./kaiwu project-up ../business/inventory-service ../business/inventory-web
./kaiwu project sync ../business/inventory-service

See both startup walkthroughs · Start Kaiwu and sign in · Full CLI reference →

ARCHITECTURE & BOUNDARIES · DECOUPLED BY DESIGN

Independent apps on a shared platform

Read the diagram from top to bottom. Each frontend sends API requests through the shared gateway. The highlighted inventory project has its own frontend, backend and database alongside purchasing.

Browser and frontends

React · TypeScript · Umi Max · Ant Design
Platform workbenchkaiwu-system-web
Existing app · Equipment bookingbooking-web
New app · Inventoryinventory-web
Shared API gatewaykaiwu-gateway-service
Spring Cloud Gateway · WebFlux · Redis
Platform control planekaiwu-system-serviceMembers, permissions, project factorySpring Boot · MyBatis-Plus
Platform database
Existing app · Equipment bookingbooking-serviceEquipment reservationsSpring Boot · MyBatis-PlusSDK · kaiwu-system-starter
Equipment booking database
New app · Inventoryinventory-serviceStock receipts and countsSpring Boot · MyBatis-PlusSDK · kaiwu-system-starter
Inventory database
Product & AI build the screens and mock flows in inventory-web (from kaiwu-web-starter or Project Factory). Backend engineers keep that exact frontend, generate inventory-service via project adopt, and write counts to the inventory database. This example uses MySQL.
kaiwu Entry repository & CLI · platform startup and project adopt/synckaiwu-web-starter Frontend starter · zero-platform mock onboardingkaiwu-deploy Optional deployment repository · Kubernetes / Argo CD

Kaiwu Shared Platform (Control Plane & Starter SDK)

Kaiwu itself runs as a built-in project (project_code=system) under the exact same rules
Identity, Roles & Row-Level ScopeSSO & 60s signed Context; kaiwu-data-scope enforces role × dept SQL predicates on declared tables, reducing missed row filters in generated CRUD
Manifest Sync & Cross-Env HandoverSync kaiwu/*.yml from Git; export 6-file snapshots across environments with 3-way diff preview and explicit grant/delete checks
Project-Scoped Referenced i18n & DictsStore stable codes in DB; project-isolated i18n keys prevent dual-source drift and cross-project leakage
Object Storage (STS) & Safe ExcelLong-term keys stay in System; apps receive prefix-scoped STS tokens, store storage_ref instead of URLs, and parse XLSX safely
Unified Tasks, Scheduling & DM8Idempotent bizKey tasks (any-one/all-sign/overdue) & leased jobs; first-install choice of MySQL or Dameng DM8
Guarded Project AI AssistantSeparate PLAN / ANSWER model routing; permission- & row-scoped reads plus preview-before-write transactional ledger

For example, equipment booking and inventory share employee identities while assigning different project roles and data scopes. Teams choose how to deploy each service independently. Follow a request through the platform →

APPROACH COMPARISON · WHY NOT STARTER KITS OR LOW-CODE?

A second app for the same employees. What carries over?

Your purchasing app is live. Now you need an inventory app with the same employee accounts and its own stock-count rules:

ApproachHow screens go from review to productionHow employees get accessWhere stock-count rules change & evolve
RecommendedKaiwu + AI coding toolProduct & AI build persona-tested React screens in kaiwu-web-starter or a generated repo with built-in mocks, adopt via project adopt, and wire Spring Boot APIs with dev:real—UI library swappable, mocks stripped from prod builds.Connect inventory to the same gateway. Assign inventory roles, row-level data scopes (self / dept), and unified workbench tasks to existing staff.Your agent edits the standalone inventory repos, runs in-repo checks, previews project sync plans, and transfers dicts, menus, roles, and jobs from staging to prod with 3-way diff review.
Low-code platformConfigure forms in a visual designer and publish directly, though complex interactions and custom UI are bounded by the platform.An app built in the same workspace can reuse its identity and role model.Configure forms and workflows in the designer. Complex domain rules and audited cross-env config diffs face platform limits.
Backend starter kitProduct creates static wireframes, then dedicated frontend engineers rebuild every screen from scratch and realign API fields.A fresh copy includes login code, but sharing accounts, task inboxes, and STS storage across apps requires custom platform rework.Edit the copied inventory code. Projects diverge quickly, and syncing menus, dicts, and role changes from staging to prod relies on manual SQL.
AI coding tool aloneAI generates throwaway demos fast, but without shared authentication, permission wiring, dictionary integration, or Mock isolation, teams often rewrite them before release.Provide your existing identity APIs, row-level data scopes, and storage contracts to the tool every time, or design them from scratch.The tool can edit any source, while your team must supply and enforce three-way permission parity, SQL row scopes, cross-env config handover, and release gates.
CONTROLLABLE DELIVERY · SWAP ENGINEERS OR AI TOOLS WITHOUT DRIFT

In-repo guardrails keep code controllable across engineers and models

AI writes code fast, but long-term maintainability requires verifiable boundaries. Kaiwu embeds conventions, rules, and checks inside each repository so any developer or AI coding tool can take over cleanly without drift.

01

Keep the working context small

Project Factory and kaiwu-web-starter deliver standalone frontend and backend repos. An agent changing a feature starts directly with that project’s screens, APIs, and migrations.

02

Keep rules and decisions in the repo

Module boundaries, AGENTS.md, business-rules.md, acceptance-scenarios.md, and manifests travel with Git. Any developer or model can recover the exact conventions for that revision.

03

Enforce contracts and mock isolation at build time

Frontend pnpm verify:mock checks rule IDs, scenarios, @/kaiwu integrity, and dist isolation; pnpm verify and verify.sh enforce three-way permission parity with the backend.

DEVELOPER HANDBOOK · FROM INSTALL TO PRODUCTION

Developer handbook

Task-oriented guides covering prerequisites, commands, expected outcomes, and troubleshooting—structured for both developers and AI coding agents.

CLI Reference · AI Reading Index (llms.txt) · Full Handbook Markdown · Repository Map

Apache License 2.0