CLAUDE.md

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

Project intent

vibe_erp is an ERP framework (not an ERP application) aimed at the printing industry. The goal is a pluggable platform on which any printing business — with its own workflows, forms, roles, and rules — can be assembled by configuration and plug-in modules, not by forking or rewriting the core.

The reference business in raw/业务流程设计文档/ is one example customer, not the spec. It must be treated as a fixture to validate that the framework can express such a workflow, never as a source of hard-coded entities or features in the core.

Top-level domains in the reference doc (use only as inspiration / test cases): 销售管理 (sales) · 采购管理 (purchasing) · 材料仓库管理 (raw material warehouse) · 成品仓库管理 (finished goods warehouse) · 生产管理 (production) · 工艺管理 (process/craft) · 车间管理 (workshop) · 设备管理 (equipment) · 品质管理 (quality) · 财务管理 (finance) · 项目管理 (project)

Architectural guardrails

These rules exist because the whole point of the project is reusability across customers. Violating them defeats the project.

1. Core stays domain-agnostic. No printing-specific entity, field, status, or workflow step belongs in the framework core. "Plate", "ink", "press", "color proof", etc. live in plug-in modules or configuration — never in core tables, core types, or core code paths.
2. Workflows are data, not code. State machines, approval chains, document routing, and form definitions must be declarative (config / DB / DSL) so a new customer can be onboarded by editing definitions, not by editing source.
3. Extensibility seams come first. Before adding any feature, identify the extension point (hook, plug-in interface, event, custom field, scripting hook) it should hang off of. If no seam exists yet, design the seam first, then implement the reference customer's behavior on top of it.
4. The reference customer is a test, not a requirement. When implementing something inspired by raw/业务流程设计文档/, ask: "Could a different printing shop with different rules also be expressed here without code changes?" If no, redesign.
5. Multi-tenant from day one in spirit. Even if deployment is single-tenant, data models and APIs should not assume one company, one workflow, or one form layout.
6. Global / i18n from day one. This codebase is the foundation of an ERP/EBC product intended to be sold worldwide. No hard-coded user-facing strings, no hard-coded currency, date format, time zone, number format, address shape, tax model, or language. All such concerns must go through localization, formatting, and configuration layers — even in the very first prototype. The reference docs being in Chinese does not mean Chinese is the primary or default locale; it is just one supported locale among many.
7. Clean Core. Borrowed from SAP S/4HANA's vocabulary: extensions never modify the core. The core is stable, generic, and upgrade-safe; everything customer-specific lives in plug-ins or in metadata rows. Extensions are graded A/B/C/D by upgrade safety:
   • A = Tier-1 metadata only (custom fields, forms, workflows, rules) — always upgrade-safe
   • B = Tier-2 plug-in using only the public api.v1.* surface — safe within a major version
   • C = Tier-2 plug-in using deprecated api.v1 symbols — safe until next major; loader emits warnings
   • D = Tier-2 plug-in reaching into platform.* or pbc.*.internal.* via reflection — UNSUPPORTED, rejected by the plug-in linter at install time
8. Two-tier extensibility, both first-class. The framework offers two extension paths and both must be designed for, not bolted on:
   • Tier 1 — key user / no-code: business analysts add fields, forms, list views, workflows, automation rules, custom entities, reports, and translations through the web UI. Everything is stored as rows in the metadata__* tables (Doctype-style), tagged source = 'user', scoped to their tenant. No build, no restart. The OpenAPI spec, REST API, and AI-agent function catalog auto-update from the metadata.
   • Tier 2 — developer / pro-code: PF4J JAR plug-ins. Plug-ins see only org.vibeerp.api.v1.*. Importing anything from platform.* or any PBC's internal package fails the plug-in linter.
9. PBC boundaries are sacred. Each core capability (pbc-identity, pbc-catalog, pbc-inventory, pbc-orders-sales, pbc-production, …) is its own Packaged Business Capability: own Gradle subproject, own table-name prefix, own bounded context, own public API surface. PBCs never import each other. Cross-PBC interaction goes through (a) the event bus or (b) service interfaces declared in api.v1.ext.<pbc>. The Gradle build enforces this — pbc-orders-sales cannot declare pbc-inventory as a dependency. This is what makes "modular monolith now, splittable later" real instead of aspirational.
10. api.v1 is the only stable contract. The package org.vibeerp.api.v1.* is the single semver-governed surface that plug-ins consume. It is published as api-v1.jar to Maven Central. Everything else in the codebase (platform.*, pbc.*.internal.*, every concrete Spring bean) is internal and may change in any release. Adding to api.v1 is allowed within a major version; renaming, removing, or behavior-changing anything in api.v1 is a major version bump. When in doubt, keep things OUT of api.v1; it is easier to grow the API deliberately than to maintain a regretted symbol forever.
11. AI agents are a first-class client. The framework is built so that the same business operations exposed via REST/OpenAPI are also callable by LLM-driven agents through an MCP server (or equivalent function-calling surface). The MCP endpoint itself is a v1.1 deliverable, but v1.0 must not architect it out — operations must be discoverable, typed, permission-checked, and locale-aware in a way that lets an agent call them safely. AI agents are listed alongside humans, web clients, mobile clients, and integrations as supported callers.

