Skip to content

How Kaiwu works ​

Understand Kaiwu’s architecture, request lifecycle, and three core boundaries in 10 minutes.

1. Independent product and starter repositories ​

Kaiwu is not a giant monorepo. The entry repository only holds bootstrap scripts and orchestration; product source lives in independent Git repositories:

RepositoryRoleResponsibility
kaiwu-gateway-serviceSingle external entry (8088)Same-origin routing, JWT & session checks, signed internal Context
kaiwu-system-serviceControl plane backendUsers, projects, roles, menus, dictionaries, i18n, and Project Factory
kaiwu-system-webPlatform frontend (8000)Unified workbench, access center, dictionaries, i18n, and config UI
kaiwu-system-starterBusiness service SDKMaven dependency for business backends; local Context verification
kaiwu-web-starterProduct frontend starterZero-platform React starter with built-in /__mock/ runtime and @/kaiwu integration layer
kaiwu-deploy (optional)GitOps manifestsEnvironment overlays when deploying to Kubernetes / ArgoCD

2. How a request flows ​

Take an Order Center app opened from the workbench (/apps/order-center/). Its frontend calls a same-origin /order-center-api/ path:

  1. Web Nginx proxy: Browsers never connect directly to backend services; Nginx forwards /api and app APIs to Gateway.
  2. Session & membership check: Gateway validates the Access JWT and active Redis session, and verifies project membership with System (cached).
  3. 60-second signed Context: Gateway issues a short-lived (60s), audience-bound signed Context and forwards the request to the business service.
  4. Local verification in Starter: The business backend verifies the signature locally via Starter SDK, checks endpoint permissions, and can filter queries using the configured data scopes.
SymptomCheck order
Missing workbench entryEnabled project membership, registered app entry, and frontend mount path.
API returns 401Active session, request routed through Gateway, matching public key and audience.
API returns 403Role grants for the declared permission code, and a fresh session after grant changes.
Empty listOrganization, active project, row-level data scope, and business filters for the same member.

3. Three core design boundaries ​

Most architectural choices in Kaiwu come down to three boundaries:

  1. Gateway holds no permission truth: Gateway handles identity, sessions, and routing only. System is the single source of truth for permissions so rules never drift.
  2. Kaiwu itself is a project: Platform members, roles, and menus live under a built-in project (project_code=system) using the exact same tables and authorization path—no privileged bypass.
  3. Generated apps can leave the platform: Project Factory runs once per app—either scaffolding both repos (BASIC_SCAFFOLD via project new) or adopting a product-built frontend and generating only its companion backend (ADOPT_FRONTEND via project adopt). Kaiwu never overwrites your business code afterward.

4. Where product, AI, and guardrails fit ​

LLMs write code fast, but often miss permission wiring, database migrations, or CI contracts. Kaiwu separates product exploration from engineering enforcement:

  • Product-first frontend (Mock stage): Product & AI start from kaiwu-web-starter (with built-in Umi Mock runtime, 501 fallback, and /__mock/ persona switcher) and access platform hooks through the read-only @/kaiwu layer so UI libraries can be swapped cleanly. Rules (docs/business-rules.md) and scenarios (docs/acceptance-scenarios.md) are checked by pnpm verify:mock, pnpm test:scenarios, and pnpm test:browser on product before handing off via handoff/* MRs.
  • Adoption or blueprint generation: Engineers run ./kaiwu project adopt <frontend-dir> --apply to register an accepted frontend, import manifests/initial roles, and scaffold the Spring Boot service—or generate both repos deterministically from a validated ProjectBlueprint.
  • Real integration & cross-environment promotion: Both repos ship AGENTS.md, backend scripts/verify.sh, and frontend pnpm verify. Permission codes match across UI checks, kaiwu/menus.yml, and @RequirePermission, while DataScopeConventionTest checks declared ownership conventions and flags potentially undeclared endpoints. Engineers verify via pnpm dev:real and production image checks (/__mock/ returns 404), then promote dictionaries, menus, settings, role grants, jobs, and project-scoped i18n cleanly via project sync and Config Handover.

5. Built-in enterprise platform capabilities ​

Alongside independent repo delivery, every connected app can adopt Kaiwu’s shared capabilities on demand:

  • MySQL & Dameng DM8 dual database support: First-install choice for the platform control plane with a dedicated kaiwu-dm-migrator and preflight checks.
  • Cross-environment config handover (ADR 0042): 6-file YAML full snapshots with 3-way baseline diff previews, explicit opt-in for role grants and removals, and newly imported jobs disabled by default.
  • Role × department row-level data scope (kaiwu-data-scope): Gateway propagates signed ds claims and Starter injects SQL predicates automatically with zero runtime callbacks.
  • STS object storage & safe Excel: Long-term keys stay inside System; apps receive prefix-scoped STS tokens and store storage_ref + object_key instead of URLs, while kaiwu-excel rejects formulas and zip bombs.
  • Unified tasks & guarded AI assistant: TodoClient manages idempotent any-one/all-sign tasks, and the assistant separates PLAN and ANSWER models with permission-scoped reads and preview-before-write confirmation.

Next steps ​

Apache License 2.0