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:
| Repository | Role | Responsibility |
|---|---|---|
kaiwu-gateway-service | Single external entry (8088) | Same-origin routing, JWT & session checks, signed internal Context |
kaiwu-system-service | Control plane backend | Users, projects, roles, menus, dictionaries, i18n, and Project Factory |
kaiwu-system-web | Platform frontend (8000) | Unified workbench, access center, dictionaries, i18n, and config UI |
kaiwu-system-starter | Business service SDK | Maven dependency for business backends; local Context verification |
kaiwu-web-starter | Product frontend starter | Zero-platform React starter with built-in /__mock/ runtime and @/kaiwu integration layer |
kaiwu-deploy (optional) | GitOps manifests | Environment 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:
- Web Nginx proxy: Browsers never connect directly to backend services; Nginx forwards
/apiand app APIs to Gateway. - Session & membership check: Gateway validates the Access JWT and active Redis session, and verifies project membership with System (cached).
- 60-second signed Context: Gateway issues a short-lived (60s), audience-bound signed Context and forwards the request to the business service.
- 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.
| Symptom | Check order |
|---|---|
| Missing workbench entry | Enabled project membership, registered app entry, and frontend mount path. |
| API returns 401 | Active session, request routed through Gateway, matching public key and audience. |
| API returns 403 | Role grants for the declared permission code, and a fresh session after grant changes. |
| Empty list | Organization, 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:
- 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.
- 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. - Generated apps can leave the platform: Project Factory runs once per app—either scaffolding both repos (
BASIC_SCAFFOLDviaproject new) or adopting a product-built frontend and generating only its companion backend (ADOPT_FRONTENDviaproject 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@/kaiwulayer so UI libraries can be swapped cleanly. Rules (docs/business-rules.md) and scenarios (docs/acceptance-scenarios.md) are checked bypnpm verify:mock,pnpm test:scenarios, andpnpm test:browseronproductbefore handing off viahandoff/*MRs. - Adoption or blueprint generation: Engineers run
./kaiwu project adopt <frontend-dir> --applyto register an accepted frontend, import manifests/initial roles, and scaffold the Spring Boot service—or generate both repos deterministically from a validatedProjectBlueprint. - Real integration & cross-environment promotion: Both repos ship
AGENTS.md, backendscripts/verify.sh, and frontendpnpm verify. Permission codes match across UI checks,kaiwu/menus.yml, and@RequirePermission, whileDataScopeConventionTestchecks declared ownership conventions and flags potentially undeclared endpoints. Engineers verify viapnpm dev:realand production image checks (/__mock/returns 404), then promote dictionaries, menus, settings, role grants, jobs, and project-scoped i18n cleanly viaproject syncand 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-migratorand 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 signeddsclaims 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_keyinstead of URLs, whilekaiwu-excelrejects formulas and zip bombs. - Unified tasks & guarded AI assistant:
TodoClientmanages idempotent any-one/all-sign tasks, and the assistant separatesPLANandANSWERmodels with permission-scoped reads and preview-before-write confirmation.