Working with the reference docs

• raw/业务流程设计文档/ is in Chinese. Module and process names are domain terms (e.g. 工艺 = process/craft, 车间 = workshop floor, 品质 = QC). Preserve original terminology when quoting; do not silently rename concepts when discussing them.
• Treat these documents as read-only reference material. Do not move, restructure, or "clean up" raw/.
• When the user asks for a feature "from the doc", confirm whether they want it built as a reference plug-in / fixture on top of the framework, or as a core capability — the answer is almost always the former.

Documentation discipline

Because this is a framework that other developers (and future-you) will build on, documentation is part of "done", not an afterthought. As the repo grows:

• Maintain a top-level docs/ tree alongside the code. At minimum it should cover: architecture overview, extension points / plug-in API, workflow & form definition format, configuration reference, i18n/localization guide, and a getting-started guide for onboarding a new customer.
• Every new extension point, plug-in interface, config key, or workflow primitive added to the core must ship with documentation in the same change. A PR that adds a public seam without docs is incomplete.
• Keep raw/业务流程设计文档/ separate from docs/. raw/ is one customer's business reference (read-only fixture). docs/ is the framework's own documentation, written in English by default with localization where appropriate.
• When a doc and the code disagree, treat it as a bug — fix whichever is wrong, do not silently let docs rot.

Stack and shape (decided, not yet built)

The architecture has been brainstormed, validated against 2026 ERP/EBC SOTA, and approved. The full design lives at docs/superpowers/specs/2026-04-07-vibe-erp-architecture-design.md and is the source of truth for everything below.

• Backend: Kotlin on the JVM, Spring Boot, single fat-JAR / single Docker image
• Workflow engine: Embedded Flowable (BPMN 2.0)
• Persistence: PostgreSQL (the only mandatory external dependency)
• Multi-tenancy: row-level tenant_id + Postgres Row-Level Security (defense in depth, same code path for self-host and hosted)
• Custom fields: JSONB ext column on every business table, described by metadata__custom_field rows; GIN-indexed
• Plug-in framework: PF4J + Spring Boot child contexts (classloader isolation per plug-in)
• i18n: ICU MessageFormat (ICU4J) + Spring MessageSource
• Reporting: JasperReports
• Auth: Built-in JWT + OIDC (Keycloak-compatible)
• Web client (v1): React + TypeScript SPA; mobile (React Native) is v2
• API: REST + OpenAPI; MCP server is v1.1 (seam exists in v1.0)

Topology: one Spring Boot process per instance, one Docker image per release, one mounted volume (/opt/vibe-erp/) for config/, plugins/, i18n-overrides/, files/, logs/. Customer extensions live outside the image. Upgrading vibe_erp = swapping the image; extensions and config stay put.

Module layout (Gradle multi-project):

vibe-erp/
├── api/api-v1/          ← THE CONTRACT (semver, published to Maven Central)
├── platform/*           ← Framework runtime (internal, not exposed to plug-ins)
├── pbc/*                ← Core PBCs: identity, catalog, partners, inventory,
│                          warehousing, orders-sales, orders-purchase,
│                          production, quality, finance
├── reference-customer/
│   └── plugin-printing-shop/   ← Reference plug-in expressing raw/业务流程设计文档/.
│                                  Built and CI-tested; NOT loaded by default.
├── web/                 ← React + TypeScript SPA
└── docs/                ← Framework documentation

Dependency rule (enforced by the Gradle build):

api/api-v1            depends on: nothing (Kotlin stdlib + jakarta.validation only)
platform/*            depends on: api/api-v1 + Spring + libs
pbc/*                 depends on: api/api-v1 + platform/*  (NEVER another pbc)
plugins (incl. ref)   depend on:  api/api-v1 only

Repository state

The repository currently contains the reference business documents under raw/, this CLAUDE.md, and the architecture spec at docs/superpowers/specs/2026-04-07-vibe-erp-architecture-design.md. There is no source code, build system, package manifest, test suite, or CI configuration yet. The next concrete step is an implementation plan, then bootstrapping the Gradle multi-project skeleton.

When source code is added, this file should be updated with: build/test/lint commands, the actual package name root (org.vibeerp is assumed but not yet committed), and any deviations from the design spec.

What to do when asked to "just add" a printing-specific feature

Stop and reframe. The correct shape is almost always:

• a generic mechanism in the core (e.g. "documents with configurable line items and a configurable approval workflow"), plus
• a plug-in / config bundle that uses that mechanism to express the specific printing-shop behavior.

If you cannot see how to split a request that way, ask the user before writing code.

The reference plug-in is the executable acceptance test

reference-customer/plugin-printing-shop/ is the framework's primary correctness test. It expresses the workflows in raw/业务流程设计文档/ using only api.v1. Two consequences:

• If a feature in pbc/* exists only to make this plug-in work, the design has failed guardrail #1 — that feature must move into the plug-in.
• If the plug-in needs to reach into a platform.* or pbc.* internal class, the seam is wrong and api.v1 needs to grow (deliberately, with a version bump consideration).

CI must build and load this plug-in in an integration test environment against a real Postgres on every PR. A green core build with a red printing-shop integration test is a release-blocker.